* random.c (gcry_random_add_bytes): Return if buflen is zero to
[libgcrypt.git] / README.apichanges
1 README.apichanges 2003-07-28
2
3
4 We decided to change a couple of annoying things in Libgcrypt and to
5 cleanup the API.  The new API better fits into a multi-threaded
6 environment and is more consistent.  One import change is that all
7 functions return error codes from a set of error codes shared between
8 GnuPG, GPGME and Libgcrypt.
9
10 This file contains some hints on how to port your application from
11 libgcrypt <= 1.1.12 to the current API as of 1.1.42.  We hope that
12 there won't be another need for such a major change.
13
14
15 * Types
16
17   All types definitions changed to a foo_t scheme; for some time we
18   will support the old names but you better start to rename them:
19
20   s/GCRY_MPI/gcry_mpi_t/
21   s/GcryMPI/gcry_mpi_t/
22   s/GCRY_SEXP/gcry_sexp_t/
23   s/GcrySexp/gcry_sexp_t/
24   s/GCRY_CIPHER_HD/gcry_cipher_hd_t/
25   s/GcryCipherHd/gcry_cipher_hd_t/
26   s/GCRY_MD_HD/gcry_md_hd_t/
27   s/GcryMDHd/gcry_md_hd_t/
28
29 * Initialization
30
31   For proper initialization of the library, you must call
32   gcry_check_version() before calling any other function except for a
33   these gcry_control operations:
34      GCRYCTL_SUSPEND_SECMEM_WARN
35      GCRYCTL_DISABLE_INTERNAL_LOCKING
36      GCRYCTL_ANY_INITIALIZATION_P
37      GCRYCTL_INITIALIZATION_FINISHED_P
38
39
40 * Handles
41
42   gcry_cipher_open and gcry_md_open do now return an error code
43   instead of a NULL handle; the handle is now returned by
44   asigning it to the first argument.  Example on how to change your
45   code:
46
47   Old:
48
49     hd = gcry_md_open (algo, flags);
50     if (!hd)
51       {
52          fprintf (stderr, "md_open failed: %s\n", gcry_errno (-1));
53          ....
54
55   New:
56
57     rc = gcry_md_open (&hd, algo, flags);
58     if (rc)
59       {
60          fprintf (stderr, "md_open failed: %s\n", gcry_strerror (rc));
61          ....
62
63   If you are not interested in the error code, you can do it in a
64   simplified way:
65  
66     gcry_md_open (&hd, algo, flags);
67     if (!hd)
68         abort ();
69
70   i.e. the function makes sure that HD points to NULL in case of an error.
71   The required change for gcry_cipher_open is similar.
72
73 * Message Digests
74
75   The order of the arguments to gcry_md_copy has been changed in order
76   to be more consistent with other functions of this type.  This means
77   that the new message digest handle will be a copy of the message
78   handle specified by the second argument and stored at the address
79   pointed to by the first argument.
80
81 * Error codes
82
83   gcry_errno () has been removed because it is hard to use in
84   multi-threaded environment.  You need to save the error code
85   returned by the functions and use it either numerical or passing it
86   to gcry_strerror (since gcry_strerror is a wrapper function for
87   gpg_strerror, the latter function can also be used).
88
89   Instead of using the error codes GCRYERR_*, you have to use the
90   GPG_ERR_* names. 
91
92 * S-expressions
93
94   gcry_sexp_canon_len used to return a `historical' error code in
95   `errcode', this is not the case anymore; the value returned in
96   `errcode' is now a standard Libgcrypt (i.e. gpg-error) error code.
97
98 * MPI
99
100   gcry_mpi_scan and gcry_mpi_print need the size of a provided buffer
101   as input and return the number of bytes actually scanned/printed to
102   the user.  The old API used a single size_t Pointer for both tasks,
103   the new API distinguishes between the input and the output values.
104
105 * Public Key cryptography
106
107   gcry_pk_decrypt used to return a `simple S-expression part' that
108   contains a single MPI value.  In case the `data' S-expression
109   contains a `flags' element, the result S-expression is filled with a
110   complete S-expression of the following format:
111
112     (value PLAINTEXT)
113