Removed the module registration interface
[libgcrypt.git] / doc / gcrypt.texi
index 1de87fa..14f6fd1 100644 (file)
@@ -614,7 +614,6 @@ If the logging verbosity level of Libgcrypt has been set to at least
 
 @menu
 * Controlling the library::     Controlling Libgcrypt's behavior.
-* Modules::                     Description of extension modules.
 * Error Handling::              Error codes and such.
 @end menu
 
@@ -857,25 +856,6 @@ command must be used at initialization time; i.e. before calling
 
 @end deftypefun
 
-@node Modules
-@section Modules
-
-Libgcrypt supports the use of `extension modules', which
-implement algorithms in addition to those already built into the library
-directly.
-
-@deftp {Data type} gcry_module_t
-This data type represents a `module'.
-@end deftp
-
-Functions registering modules provided by the user take a `module
-specification structure' as input and return a value of
-@code{gcry_module_t} and an ID that is unique in the modules'
-category.  This ID can be used to reference the newly registered
-module.  After registering a module successfully, the new functionality
-should be able to be used through the normal functions provided by
-Libgcrypt until it is unregistered again.
-
 @c **********************************************************
 @c *******************  Errors  ****************************
 @c **********************************************************
@@ -1430,7 +1410,6 @@ building blocks provided by Libgcrypt.
 
 @menu
 * Available ciphers::           List of ciphers supported by the library.
-* Cipher modules::              How to work with cipher modules.
 * Available cipher modes::      List of cipher modes supported by the library.
 * Working with cipher handles::  How to perform operations related to cipher handles.
 * General cipher functions::    General cipher functions independent of cipher handles.
@@ -1537,119 +1516,6 @@ The Camellia cipher by NTT.  See
 
 @end table
 
-@node Cipher modules
-@section Cipher modules
-
-Libgcrypt makes it possible to load additional `cipher modules'; these
-ciphers can be used just like the cipher algorithms that are built
-into the library directly.  For an introduction into extension
-modules, see @xref{Modules}.
-
-@deftp {Data type} gcry_cipher_spec_t
-This is the `module specification structure' needed for registering
-cipher modules, which has to be filled in by the user before it can be
-used to register a module.  It contains the following members:
-
-@table @code
-@item const char *name
-The primary name of the algorithm.
-@item const char **aliases
-A list of strings that are `aliases' for the algorithm.  The list must
-be terminated with a NULL element.
-@item gcry_cipher_oid_spec_t *oids
-A list of OIDs that are to be associated with the algorithm.  The
-list's last element must have it's `oid' member set to NULL.  See
-below for an explanation of this type.
-@item size_t blocksize
-The block size of the algorithm, in bytes.
-@item size_t keylen
-The length of the key, in bits.
-@item size_t contextsize
-The size of the algorithm-specific `context', that should be allocated
-for each handle.
-@item gcry_cipher_setkey_t setkey
-The function responsible for initializing a handle with a provided
-key.  See below for a description of this type.
-@item gcry_cipher_encrypt_t encrypt
-The function responsible for encrypting a single block.  See below for
-a description of this type.
-@item gcry_cipher_decrypt_t decrypt
-The function responsible for decrypting a single block.  See below for
-a description of this type.
-@item gcry_cipher_stencrypt_t stencrypt
-Like `encrypt', for stream ciphers.  See below for a description of
-this type.
-@item gcry_cipher_stdecrypt_t stdecrypt
-Like `decrypt', for stream ciphers.  See below for a description of
-this type.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_cipher_oid_spec_t
-This type is used for associating a user-provided algorithm
-implementation with certain OIDs.  It contains the following members:
-@table @code
-@item const char *oid
-Textual representation of the OID.
-@item int mode
-Cipher mode for which this OID is valid.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_cipher_setkey_t
-Type for the `setkey' function, defined as: gcry_err_code_t
-(*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned
-keylen)
-@end deftp
-
-@deftp {Data type} gcry_cipher_encrypt_t
-Type for the `encrypt' function, defined as: gcry_err_code_t
-(*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const
-unsigned char *inbuf)
-@end deftp
-
-@deftp {Data type} gcry_cipher_decrypt_t
-Type for the `decrypt' function, defined as: gcry_err_code_t
-(*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const
-unsigned char *inbuf)
-@end deftp
-
-@deftp {Data type} gcry_cipher_stencrypt_t
-Type for the `stencrypt' function, defined as: gcry_err_code_t
-(*gcry_@/cipher_@/stencrypt_@/t) (void *c, const unsigned char *outbuf, const
-unsigned char *, unsigned int n)
-@end deftp
-
-@deftp {Data type} gcry_cipher_stdecrypt_t
-Type for the `stdecrypt' function, defined as: gcry_err_code_t
-(*gcry_@/cipher_@/stdecrypt_@/t) (void *c, const unsigned char *outbuf, const
-unsigned char *, unsigned int n)
-@end deftp
-
-@deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
-
-Register a new cipher module whose specification can be found in
-@var{cipher}.  On success, a new algorithm ID is stored in
-@var{algorithm_id} and a pointer representing this module is stored
-in @var{module}.  Deprecated; the module register interface will be
-removed in a future version.
-@end deftypefun
-
-@deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
-Unregister the cipher identified by @var{module}, which must have been
-registered with gcry_cipher_register.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
-Get a list consisting of the IDs of the loaded cipher modules.  If
-@var{list} is zero, write the number of loaded cipher modules to
-@var{list_length} and return.  If @var{list} is non-zero, the first
-*@var{list_length} algorithm IDs are stored in @var{list}, which must
-be of according size.  In case there are less cipher modules than
-*@var{list_length}, *@var{list_length} is updated to the correct
-number.
-@end deftypefun
-
 @node Available cipher modes
 @section Available cipher modes
 
@@ -1994,7 +1860,6 @@ S-expressions.
 @menu
 * Available algorithms::        Algorithms supported by the library.
 * Used S-expressions::          Introduction into the used S-expression.
-* Public key modules::          How to work with public key modules.
 * Cryptographic Functions::     Functions for performing the cryptographic actions.
 * General public-key related Functions::  General functions, not implementing any cryptography.
 @end menu
@@ -2233,139 +2098,6 @@ As usual the OIDs may optionally be prefixed with the string @code{OID.}
 or @code{oid.}.
 
 
-
-@node Public key modules
-@section Public key modules
-
-Libgcrypt makes it possible to load additional `public key
-modules'; these public key algorithms can be used just like the
-algorithms that are built into the library directly.  For an
-introduction into extension modules, see @xref{Modules}.
-
-@deftp {Data type} gcry_pk_spec_t
-This is the `module specification structure' needed for registering
-public key modules, which has to be filled in by the user before it
-can be used to register a module.  It contains the following members:
-
-@table @code
-@item const char *name
-The primary name of this algorithm.
-@item char **aliases
-A list of strings that are `aliases' for the algorithm.  The list
-must be terminated with a NULL element.
-@item const char *elements_pkey
-String containing the one-letter names of the MPI values contained in
-a public key.
-@item const char *element_skey
-String containing the one-letter names of the MPI values contained in
-a secret key.
-@item const char *elements_enc
-String containing the one-letter names of the MPI values that are the
-result of an encryption operation using this algorithm.
-@item const char *elements_sig
-String containing the one-letter names of the MPI values that are the
-result of a sign operation using this algorithm.
-@item const char *elements_grip
-String containing the one-letter names of the MPI values that are to
-be included in the `key grip'.
-@item int use
-The bitwise-OR of the following flags, depending on the abilities of
-the algorithm:
-@table @code
-@item GCRY_PK_USAGE_SIGN
-The algorithm supports signing and verifying of data.
-@item GCRY_PK_USAGE_ENCR
-The algorithm supports the encryption and decryption of data.
-@end table
-@item gcry_pk_generate_t generate
-The function responsible for generating a new key pair.  See below for
-a description of this type.
-@item gcry_pk_check_secret_key_t check_secret_key
-The function responsible for checking the sanity of a provided secret
-key.  See below for a description of this type.
-@item gcry_pk_encrypt_t encrypt
-The function responsible for encrypting data.  See below for a
-description of this type.
-@item gcry_pk_decrypt_t decrypt
-The function responsible for decrypting data.  See below for a
-description of this type.
-@item gcry_pk_sign_t sign
-The function responsible for signing data.  See below for a description
-of this type.
-@item gcry_pk_verify_t verify
-The function responsible for verifying that the provided signature
-matches the provided data.  See below for a description of this type.
-@item gcry_pk_get_nbits_t get_nbits
-The function responsible for returning the number of bits of a provided
-key.  See below for a description of this type.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_pk_generate_t
-Type for the `generate' function, defined as: gcry_err_code_t
-(*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long
-use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)
-@end deftp
-
-@deftp {Data type} gcry_pk_check_secret_key_t
-Type for the `check_secret_key' function, defined as: gcry_err_code_t
-(*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)
-@end deftp
-
-@deftp {Data type} gcry_pk_encrypt_t
-Type for the `encrypt' function, defined as: gcry_err_code_t
-(*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
-gcry_mpi_t *pkey, int flags)
-@end deftp
-
-@deftp {Data type} gcry_pk_decrypt_t
-Type for the `decrypt' function, defined as: gcry_err_code_t
-(*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data,
-gcry_mpi_t *skey, int flags)
-@end deftp
-
-@deftp {Data type} gcry_pk_sign_t
-Type for the `sign' function, defined as: gcry_err_code_t
-(*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
-gcry_mpi_t *skey)
-@end deftp
-
-@deftp {Data type} gcry_pk_verify_t
-Type for the `verify' function, defined as: gcry_err_code_t
-(*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data,
-gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)
-@end deftp
-
-@deftp {Data type} gcry_pk_get_nbits_t
-Type for the `get_nbits' function, defined as: unsigned
-(*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)
-@end deftp
-
-@deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})
-
-Register a new public key module whose specification can be found in
-@var{pubkey}.  On success, a new algorithm ID is stored in
-@var{algorithm_id} and a pointer representing this module is stored in
-@var{module}.  Deprecated; the module register interface will be
-removed in a future version.
-
-@end deftypefun
-
-@deftypefun void gcry_pk_unregister (gcry_module_t @var{module})
-Unregister the public key module identified by @var{module}, which
-must have been registered with gcry_pk_register.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})
-Get a list consisting of the IDs of the loaded pubkey modules.  If
-@var{list} is zero, write the number of loaded pubkey modules to
-@var{list_length} and return.  If @var{list} is non-zero, the first
-*@var{list_length} algorithm IDs are stored in @var{list}, which must
-be of according size.  In case there are less pubkey modules than
-*@var{list_length}, *@var{list_length} is updated to the correct
-number.
-@end deftypefun
-
 @node Cryptographic Functions
 @section Cryptographic Functions
 
@@ -2960,7 +2692,6 @@ are also supported.
 
 @menu
 * Available hash algorithms::   List of hash algorithms supported by the library.
-* Hash algorithm modules::      How to work with hash algorithm modules.
 * Working with hash algorithms::  List of functions related to hashing.
 @end menu
 
@@ -3064,107 +2795,6 @@ bytes.
 @end table
 @c end table of hash algorithms
 
-@node Hash algorithm modules
-@section Hash algorithm modules
-
-Libgcrypt makes it possible to load additional `message
-digest modules'; these digests can be used just like the message digest
-algorithms that are built into the library directly.  For an
-introduction into extension modules, see @xref{Modules}.
-
-@deftp {Data type} gcry_md_spec_t
-This is the `module specification structure' needed for registering
-message digest modules, which has to be filled in by the user before
-it can be used to register a module.  It contains the following
-members:
-
-@table @code
-@item const char *name
-The primary name of this algorithm.
-@item unsigned char *asnoid
-Array of bytes that form the ASN OID.
-@item int asnlen
-Length of bytes in `asnoid'.
-@item gcry_md_oid_spec_t *oids
-A list of OIDs that are to be associated with the algorithm.  The
-list's last element must have it's `oid' member set to NULL.  See
-below for an explanation of this type.  See below for an explanation
-of this type.
-@item int mdlen
-Length of the message digest algorithm.  See below for an explanation
-of this type.
-@item gcry_md_init_t init
-The function responsible for initializing a handle.  See below for an
-explanation of this type.
-@item gcry_md_write_t write
-The function responsible for writing data into a message digest
-context.  See below for an explanation of this type.
-@item gcry_md_final_t final
-The function responsible for `finalizing' a message digest context.
-See below for an explanation of this type.
-@item gcry_md_read_t read
-The function responsible for reading out a message digest result.  See
-below for an explanation of this type.
-@item size_t contextsize
-The size of the algorithm-specific `context', that should be
-allocated for each handle.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_md_oid_spec_t
-This type is used for associating a user-provided algorithm
-implementation with certain OIDs.  It contains the following members:
-
-@table @code
-@item const char *oidstring
-Textual representation of the OID.
-@end table
-@end deftp
-
-@deftp {Data type} gcry_md_init_t
-Type for the `init' function, defined as: void (*gcry_md_init_t) (void
-*c)
-@end deftp
-
-@deftp {Data type} gcry_md_write_t
-Type for the `write' function, defined as: void (*gcry_md_write_t)
-(void *c, unsigned char *buf, size_t nbytes)
-@end deftp
-
-@deftp {Data type} gcry_md_final_t
-Type for the `final' function, defined as: void (*gcry_md_final_t)
-(void *c)
-@end deftp
-
-@deftp {Data type} gcry_md_read_t
-Type for the `read' function, defined as: unsigned char
-*(*gcry_md_read_t) (void *c)
-@end deftp
-
-@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
-
-Register a new digest module whose specification can be found in
-@var{digest}.  On success, a new algorithm ID is stored in
-@var{algorithm_id} and a pointer representing this module is stored
-in @var{module}.  Deprecated; the module register interface will be
-removed in a future version.
-@end deftypefun
-
-@deftypefun void gcry_md_unregister (gcry_module_t @var{module})
-Unregister the digest identified by @var{module}, which must have been
-registered with gcry_md_register.
-@end deftypefun
-
-@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
-Get a list consisting of the IDs of the loaded message digest modules.
-If @var{list} is zero, write the number of loaded message digest
-modules to @var{list_length} and return.  If @var{list} is non-zero,
-the first *@var{list_length} algorithm IDs are stored in @var{list},
-which must be of according size.  In case there are less message
-digests modules than *@var{list_length}, *@var{list_length} is updated
-to the correct number.
-@end deftypefun
-
 @node Working with hash algorithms
 @section Working with hash algorithms
 
@@ -4502,18 +4132,13 @@ Create a new public/private key pair.
 
 @end table
 
-With the help of the module registration system all these functions
+All these functions
 lookup the module implementing the algorithm and pass the actual work
 to that module.  The parsing of the S-expression input and the
 construction of S-expression for the return values is done by the high
 level code (@file{cipher/pubkey.c}).  Thus the internal interface
 between the algorithm modules and the high level functions passes data
-in a custom format.  The interface to the modules is published
-(@file{gcrypt-modules.h}) so that it can used to register external
-implementations of algorithms with Libgcrypt.  However, for some
-algorithms this module interface is to limited and thus for the
-internal modules an extra interface is sometimes used to convey more
-information.
+in a custom format.
 
 By default Libgcrypt uses a blinding technique for RSA decryption to
 mitigate real world timing attacks over a network: Instead of using
@@ -5126,12 +4751,7 @@ verification fails.  (@code{cipher/@/dsa.c:@/test_keys})
 
 @subsection Software Load Tests
 
-Loading of extra modules into libgcrypt is disabled in FIPS mode and
-thus no tests are
-implemented. (@code{cipher/@/cipher.c:@/_gcry_cipher_register},
-@code{cipher/@/md.c:@/_gcry_md_register},
-@code{cipher/@/pubkey.c:@/_gcry_pk_register})
-
+No code is loaded at runtime.
 
 @subsection Manual Key Entry Tests
 
@@ -5332,9 +4952,6 @@ large-pool-CSPRNG generator.
 The command @code{GCRYCTL_ENABLE_QUICK_RANDOM} is ignored.
 
 @item
-Registration of external modules is not supported.
-
-@item
 Message digest debugging is disabled.
 
 @item