(gcrypt.info) Working with cipher handles

Info Catalog (gcrypt.info) Available cipher modes (gcrypt.info) Symmetric cryptography (gcrypt.info) General cipher functions
 
 Working with cipher handles
 ===========================
 
 To use a cipher algorithm, you must first allocate an according handle.
 This is to be done using the open function:
 
  - Function: gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *HD,
      int ALGO, int MODE, unsigned int FLAGS)
 
      This function creates the context handle required for most of the
      other cipher functions and returns a handle to it in `hd'.  In
      case of an error, an according error code is returned.
 
      The ID of algorithm to use must be specified via ALGO.  See 
      Available ciphers, for a list of supported ciphers and the
      according constants.
 
      Besides using the constants directly, the function
      `gcry_cipher_map_name' may be used to convert the textual name of
      an algorithm into the according numeric ID.
 
      The cipher mode to use must be specified via MODE.  See 
      Available cipher modes, for a list of supported cipher modes and
      the according constants.  Note, that some modes do not work
      together with all algorithms.
 
      The third argument FLAGS can either be passed as `0' or as the
      bit-wise OR of the following constants.
 
     `GCRY_CIPHER_SECURE'
           Make sure that all operations are allocated in secure memory.
           This is useful, when the key material is highly confidential.
 
     `GCRY_CIPHER_ENABLE_SYNC'
           This flag enables the CFB sync mode, which is a special
           feature of Libgcrypt's CFB mode implementation to allow for
           OpenPGP's CFB variant.  See `gcry_cipher_sync'.
 
     `GCRY_CIPHER_CBC_CTS'
           Enable cipher text stealing (CTS) for the CBC mode.  Cannot
           be used simultaneous as GCRY_CIPHER_CBC_MAC
 
     `GCRY_CIPHER_CBC_MAC'
           Compute CBC-MAC keyed checksums.  This is the same as CBC
           mode, but only output the last block.  Cannot be used
           simultaneous as GCRY_CIPHER_CBC_CTS.
 
    Use the following function to release an existing handle:
 
  - Function: void gcry_cipher_close (gcry_cipher_hd_t H)
      This function releases the context created by `gcry_cipher_open'.
 
    In order to use a handle for performing cryptographic operations, a
 `key' has to be set first:
 
  - Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t H, void
           *K, size_t L)
      Set the key K used for encryption or decryption in the context
      denoted by the handle H.  The length L of the key K must match the
      required length of the algorithm set for this context or be in the
      allowed range for algorithms with variable key size.  The function
      checks this and returns an error if there is a problem.  A caller
      should always check for an error.
 
      Note, this is currently implemented as a macro but may be changed
      to a function in the future.
 
    Most crypto modes requires an initialization vector (IV), which
 usually is a non-secret random string acting as a kind of salt value.
 The CTR mode requires a counter, which is also similar to a salt value.
 To set the IV or CTR, use these functions:
 
  - Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t H, void
           *K, size_t L)
      Set the initialization vector used for encryption or decryption.
      The vector is passed as the buffer K of length L and copied to
      internal data structures.  The function checks that the IV matches
      the requirement of the selected algorithm and mode.  Note, that
      this is implemented as a macro.
 
  - Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H, void
           *C, size_t L)
      Set the counter vector used for encryption or decryption. The
      counter is passed as the buffer C of length L and copied to
      internal data structures.  The function checks that the counter
      matches the requirement of the selected algorithm (i.e., it must be
      the same size as the block size).  Note, that this is implemented
      as a macro.
 
  - Function: gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t H)
      Set the given handle's context back to the state it had after the
      last call to gcry_cipher_setkey and clear the initialization
      vector.
 
      Note, that gcry_cipher_reset is implemented as a macro.
 
    The actual encryption and decryption is done by using one of the
 following functions.  They may be used as often as required to process
 all the data.
 
  - Function: gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t H,
           unsigned char *out, size_t OUTSIZE, const unsigned char *IN,
           size_t INLEN)
      `gcry_cipher_encrypt' is used to encrypt the data.  This function
      can either work in place or with two buffers.  It uses the cipher
      context already setup and described by the handle H.  There are 2
      ways to use the function: If IN is passed as `NULL' and INLEN is
      `0', in-place encryption of the data in OUT or length OUTSIZE
      takes place.  With IN being not `NULL', INLEN bytes are encrypted
      to the buffer OUT which must have at least a size of INLEN.
      OUTLEN must be set to the allocated size of OUT, so that the
      function can check that there is sufficient space. Note, that
      overlapping buffers are not allowed.
 
      Depending on the selected algorithms and encryption mode, the
      length of the buffers must be a multiple of the block size.
 
      The function returns `0' on success or an error code.
 
  - Function: gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t H,
           unsigned char *out, size_t OUTSIZE, const unsigned char *IN,
           size_t INLEN)
      `gcry_cipher_decrypt' is used to decrypt the data.  This function
      can either work in place or with two buffers.  It uses the cipher
      context already setup and described by the handle H.  There are 2
      ways to use the function: If IN is passed as `NULL' and INLEN is
      `0', in-place decryption of the data in OUT or length OUTSIZE
      takes place.  With IN being not `NULL', INLEN bytes are decrypted
      to the buffer OUT which must have at least a size of INLEN.
      OUTLEN must be set to the allocated size of OUT, so that the
      function can check that there is sufficient space. Note, that
      overlapping buffers are not allowed.
 
      Depending on the selected algorithms and encryption mode, the
      length of the buffers must be a multiple of the block size.
 
      The function returns `0' on success or an error code.
 
    OpenPGP (as defined in RFC-2440) requires a special sync operation in
 some places, the following function is used for this:
 
  - Function: gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t H)
      Perform the OpenPGP sync operation on context H. Note, that this
      is a no-op unless the context was created with the flag
      `GCRY_CIPHER_ENABLE_SYNC'
 
    Some of the described functions are implemented as macros utilizing a
 catch-all control function.  This control function is rarely used
 directly but there is nothing which would inhibit it:
 
  - Function: gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t H, int CMD,
           void *BUFFER, size_t BUFLEN)
      `gcry_cipher_ctl' controls various aspects of the cipher module and
      specific cipher contexts.  Usually some more specialized functions
      or macros are used for this purpose.  The semantics of the
      function and its parameters depends on the the command CMD and the
      passed context handle H.  Please see the comments in the source
      code (`src/global.c') for details.
 
  - Function: gcry_error_t gcry_cipher_info (gcry_cipher_hd_t H, int
           WHAT, void *BUFFER, size_t *NBYTES)
      `gcry_cipher_info' is used to retrieve various information about a
      cipher context or the cipher module in general.
 
      Currently no information is available.
 
Info Catalog (gcrypt.info) Available cipher modes (gcrypt.info) Symmetric cryptography (gcrypt.info) General cipher functions
automatically generated by info2html