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

Info Catalog

(gcrypt.info.gz) Cryptographic Functions

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

 
 7.5 General public-key related Functions
 ========================================
 
 A couple of utility functions are available to retrieve the length of
 the key, map algorithm identifiers and perform sanity checks:
 
  -- Function: const char * gcry_pk_algo_name (int ALGO)
      Map the public key algorithm id ALGO to a string representation of
      the algorithm name.  For unknown algorithms this functions returns
      an empty string.
 
  -- Function: int gcry_pk_map_name (const char *NAME)
      Map the algorithm NAME to a public key algorithm Id.  Returns 0 if
      the algorithm name is not known.
 
  -- Function: int gcry_pk_test_algo (int ALGO)
      Return 0 if the public key algorithm ALGO is available for use.
      Note, that this is implemented as a macro.
 
  -- Function: unsigned int gcry_pk_get_nbits (gcry_sexp_t KEY)
      Return what is commonly referred as the key length for the given
      public or private in KEY.
 
  -- Function: unsigned char * gcry_pk_get_keygrip (gcry_sexp_t KEY,
           unsigned char *ARRAY)
      Return the so called "keygrip" which is the SHA-1 hash of the
      public key parameters expressed in a way depended on the
      algorithm.  ARRAY must either provide space for 20 bytes or
      `NULL;'. In the latter case a newly allocated array of that size
      is returned.  On success a pointer to the newly allocated space or
      to ARRAY is returned.  `NULL' is returned to indicate an error
      which is most likely an unknown algorithm or one where a "keygrip"
      has not yet been defined.  The function accepts public or secret
      keys in KEY.
 
  -- Function: gcry_error_t gcry_pk_testkey (gcry_sexp_t KEY)
      Return zero if the private key KEY is `sane', an error code
      otherwise.  Note, that it is not possible to chek the `saneness'
      of a public key.
 
 
  -- Function: int gcry_pk_algo_info (int ALGO, int WHAT, void *BUFFER,
           size_t *NBYTES)
      Depending on the value of WHAT return various information about
      the public key algorithm with the id ALGO.  Note, that the
      function returns `-1' on error and the actual error code must be
      retrieved using the function `gcry_errno'.  The currently defined
      values for WHAT are:
 
     `GCRYCTL_TEST_ALGO:'
           Return 0 when the specified algorithm is available for use.
           BUFFER must be `NULL', NBYTES may be passed as `NULL' or
           point to a variable with the required usage of the algorithm.
           This may be 0 for "don't care" or the bit-wise OR of these
           flags:
 
          `GCRY_PK_USAGE_SIGN'
                Algorithm is usable for signing.
 
          `GCRY_PK_USAGE_ENCR'
                Algorithm is usable for encryption.
 
     `GCRYCTL_GET_ALGO_USAGE:'
           Return the usage flags for the given algorithm.  An invalid
           algorithm return 0.  Disabled algorithms are ignored here
           because we want to know whether the algorithm is at all
           capable of a certain usage.
 
     `GCRYCTL_GET_ALGO_NPKEY'
           Return the number of elements the public key for algorithm
           ALGO consist of.  Return 0 for an unknown algorithm.
 
     `GCRYCTL_GET_ALGO_NSKEY'
           Return the number of elements the private key for algorithm
           ALGO consist of.  Note that this value is always larger than
           that of the public key.  Return 0 for an unknown algorithm.
 
     `GCRYCTL_GET_ALGO_NSIGN'
           Return the number of elements a signature created with the
           algorithm ALGO consists of.  Return 0 for an unknown
           algorithm or for an algorithm not capable of creating
           signatures.
 
     `GCRYCTL_GET_ALGO_NENC'
           Return the number of elements a encrypted message created
           with the algorithm ALGO consists of.  Return 0 for an unknown
           algorithm or for an algorithm not capable of encryption.
 
      Please note that parameters not required should be passed as
      `NULL'.
 
  -- Function: gcry_error_t gcry_pk_ctl (int CMD, void *BUFFER,
           size_t BUFLEN)
      This is a general purpose function to perform certain control
      operations.  CMD controls what is to be done. The return value is
      0 for success or an error code.  Currently supported values for
      CMD are:
 
     `GCRYCTL_DISABLE_ALGO'
           Disable the algorithm given as an algorithm id in BUFFER.
           BUFFER must point to an `int' variable with the algorithm id
           and BUFLEN must have the value `sizeof (int)'.
 
 
 Libgcrypt also provides a function for generating public key pairs:
 
  -- Function: gcry_error_t gcry_pk_genkey (gcry_sexp_t *R_KEY,
           gcry_sexp_t PARMS)
      This function create a new public key pair using information given
      in the S-expression PARMS and stores the private and the public key
      in one new S-expression at the address given by R_KEY.  In case of
      an error, R_KEY is set to `NULL'.  The return code is 0 for
      success or an error code otherwise.
 
      Here is an example for PARMS for creating a 1024 bit RSA key:
 
           (genkey
             (rsa
               (nbits 4:1024)))
 
      To create an ElGamal key, substitute "elg" for "rsa" and to create
      a DSA key use "dsa".  Valid ranges for the key length depend on the
      algorithms; all commonly used key lengths are supported.  Currently
      supported parameters are:
 
     `nbits'
           This is always required to specify the length of the key.
           The argument is a string with a number in C-notation.
 
     `rsa-use-e'
           This is only used with RSA to give a hint for the public
           exponent. The value will be used as a base to test for a
           usable exponent. Some values are special:
 
          `0'
                Use a secure and fast value.  This is currently the
                number 41.
 
          `1'
                Use a secure value as required by some specification.
                This is currently the number 65537.
 
          `2'
                Reserved
 
           If this parameter is not used, Libgcrypt uses for historic
           reasons 65537.
 
 
      The key pair is returned in a format depending on the algorithm.
      Both private and public keys are returned in one container and may
      be accompanied by some miscellaneous information.
 
      As an example, here is what the ElGamal key generation returns:
 
           (key-data
             (public-key
               (elg
                 (p P-MPI)
                 (g G-MPI)
                 (y Y-MPI)))
             (private-key
               (elg
                 (p P-MPI)
                 (g G-MPI)
                 (y Y-MPI)
                 (x X-MPI)))
             (misc-key-info
               (pm1-factors N1 N2 ... NN)))
 
      As you can see, some of the information is duplicated, but this
      provides an easy way to extract either the public or the private
      key.  Note that the order of the elements is not defined, e.g. the
      private key may be stored before the public key. N1 N2 ... NN is a
      list of prime numbers used to composite P-MPI; this is in general
      not a very useful information.
 

Info Catalog

(gcrypt.info.gz) Cryptographic Functions

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