(gcrypt.info.gz) Cryptographic Functions

Info Catalog

(gcrypt.info.gz) Public key modules

(gcrypt.info.gz) Public Key cryptography (I)

(gcrypt.info.gz) General public-key related Functions

 
 7.4 Cryptographic Functions
 ===========================
 
 Note, that we will in future allow to use keys without p,q and u
 specified and may also support other parameters for performance reasons.
 
 Some functions operating on S-expressions support `flags', that
 influence the operation.  These flags have to be listed in a
 sub-S-expression named `flags'; the following flags are known:
 
 PKCS1
      Use PKCS#1 block type 2 padding.
 
 NO-BLINDING
      Do not use a technique called `blinding', which is used by default
      in order to prevent leaking of secret information.  Blinding is
      only implemented by RSA, but it might be implemented by other
      algorithms in the future as well, when necessary.
 
 Now that we know the key basics, we can carry on and explain how to
 encrypt and decrypt data.  In almost all cases the data is a random
 session key which is in turn used for the actual encryption of the real
 data.  There are 2 functions to do this:
 
  -- Function: gcry_error_t gcry_pk_encrypt (gcry_sexp_t *R_CIPH,
           gcry_sexp_t DATA, gcry_sexp_t PKEY)
      Obviously a public key must be provided for encryption.  It is
      expected as an appropriate S-expression (see above) in PKEY.  The
      data to be encrypted can either be in the simple old format, which
      is a very simple S-expression consisting only of one MPI, or it
      may be a more complex S-expression which also allows to specify
      flags for operation, like e.g. padding rules.
 
      If you don't want to let Libgcrypt handle the padding, you must
      pass an appropriate MPI using this expression for DATA:
 
           (data
             (flags raw)
             (value MPI))
 
      This has the same semantics as the old style MPI only way.  MPI is
      the actual data, already padded appropriate for your protocol.
      Most systems however use PKCS#1 padding and so you can use this
      S-expression for DATA:
 
           (data
             (flags pkcs1)
             (value BLOCK))
 
      Here, the "flags" list has the "pkcs1" flag which let the function
      know that it should provide PKCS#1 block type 2 padding.  The
      actual data to be encrypted is passed as a string of octets in
      BLOCK.  The function checks that this data actually can be used
      with the given key, does the padding and encrypts it.
 
      If the function could successfully perform the encryption, the
      return value will be 0 and a a new S-expression with the encrypted
      result is allocated and assign to the variable at the address of
      R_CIPH.  The caller is responsible to release this value using
      `gcry_sexp_release'.  In case of an error, an error code is
      returned and R_CIPH will be set to `NULL'.
 
      The returned S-expression has this format when used with RSA:
 
           (enc-val
             (rsa
               (a A-MPI)))
 
      Where A-MPI is an MPI with the result of the RSA operation.  When
      using the ElGamal algorithm, the return value will have this
      format:
 
           (enc-val
             (elg
               (a A-MPI)
               (b B-MPI)))
 
      Where A-MPI and B-MPI are MPIs with the result of the ElGamal
      encryption operation.
 
  -- Function: gcry_error_t gcry_pk_decrypt (gcry_sexp_t *R_PLAIN,
           gcry_sexp_t DATA, gcry_sexp_t SKEY)
      Obviously a private key must be provided for decryption.  It is
      expected as an appropriate S-expression (see above) in SKEY.  The
      data to be decrypted must match the format of the result as
      returned by `gcry_pk_encrypt', but should be enlarged with a
      `flags' element:
 
           (enc-val
             (flags)
             (elg
               (a A-MPI)
               (b B-MPI)))
 
      Note, that this function currently does not know of any padding
      methods and the caller must do any un-padding on his own.
 
      The function returns 0 on success or an error code.  The variable
      at the address of R_PLAIN will be set to NULL on error or receive
      the decrypted value on success.  The format of R_PLAIN is a simple
      S-expression part (i.e. not a valid one) with just one MPI if
      there was no `flags' element in DATA; if at least an empty `flags'
      is passed in DATA, the format is:
 
           (value PLAINTEXT)
 
    Another operation commonly performed using public key cryptography is
 signing data.  In some sense this is even more important than
 encryption because digital signatures are an important instrument for
 key management.  Libgcrypt supports digital signatures using 2
 functions, similar to the encryption functions:
 
  -- Function: gcry_error_t gcry_pk_sign (gcry_sexp_t *R_SIG,
           gcry_sexp_t DATA, gcry_sexp_t SKEY)
      This function creates a digital signature for DATA using the
      private key SKEY and place it into the variable at the address of
      R_SIG.  DATA may either be the simple old style S-expression with
      just one MPI or a modern and more versatile S-expression which
      allows to let Libgcrypt handle padding:
 
            (data
             (flags pkcs1)
             (hash HASH-ALGO BLOCK))
 
      This example requests to sign the data in BLOCK after applying
      PKCS#1 block type 1 style padding.  HASH-ALGO is a string with the
      hash algorithm to be encoded into the signature, this may be any
      hash algorithm name as supported by Libgcrypt.  Most likely, this
      will be "sha1", "rmd160" or "md5".  It is obvious that the length
      of BLOCK must match the size of that message digests; the function
      checks that this and other constraints are valid.
 
      If PKCS#1 padding is not required (because the caller does already
      provide a padded value), either the old format or better the
      following format should be used:
 
           (data
             (flags raw)
             (value MPI))
 
      Here, the data to be signed is directly given as an MPI.
 
      The signature is returned as a newly allocated S-expression in
      R_SIG using this format for RSA:
 
           (sig-val
             (rsa
               (s S-MPI)))
 
      Where S-MPI is the result of the RSA sign operation.  For DSA the
      S-expression returned is:
 
           (sig-val
             (dsa
               (r R-MPI)
               (s S-MPI)))
 
      Where R-MPI and S-MPI are the result of the DSA sign operation.
      For ElGamal signing (which is slow, yields large numbers and
      probably is not as secure as the other algorithms), the same
      format is used with "elg" replacing "dsa".
 
 The operation most commonly used is definitely the verification of a
 signature.  Libgcrypt provides this function:
 
  -- Function: gcry_error_t gcry_pk_verify (gcry_sexp_t SIG,
           gcry_sexp_t DATA, gcry_sexp_t PKEY)
      This is used to check whether the signature SIG matches the DATA.
      The public key PKEY must be provided to perform this verification.
      This function is similar in its parameters to `gcry_pk_sign' with
      the exceptions that the public key is used instead of the private
      key and that no signature is created but a signature, in a format
      as created by `gcry_pk_sign', is passed to the function in SIG.
 
      The result is 0 for success (i.e. the data matches the signature),
      or an error code where the most relevant code is
      `GCRYERR_BAD_SIGNATURE' to indicate that the signature does not
      match the provided data.
 
 

Info Catalog

(gcrypt.info.gz) Public key modules

(gcrypt.info.gz) Public Key cryptography (I)

(gcrypt.info.gz) General public-key related Functions