doc/README.apichanges

   1 README.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
   6 We decided to change a couple of annoying things in Libgcrypt and to
   7 cleanup the API.  The new API better fits into a multi-threaded
   8 environment and is more consistent.  One import change is that all
   9 functions return error codes from a set of error codes shared between
  10 GnuPG, GPGME and Libgcrypt.
  11
  12 This file contains some hints on how to port your application from
  13 libgcrypt <= 1.1.12 to the current API as of 1.1.42.  We hope that
  14 there 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