#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 */
int OP_digest_digest(void *provctx, const unsigned char *in, size_t inl,
unsigned char *out, size_t *outl, size_t outsz);
+ /* Digest parameter descriptors */
+ const OSSL_PARAM *OP_cipher_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);
+
/* Digest parameters */
- size_t OP_digest_size(void);
- size_t OP_digest_block_size(void);
- int OP_digest_set_params(void *dctx, const OSSL_PARAM params[]);
- int OP_digest_get_params(void *dctx, OSSL_PARAM params[]);
+ int OP_digest_get_params(OSSL_PARAM params[]);
+
+ /* Digest operation parameters */
+ 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
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
macros in L<openssl-core_numbers.h(7)>, as follows:
- OP_digest_newctx OSSL_FUNC_DIGEST_NEWCTX
- OP_digest_freectx OSSL_FUNC_DIGEST_FREECTX
- OP_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX
+ OP_digest_newctx OSSL_FUNC_DIGEST_NEWCTX
+ OP_digest_freectx OSSL_FUNC_DIGEST_FREECTX
+ OP_digest_dupctx OSSL_FUNC_DIGEST_DUPCTX
- OP_digest_init OSSL_FUNC_DIGEST_INIT
- OP_digest_update OSSL_FUNC_DIGEST_UPDATE
- OP_digest_final OSSL_FUNC_DIGEST_FINAL
- OP_digest_digest OSSL_FUNC_DIGEST_DIGEST
+ OP_digest_init OSSL_FUNC_DIGEST_INIT
+ OP_digest_update OSSL_FUNC_DIGEST_UPDATE
+ OP_digest_final OSSL_FUNC_DIGEST_FINAL
+ OP_digest_digest OSSL_FUNC_DIGEST_DIGEST
- OP_digest_size OSSL_FUNC_DIGEST_SIZE
- OP_digest_block_size OSSL_FUNC_DIGEST_BLOCK_SIZE
- OP_digest_set_params OSSL_FUNC_DIGEST_SET_PARAMS
- OP_digest_get_params OSSL_FUNC_DIGEST_GET_PARAMS
+ OP_digest_get_params OSSL_FUNC_DIGEST_GET_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.
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 param
ater B<provctx> is the provider context generated during provider
+The param
eter B<provctx> is the provider context generated during provider
initialisation (see L<provider(3)>).
OP_digest_freectx() is passed a pointer to the provider side digest context in
=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 B<dctx> parameter.
OP_digest_update() is called to supply data to be digested as part of a
previously initialised digest operation.
=head2 Digest Parameters
-OP_digest_size() should return the size of the digest.
+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>.
+
+OP_digest_set_ctx_params() sets digest operation parameters for the
+provider side digest context B<dctx> to B<params>.
+Any parameter settings are additional to any that were previously set.
+
+OP_digest_get_ctx_params() gets digest operation details details from
+the given provider side digest context B<dctx> and stores them in B<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_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 parameters are relevant to, or are understood
+by all digests:
+
+=over 4
+
+=item B<OSSL_DIGEST_PARAM_BLOCK_SIZE> (int)
+
+The digest block size.
+
+=item B<OSSL_DIGEST_PARAM_SIZE> (int)
+
+The digest output size.
+
+=item B<OSSL_DIGEST_PARAM_FLAGS> (unsigned long)
+
+Diverse flags that describe exceptional behaviour for the digest:
+
+=over 4
+
+=item B<EVP_MD_FLAG_ONESHOT>
+
+This digest method can only handle one block of input.
+
+=item B<EVP_MD_FLAG_XOF>
+
+This digest method is an extensible-output function (XOF) and supports
+setting the B<OSSL_DIGEST_PARAM_XOFLEN> parameter.
+
+=item B<EVP_MD_FLAG_DIGALGID_NULL>
+
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter set to NULL by default. Use this for PKCS#1. I<Note: if
+combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.>
+
+=item B<EVP_MD_FLAG_DIGALGID_ABSENT>
+
+When setting up a DigestAlgorithmIdentifier, this flag will have the
+parameter be left absent by default. I<Note: if combined with
+EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
+
+=item B<EVP_MD_FLAG_DIGALGID_CUSTOM>
+
+Custom DigestAlgorithmIdentifier handling via ctrl, with
+B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with
+EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.>
+Currently unused.
+
+=back
+
+=back
-OP_digest_block_size() should return the size of the block size of the
-underlying digest algorithm.
+=head2 Digest Context Parameters
-OP_digest_set_params() set 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 B<dctx> to B<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_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 B<dctx>
+and stores them in B<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
projects / openssl.git / blobdiff