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