Introduce the provider property
[openssl.git] / doc / man7 / provider-digest.pod
index 1b71cc19f9c783e217c2b20ef18fd2efcb4d90b4..576ea581b49372697bc0a68ab0bf516c8c48de9c 100644 (file)
@@ -6,15 +6,14 @@ provider-digest - The digest library E<lt>-E<gt> provider functions
 
 =head1 SYNOPSIS
 
-=for comment multiple includes
+=for openssl multiple includes
 
  #include <openssl/core_numbers.h>
  #include <openssl/core_names.h>
 
  /*
-  * None of these are actual functions, but are displayed like this for
-  * the function signatures for functions that are offered as function
-  * pointers in OSSL_DISPATCH arrays.
+  * Digests support the following function signatures in OSSL_DISPATCH arrays.
+  * (The function signatures are not actual functions).
   */
 
  /* Context management */
@@ -31,18 +30,18 @@ provider-digest - The digest library E<lt>-E<gt> provider functions
                       unsigned char *out, size_t *outl, size_t outsz);
 
  /* Digest parameter descriptors */
- const OSSL_PARAM *OP_cipher_gettable_params(void);
+ const OSSL_PARAM *OP_digest_gettable_params(void);
 
  /* Digest operation parameter descriptors */
- const OSSL_PARAM *OP_cipher_gettable_ctx_params(void);
- const OSSL_PARAM *OP_cipher_settable_ctx_params(void);
+ const OSSL_PARAM *OP_digest_gettable_ctx_params(void);
+ const OSSL_PARAM *OP_digest_settable_ctx_params(void);
 
  /* Digest parameters */
  int OP_digest_get_params(OSSL_PARAM params[]);
 
  /* Digest operation parameters */
- int OP_digest_ctx_set_params(void *dctx, const OSSL_PARAM params[]);
- int OP_digest_ctx_get_params(void *dctx, OSSL_PARAM params[]);
+ int OP_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]);
+ int OP_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]);
 
 =head1 DESCRIPTION
 
@@ -82,15 +81,15 @@ macros in L<openssl-core_numbers.h(7)>, as follows:
  OP_digest_digest               OSSL_FUNC_DIGEST_DIGEST
 
  OP_digest_get_params           OSSL_FUNC_DIGEST_GET_PARAMS
- OP_digest_ctx_get_params       OSSL_FUNC_DIGEST_CTX_GET_PARAMS
- OP_digest_ctx_set_params       OSSL_FUNC_DIGEST_CTX_SET_PARAMS
+ OP_digest_get_ctx_params       OSSL_FUNC_DIGEST_GET_CTX_PARAMS
+ OP_digest_set_ctx_params       OSSL_FUNC_DIGEST_SET_CTX_PARAMS
 
  OP_digest_gettable_params      OSSL_FUNC_DIGEST_GETTABLE_PARAMS
  OP_digest_gettable_ctx_params  OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS
  OP_digest_settable_ctx_params  OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS
 
 A digest algorithm implementation may not implement all of these functions.
-In order to be useable all or none of OP_digest_newctx, OP_digest_freectx,
+In order to be usable all or none of OP_digest_newctx, OP_digest_freectx,
 OP_digest_init, OP_digest_update and OP_digest_final should be implemented.
 All other functions are optional.
 
@@ -100,43 +99,43 @@ OP_digest_newctx() should create and return a pointer to a provider side
 structure for holding context information during a digest operation.
 A pointer to this context will be passed back in a number of the other digest
 operation function calls.
-The paramater B<provctx> is the provider context generated during provider
-initialisation (see L<provider(3)>).
+The parameter I<provctx> is the provider context generated during provider
+initialisation (see L<provider(7)>).
 
 OP_digest_freectx() is passed a pointer to the provider side digest context in
-the B<dctx> parameter.
+the I<dctx> parameter.
 This function should free any resources associated with that context.
 
 OP_digest_dupctx() should duplicate the provider side digest context in the
-B<dctx> parameter and return the duplicate copy.
+I<dctx> parameter and return the duplicate copy.
 
 =head2 Digest Generation Functions
 
 OP_digest_init() initialises a digest operation given a newly created
-provider side digest context in the B<dctx> paramter.
+provider side digest context in the I<dctx> parameter.
 
 OP_digest_update() is called to supply data to be digested as part of a
 previously initialised digest operation.
-The B<dctx> parameter contains a pointer to a previously initialised provider
+The I<dctx> parameter contains a pointer to a previously initialised provider
 side context.
-OP_digest_update() should digest B<inl> bytes of data at the location pointed to
-by B<in>.
+OP_digest_update() should digest I<inl> bytes of data at the location pointed to
+by I<in>.
 OP_digest_update() may be called multiple times for a single digest operation.
 
 OP_digest_final() generates a digest started through previous OP_digest_init()
 and OP_digest_update() calls.
-The B<dctx> parameter contains a pointer to the provider side context.
-The digest should be written to B<*out> and the length of the digest to
-B<*outl>.
-The digest should not exceed B<outsz> bytes.
+The I<dctx> parameter contains a pointer to the provider side context.
+The digest should be written to I<*out> and the length of the digest to
+I<*outl>.
+The digest should not exceed I<outsz> bytes.
 
 OP_digest_digest() is a "oneshot" digest function.
 No provider side digest context is used.
 Instead the provider context that was created during provider initialisation is
-passed in the B<provctx> parameter (see L<provider(3)>).
-B<inl> bytes at B<in> should be digested and the result should be stored at
-B<out>. The length of the digest should be stored in B<*outl> which should not
-exceed B<outsz> bytes.
+passed in the I<provctx> parameter (see L<provider(7)>).
+I<inl> bytes at I<in> should be digested and the result should be stored at
+I<out>. The length of the digest should be stored in I<*outl> which should not
+exceed I<outsz> bytes.
 
 =head2 Digest Parameters
 
@@ -144,36 +143,38 @@ See L<OSSL_PARAM(3)> for further details on the parameters structure used by
 these functions.
 
 OP_digest_get_params() gets details of the algorithm implementation
-and stores them in B<params>.
+and stores them in I<params>.
 
-OP_digest_ctx_set_params() sets digest operation parameters for the
-provider side digest context B<dctx> to B<params>.
+OP_digest_set_ctx_params() sets digest operation parameters for the
+provider side digest context I<dctx> to I<params>.
 Any parameter settings are additional to any that were previously set.
 
-OP_digest_ctx_get_params() gets digest operation details details from
-the given provider side digest context B<dctx> and stores them in B<params>.
+OP_digest_get_ctx_params() gets digest operation details details from
+the given provider side digest context I<dctx> and stores them in I<params>.
 
 OP_digest_gettable_params(), OP_digest_gettable_ctx_params(), and
 OP_digest_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
 as descriptors of the parameters that OP_digest_get_params(),
-OP_digest_ctx_get_params(), and OP_digest_ctx_set_params() can handle,
+OP_digest_get_ctx_params(), and OP_digest_set_ctx_params() can handle,
 respectively.
 
 Parameters currently recognised by built-in digests with this function
-are as follows. Not all parametes are relevant to, or are understood
+are as follows. Not all parameters are relevant to, or are understood
 by all digests:
 
 =over 4
 
-=item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (int)
+=item "blocksize" (B<OSSL_DIGEST_PARAM_BLOCK_SIZE>) <unsigned integer>
 
 The digest block size.
+The length of the "blocksize" parameter should not exceed that of a B<size_t>.
 
-=item B<OSSL_DIGEST_PARAM_SIZE> (int)
+=item "size" (B<OSSL_DIGEST_PARAM_SIZE>) <unsigned integer>
 
 The digest output size.
+The length of the "size" parameter should not exceed that of a B<size_t>.
 
-=item B<OSSL_DIGEST_PARAM_FLAGS> (unsigned long)
+=item "flags" (B<OSSL_DIGEST_PARAM_FLAGS>) <unsigned integer>
 
 Diverse flags that describe exceptional behaviour for the digest:
 
@@ -209,30 +210,34 @@ Currently unused.
 
 =back
 
+The length of the "flags" parameter should equal that of an
+B<unsigned long int>.
+
 =back
 
 =head2 Digest Context Parameters
 
-OP_digest_ctx_set_params() sets digest parameters associated with the
-given provider side digest context B<dctx> to B<params>.
+OP_digest_set_ctx_params() sets digest parameters associated with the
+given provider side digest context I<dctx> to I<params>.
 Any parameter settings are additional to any that were previously set.
 See L<OSSL_PARAM(3)> for further details on the parameters structure.
 
-OP_digest_ctx_get_params() gets details of currently set parameters
-values associated with the give provider side digest context B<dctx>
-and stores them in B<params>.
+OP_digest_get_ctx_params() gets details of currently set parameters
+values associated with the give provider side digest context I<dctx>
+and stores them in I<params>.
 See L<OSSL_PARAM(3)> for further details on the parameters structure.
 
 Parameters currently recognised by built-in digests are as follows. Not all
-parametes are relevant to, or are understood by all digests:
+parameters are relevant to, or are understood by all digests:
 
 =over 4
 
-=item B<OSSL_DIGEST_PARAM_XOFLEN> (size_t)
+=item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer>
 
 Sets the digest length for extendable output functions.
+The length of the "xoflen" parameter should not exceed that of a B<size_t>.
 
-=item B<OSSL_DIGEST_PARAM_SSL3_MS> (octet string)
+=item "ssl3-ms" (B<OSSL_DIGEST_PARAM_SSL3_MS>) <octet string>
 
 This parameter is set by libssl in order to calculate a signature hash for an
 SSLv3 CertificateVerify message as per RFC6101.
@@ -244,7 +249,7 @@ section 5.6.8.
 The next call after setting this parameter will be OP_digest_final().
 This is only relevant for implementations of SHA1 or MD5_SHA1.
 
-=item B<OSSL_DIGEST_PARAM_PAD_TYPE> (int)
+=item "pad_type" (B<OSSL_DIGEST_PARAM_PAD_TYPE>) <unsigned integer>
 
 Sets the pad type to be used.
 The only built-in digest that uses this is MDC2.
@@ -252,7 +257,7 @@ Normally the final MDC2 block is padded with 0s.
 If the pad type is set to 2 then the final block is padded with 0x80 followed by
 0s.
 
-=item B<OSSL_DIGEST_PARAM_MICALG> (utf8 string)
+=item "micalg" (B<OSSL_DIGEST_PARAM_MICALG>) <UTF8 string>
 
 Gets the digest Message Integrity Check algorithm string.
 This is used when creating S/MIME multipart/signed messages, as specified in