| =pod |
| |
| =head1 NAME |
| |
| EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free, |
| EVP_MD_get_params, EVP_MD_gettable_params, |
| EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_dup, |
| EVP_MD_CTX_copy, EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, |
| EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, |
| EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, |
| EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, |
| EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, |
| EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, |
| EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, |
| EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, |
| EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, |
| EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, |
| EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md, |
| EVP_MD_CTX_get_type, EVP_MD_CTX_get_size, EVP_MD_CTX_get_block_size, |
| EVP_MD_CTX_get0_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, |
| EVP_md_null, |
| EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, |
| EVP_MD_CTX_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, |
| EVP_MD_do_all_provided, |
| EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size, |
| EVP_MD_block_size, EVP_MD_flags, EVP_MD_CTX_size, EVP_MD_CTX_block_size, |
| EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data |
| - EVP digest routines |
| |
| =head1 SYNOPSIS |
| |
| #include <openssl/evp.h> |
| |
| EVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *ctx, const char *algorithm, |
| const char *properties); |
| int EVP_MD_up_ref(EVP_MD *md); |
| void EVP_MD_free(EVP_MD *md); |
| int EVP_MD_get_params(const EVP_MD *digest, OSSL_PARAM params[]); |
| const OSSL_PARAM *EVP_MD_gettable_params(const EVP_MD *digest); |
| EVP_MD_CTX *EVP_MD_CTX_new(void); |
| int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); |
| void EVP_MD_CTX_free(EVP_MD_CTX *ctx); |
| void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2); |
| int EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]); |
| int EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]); |
| const OSSL_PARAM *EVP_MD_settable_ctx_params(const EVP_MD *md); |
| const OSSL_PARAM *EVP_MD_gettable_ctx_params(const EVP_MD *md); |
| const OSSL_PARAM *EVP_MD_CTX_settable_params(EVP_MD_CTX *ctx); |
| const OSSL_PARAM *EVP_MD_CTX_gettable_params(EVP_MD_CTX *ctx); |
| void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags); |
| void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags); |
| int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags); |
| |
| int EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name, const char *propq, |
| const void *data, size_t datalen, |
| unsigned char *md, size_t *mdlen); |
| int EVP_Digest(const void *data, size_t count, unsigned char *md, |
| unsigned int *size, const EVP_MD *type, ENGINE *impl); |
| int EVP_DigestInit_ex2(EVP_MD_CTX *ctx, const EVP_MD *type, |
| const OSSL_PARAM params[]); |
| int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); |
| int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); |
| int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); |
| int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *md, size_t len); |
| |
| EVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in); |
| int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); |
| |
| int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); |
| int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); |
| |
| int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in); |
| |
| const char *EVP_MD_get0_name(const EVP_MD *md); |
| const char *EVP_MD_get0_description(const EVP_MD *md); |
| int EVP_MD_is_a(const EVP_MD *md, const char *name); |
| int EVP_MD_names_do_all(const EVP_MD *md, |
| void (*fn)(const char *name, void *data), |
| void *data); |
| const OSSL_PROVIDER *EVP_MD_get0_provider(const EVP_MD *md); |
| int EVP_MD_get_type(const EVP_MD *md); |
| int EVP_MD_get_pkey_type(const EVP_MD *md); |
| int EVP_MD_get_size(const EVP_MD *md); |
| int EVP_MD_get_block_size(const EVP_MD *md); |
| unsigned long EVP_MD_get_flags(const EVP_MD *md); |
| |
| const EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx); |
| EVP_MD *EVP_MD_CTX_get1_md(EVP_MD_CTX *ctx); |
| const char *EVP_MD_CTX_get0_name(const EVP_MD_CTX *ctx); |
| int EVP_MD_CTX_get_size(const EVP_MD_CTX *ctx); |
| int EVP_MD_CTX_get_block_size(const EVP_MD_CTX *ctx); |
| int EVP_MD_CTX_get_type(const EVP_MD_CTX *ctx); |
| void *EVP_MD_CTX_get0_md_data(const EVP_MD_CTX *ctx); |
| |
| const EVP_MD *EVP_md_null(void); |
| |
| const EVP_MD *EVP_get_digestbyname(const char *name); |
| const EVP_MD *EVP_get_digestbynid(int type); |
| const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); |
| |
| EVP_PKEY_CTX *EVP_MD_CTX_get_pkey_ctx(const EVP_MD_CTX *ctx); |
| void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx); |
| |
| void EVP_MD_do_all_provided(OSSL_LIB_CTX *libctx, |
| void (*fn)(EVP_MD *mac, void *arg), |
| void *arg); |
| |
| #define EVP_MD_type EVP_MD_get_type |
| #define EVP_MD_nid EVP_MD_get_type |
| #define EVP_MD_name EVP_MD_get0_name |
| #define EVP_MD_pkey_type EVP_MD_get_pkey_type |
| #define EVP_MD_size EVP_MD_get_size |
| #define EVP_MD_block_size EVP_MD_get_block_size |
| #define EVP_MD_flags EVP_MD_get_flags |
| #define EVP_MD_CTX_size EVP_MD_CTX_get_size |
| #define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size |
| #define EVP_MD_CTX_type EVP_MD_CTX_get_type |
| #define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx |
| #define EVP_MD_CTX_md_data EVP_MD_CTX_get0_md_data |
| |
| The following functions have been deprecated since OpenSSL 3.0, and can be |
| hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, |
| see L<openssl_user_macros(7)>: |
| |
| const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); |
| |
| int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx, |
| const void *data, size_t count); |
| |
| void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx, |
| int (*update)(EVP_MD_CTX *ctx, |
| const void *data, size_t count)); |
| |
| =head1 DESCRIPTION |
| |
| The EVP digest routines are a high-level interface to message digests, |
| and should be used instead of the digest-specific functions. |
| |
| The B<EVP_MD> type is a structure for digest method implementation. |
| |
| =over 4 |
| |
| =item EVP_MD_fetch() |
| |
| Fetches the digest implementation for the given I<algorithm> from any |
| provider offering it, within the criteria given by the I<properties>. |
| See L<crypto(7)/ALGORITHM FETCHING> for further information. |
| |
| The returned value must eventually be freed with EVP_MD_free(). |
| |
| Fetched B<EVP_MD> structures are reference counted. |
| |
| =item EVP_MD_up_ref() |
| |
| Increments the reference count for an B<EVP_MD> structure. |
| |
| =item EVP_MD_free() |
| |
| Decrements the reference count for the fetched B<EVP_MD> structure. |
| If the reference count drops to 0 then the structure is freed. |
| |
| =item EVP_MD_CTX_new() |
| |
| Allocates and returns a digest context. |
| |
| =item EVP_MD_CTX_reset() |
| |
| Resets the digest context I<ctx>. This can be used to reuse an already |
| existing context. |
| |
| =item EVP_MD_CTX_free() |
| |
| Cleans up digest context I<ctx> and frees up the space allocated to it. |
| |
| =item EVP_MD_CTX_ctrl() |
| |
| I<This is a legacy method. EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params() |
| is the mechanism that should be used to set and get parameters that are used by |
| providers.> |
| |
| Performs digest-specific control actions on context I<ctx>. The control command |
| is indicated in I<cmd> and any additional arguments in I<p1> and I<p2>. |
| EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex2(). Other restrictions |
| may apply depending on the control type and digest implementation. |
| |
| If this function happens to be used with a fetched B<EVP_MD>, it will |
| translate the controls that are known to OpenSSL into L<OSSL_PARAM(3)> |
| parameters with keys defined by OpenSSL and call EVP_MD_CTX_get_params() or |
| EVP_MD_CTX_set_params() as is appropriate for each control command. |
| |
| See L</CONTROLS> below for more information, including what translations are |
| being done. |
| |
| =item EVP_MD_get_params() |
| |
| Retrieves the requested list of I<params> from a MD I<md>. |
| See L</PARAMETERS> below for more information. |
| |
| =item EVP_MD_CTX_get_params() |
| |
| Retrieves the requested list of I<params> from a MD context I<ctx>. |
| See L</PARAMETERS> below for more information. |
| |
| =item EVP_MD_CTX_set_params() |
| |
| Sets the list of I<params> into a MD context I<ctx>. |
| See L</PARAMETERS> below for more information. |
| |
| =item EVP_MD_gettable_params() |
| |
| Get a constant B<OSSL_PARAM> array that describes the retrievable parameters |
| that can be used with EVP_MD_get_params(). See L<OSSL_PARAM(3)> for the |
| use of B<OSSL_PARAM> as a parameter descriptor. |
| |
| =item EVP_MD_gettable_ctx_params(), EVP_MD_CTX_gettable_params() |
| |
| Get a constant B<OSSL_PARAM> array that describes the retrievable parameters |
| that can be used with EVP_MD_CTX_get_params(). EVP_MD_gettable_ctx_params() |
| returns the parameters that can be retrieved from the algorithm, whereas |
| EVP_MD_CTX_gettable_params() returns the parameters that can be retrieved |
| in the context's current state. See L<OSSL_PARAM(3)> for the use of |
| B<OSSL_PARAM> as a parameter descriptor. |
| |
| =item EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() |
| |
| Get a constant B<OSSL_PARAM> array that describes the settable parameters |
| that can be used with EVP_MD_CTX_set_params(). EVP_MD_settable_ctx_params() |
| returns the parameters that can be set from the algorithm, whereas |
| EVP_MD_CTX_settable_params() returns the parameters that can be set in the |
| context's current state. See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> |
| as a parameter descriptor. |
| |
| =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags() |
| |
| Sets, clears and tests I<ctx> flags. See L</FLAGS> below for more information. |
| |
| =item EVP_Q_digest() is a quick one-shot digest function. |
| |
| It hashes I<datalen> bytes of data at I<data> using the digest algorithm |
| I<name>, which is fetched using the optional I<libctx> and I<propq> parameters. |
| The digest value is placed in I<md> and its length is written at I<mdlen> |
| if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written. |
| |
| =item EVP_Digest() |
| |
| A wrapper around the Digest Init_ex, Update and Final_ex functions. |
| Hashes I<count> bytes of data at I<data> using a digest I<type> from ENGINE |
| I<impl>. The digest value is placed in I<md> and its length is written at I<size> |
| if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> bytes will be written. |
| If I<impl> is NULL the default implementation of digest I<type> is used. |
| |
| =item EVP_DigestInit_ex2() |
| |
| Sets up digest context I<ctx> to use a digest I<type>. |
| I<type> is typically supplied by a function such as EVP_sha1(), or a |
| value explicitly fetched with EVP_MD_fetch(). |
| |
| The parameters B<params> are set on the context after initialisation. |
| |
| The I<type> parameter can be NULL if I<ctx> has been already initialized |
| with another EVP_DigestInit_ex() call and has not been reset with |
| EVP_MD_CTX_reset(). |
| |
| =item EVP_DigestInit_ex() |
| |
| Sets up digest context I<ctx> to use a digest I<type>. |
| I<type> is typically supplied by a function such as EVP_sha1(), or a |
| value explicitly fetched with EVP_MD_fetch(). |
| |
| If I<impl> is non-NULL, its implementation of the digest I<type> is used if |
| there is one, and if not, the default implementation is used. |
| |
| The I<type> parameter can be NULL if I<ctx> has been already initialized |
| with another EVP_DigestInit_ex() call and has not been reset with |
| EVP_MD_CTX_reset(). |
| |
| =item EVP_DigestUpdate() |
| |
| Hashes I<cnt> bytes of data at I<d> into the digest context I<ctx>. This |
| function can be called several times on the same I<ctx> to hash additional |
| data. |
| |
| =item EVP_DigestFinal_ex() |
| |
| Retrieves the digest value from I<ctx> and places it in I<md>. If the I<s> |
| parameter is not NULL then the number of bytes of data written (i.e. the |
| length of the digest) will be written to the integer at I<s>, at most |
| B<EVP_MAX_MD_SIZE> bytes will be written. After calling EVP_DigestFinal_ex() |
| no additional calls to EVP_DigestUpdate() can be made, but |
| EVP_DigestInit_ex2() can be called to initialize a new digest operation. |
| |
| =item EVP_DigestFinalXOF() |
| |
| Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256. |
| It retrieves the digest value from I<ctx> and places it in I<len>-sized I<md>. |
| After calling this function no additional calls to EVP_DigestUpdate() can be |
| made, but EVP_DigestInit_ex2() can be called to initialize a new operation. |
| |
| =item EVP_MD_CTX_dup() |
| |
| Can be used to duplicate the message digest state from I<in>. This is useful |
| to avoid multiple EVP_MD_fetch() calls or if large amounts of data are to be |
| hashed which only differ in the last few bytes. |
| |
| =item EVP_MD_CTX_copy_ex() |
| |
| Can be used to copy the message digest state from I<in> to I<out>. This is |
| useful if large amounts of data are to be hashed which only differ in the last |
| few bytes. |
| |
| =item EVP_DigestInit() |
| |
| Behaves in the same way as EVP_DigestInit_ex2() except it doesn't set any |
| parameters and calls EVP_MD_CTX_reset() so it cannot be used with an I<type> |
| of NULL. |
| |
| =item EVP_DigestFinal() |
| |
| Similar to EVP_DigestFinal_ex() except after computing the digest |
| the digest context I<ctx> is automatically cleaned up with EVP_MD_CTX_reset(). |
| |
| =item EVP_MD_CTX_copy() |
| |
| Similar to EVP_MD_CTX_copy_ex() except the destination I<out> does not have to |
| be initialized. |
| |
| =item EVP_MD_is_a() |
| |
| Returns 1 if I<md> is an implementation of an algorithm that's |
| identifiable with I<name>, otherwise 0. |
| |
| If I<md> is a legacy digest (it's the return value from the likes of |
| EVP_sha256() rather than the result of an EVP_MD_fetch()), only cipher |
| names registered with the default library context (see |
| L<OSSL_LIB_CTX(3)>) will be considered. |
| |
| =item EVP_MD_get0_name(), |
| EVP_MD_CTX_get0_name() |
| |
| Return the name of the given message digest. For fetched message |
| digests with multiple names, only one of them is returned; it's |
| recommended to use EVP_MD_names_do_all() instead. |
| |
| =item EVP_MD_names_do_all() |
| |
| Traverses all names for the I<md>, and calls I<fn> with each name and |
| I<data>. This is only useful with fetched B<EVP_MD>s. |
| |
| =item EVP_MD_get0_description() |
| |
| Returns a description of the digest, meant for display and human consumption. |
| The description is at the discretion of the digest implementation. |
| |
| =item EVP_MD_get0_provider() |
| |
| Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given |
| B<EVP_MD>. |
| |
| =item EVP_MD_get_size(), |
| EVP_MD_CTX_get_size() |
| |
| Return the size of the message digest when passed an B<EVP_MD> or an |
| B<EVP_MD_CTX> structure, i.e. the size of the hash. |
| |
| =item EVP_MD_get_block_size(), |
| EVP_MD_CTX_get_block_size() |
| |
| Return the block size of the message digest when passed an B<EVP_MD> or an |
| B<EVP_MD_CTX> structure. |
| |
| =item EVP_MD_get_type(), |
| EVP_MD_CTX_get_type() |
| |
| Return the NID of the OBJECT IDENTIFIER representing the given message digest |
| when passed an B<EVP_MD> structure. For example, C<EVP_MD_get_type(EVP_sha1())> |
| returns B<NID_sha1>. This function is normally used when setting ASN1 OIDs. |
| |
| =item EVP_MD_CTX_get0_md_data() |
| |
| Return the digest method private data for the passed B<EVP_MD_CTX>. |
| The space is allocated by OpenSSL and has the size originally set with |
| EVP_MD_meth_set_app_datasize(). |
| |
| =item EVP_MD_CTX_get0_md(), EVP_MD_CTX_get1_md() |
| |
| EVP_MD_CTX_get0_md() returns |
| the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>. This |
| will be the same B<EVP_MD> object originally passed to EVP_DigestInit_ex2() (or |
| other similar function) when the EVP_MD_CTX was first initialised. Note that |
| where explicit fetch is in use (see L<EVP_MD_fetch(3)>) the value returned from |
| this function will not have its reference count incremented and therefore it |
| should not be used after the EVP_MD_CTX is freed. |
| EVP_MD_CTX_get1_md() is the same except the ownership is passed to the |
| caller and is from the passed B<EVP_MD_CTX>. |
| |
| =item EVP_MD_CTX_set_update_fn() |
| |
| Sets the update function for I<ctx> to I<update>. |
| This is the function that is called by EVP_DigestUpdate(). If not set, the |
| update function from the B<EVP_MD> type specified at initialization is used. |
| |
| =item EVP_MD_CTX_update_fn() |
| |
| Returns the update function for I<ctx>. |
| |
| =item EVP_MD_get_flags() |
| |
| Returns the I<md> flags. Note that these are different from the B<EVP_MD_CTX> |
| ones. See L<EVP_MD_meth_set_flags(3)> for more information. |
| |
| =item EVP_MD_get_pkey_type() |
| |
| Returns the NID of the public key signing algorithm associated with this |
| digest. For example EVP_sha1() is associated with RSA so this will return |
| B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms are no |
| longer linked this function is only retained for compatibility reasons. |
| |
| =item EVP_md_null() |
| |
| A "null" message digest that does nothing: i.e. the hash it returns is of zero |
| length. |
| |
| =item EVP_get_digestbyname(), |
| EVP_get_digestbynid(), |
| EVP_get_digestbyobj() |
| |
| Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an |
| B<ASN1_OBJECT> structure respectively. |
| |
| The EVP_get_digestbyname() function is present for backwards compatibility with |
| OpenSSL prior to version 3 and is different to the EVP_MD_fetch() function |
| since it does not attempt to "fetch" an implementation of the cipher. |
| Additionally, it only knows about digests that are built-in to OpenSSL and have |
| an associated NID. Similarly EVP_get_digestbynid() and EVP_get_digestbyobj() |
| also return objects without an associated implementation. |
| |
| When the digest objects returned by these functions are used (such as in a call |
| to EVP_DigestInit_ex()) an implementation of the digest will be implicitly |
| fetched from the loaded providers. This fetch could fail if no suitable |
| implementation is available. Use EVP_MD_fetch() instead to explicitly fetch |
| the algorithm and an associated implementation from a provider. |
| |
| See L<crypto(7)/ALGORITHM FETCHING> for more information about fetching. |
| |
| The digest objects returned from these functions do not need to be freed with |
| EVP_MD_free(). |
| |
| =item EVP_MD_CTX_get_pkey_ctx() |
| |
| Returns the B<EVP_PKEY_CTX> assigned to I<ctx>. The returned pointer should not |
| be freed by the caller. |
| |
| =item EVP_MD_CTX_set_pkey_ctx() |
| |
| Assigns an B<EVP_PKEY_CTX> to B<EVP_MD_CTX>. This is usually used to provide |
| a customized B<EVP_PKEY_CTX> to L<EVP_DigestSignInit(3)> or |
| L<EVP_DigestVerifyInit(3)>. The I<pctx> passed to this function should be freed |
| by the caller. A NULL I<pctx> pointer is also allowed to clear the B<EVP_PKEY_CTX> |
| assigned to I<ctx>. In such case, freeing the cleared B<EVP_PKEY_CTX> or not |
| depends on how the B<EVP_PKEY_CTX> is created. |
| |
| =item EVP_MD_do_all_provided() |
| |
| Traverses all messages digests implemented by all activated providers |
| in the given library context I<libctx>, and for each of the implementations, |
| calls the given function I<fn> with the implementation method and the given |
| I<arg> as argument. |
| |
| =back |
| |
| =head1 PARAMETERS |
| |
| See L<OSSL_PARAM(3)> for information about passing parameters. |
| |
| EVP_MD_CTX_set_params() can be used with the following OSSL_PARAM keys: |
| |
| =over 4 |
| |
| =item "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>) <unsigned integer> |
| |
| Sets the digest length for extendable output functions. |
| It is used by the SHAKE algorithm and should not exceed what can be given |
| using a B<size_t>. |
| |
| =item "pad-type" (B<OSSL_DIGEST_PARAM_PAD_TYPE>) <unsigned integer> |
| |
| Sets the padding type. |
| It is used by the MDC2 algorithm. |
| |
| =back |
| |
| EVP_MD_CTX_get_params() can be used with the following OSSL_PARAM keys: |
| |
| =over 4 |
| |
| =item "micalg" (B<OSSL_PARAM_DIGEST_KEY_MICALG>) <UTF8 string>. |
| |
| Gets the digest Message Integrity Check algorithm string. This is used when |
| creating S/MIME multipart/signed messages, as specified in RFC 3851. |
| It may be used by external engines or providers. |
| |
| =back |
| |
| =head1 CONTROLS |
| |
| EVP_MD_CTX_ctrl() can be used to send the following standard controls: |
| |
| =over 4 |
| |
| =item EVP_MD_CTRL_MICALG |
| |
| Gets the digest Message Integrity Check algorithm string. This is used when |
| creating S/MIME multipart/signed messages, as specified in RFC 3851. |
| The string value is written to I<p2>. |
| |
| When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with |
| an L<OSSL_PARAM(3)> item with the key "micalg" (B<OSSL_DIGEST_PARAM_MICALG>). |
| |
| =item EVP_MD_CTRL_XOF_LEN |
| |
| This control sets the digest length for extendable output functions to I<p1>. |
| Sending this control directly should not be necessary, the use of |
| EVP_DigestFinalXOF() is preferred. |
| Currently used by SHAKE. |
| |
| When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with |
| an L<OSSL_PARAM(3)> item with the key "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>). |
| |
| =back |
| |
| =head1 FLAGS |
| |
| EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags() |
| can be used the manipulate and test these B<EVP_MD_CTX> flags: |
| |
| =over 4 |
| |
| =item EVP_MD_CTX_FLAG_ONESHOT |
| |
| This flag instructs the digest to optimize for one update only, if possible. |
| |
| =for comment EVP_MD_CTX_FLAG_CLEANED is internal, don't mention it |
| |
| =for comment EVP_MD_CTX_FLAG_REUSE is internal, don't mention it |
| |
| =for comment We currently avoid documenting flags that are only bit holder: |
| EVP_MD_CTX_FLAG_NON_FIPS_ALLOW, EVP_MD_CTX_FLAGS_PAD_* |
| |
| =item EVP_MD_CTX_FLAG_NO_INIT |
| |
| This flag instructs EVP_DigestInit() and similar not to initialise the |
| implementation specific data. |
| |
| =item EVP_MD_CTX_FLAG_FINALISE |
| |
| Some functions such as EVP_DigestSign only finalise copies of internal |
| contexts so additional data can be included after the finalisation call. |
| This is inefficient if this functionality is not required, and can be |
| disabled with this flag. |
| |
| =back |
| |
| =head1 RETURN VALUES |
| |
| =over 4 |
| |
| =item EVP_MD_fetch() |
| |
| Returns a pointer to a B<EVP_MD> for success or NULL for failure. |
| |
| =item EVP_MD_up_ref() |
| |
| Returns 1 for success or 0 for failure. |
| |
| =item EVP_Q_digest(), |
| EVP_Digest(), |
| EVP_DigestInit_ex2(), |
| EVP_DigestInit_ex(), |
| EVP_DigestUpdate(), |
| EVP_DigestFinal_ex(), |
| EVP_DigestFinalXOF(), and |
| EVP_DigestFinal() |
| |
| return 1 for |
| success and 0 for failure. |
| |
| =item EVP_MD_CTX_ctrl() |
| |
| Returns 1 if successful or 0 for failure. |
| |
| =item EVP_MD_CTX_set_params(), |
| EVP_MD_CTX_get_params() |
| |
| Returns 1 if successful or 0 for failure. |
| |
| =item EVP_MD_CTX_settable_params(), |
| EVP_MD_CTX_gettable_params() |
| |
| Return an array of constant B<OSSL_PARAM>s, or NULL if there is none |
| to get. |
| |
| =item EVP_MD_CTX_dup() |
| |
| Returns a new EVP_MD_CTX if successful or NULL on failure. |
| |
| =item EVP_MD_CTX_copy_ex() |
| |
| Returns 1 if successful or 0 for failure. |
| |
| =item EVP_MD_get_type(), |
| EVP_MD_get_pkey_type() |
| |
| Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none |
| exists. |
| |
| =item EVP_MD_get_size(), |
| EVP_MD_get_block_size(), |
| EVP_MD_CTX_get_size(), |
| EVP_MD_CTX_get_block_size() |
| |
| Returns the digest or block size in bytes. |
| |
| =item EVP_md_null() |
| |
| Returns a pointer to the B<EVP_MD> structure of the "null" message digest. |
| |
| =item EVP_get_digestbyname(), |
| EVP_get_digestbynid(), |
| EVP_get_digestbyobj() |
| |
| Returns either an B<EVP_MD> structure or NULL if an error occurs. |
| |
| =item EVP_MD_CTX_set_pkey_ctx() |
| |
| This function has no return value. |
| |
| =item EVP_MD_names_do_all() |
| |
| Returns 1 if the callback was called for all names. A return value of 0 means |
| that the callback was not called for any names. |
| |
| =back |
| |
| =head1 NOTES |
| |
| The B<EVP> interface to message digests should almost always be used in |
| preference to the low-level interfaces. This is because the code then becomes |
| transparent to the digest used and much more flexible. |
| |
| New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3 |
| digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms |
| are still in common use. |
| |
| For most applications the I<impl> parameter to EVP_DigestInit_ex() will be |
| set to NULL to use the default digest implementation. |
| |
| The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are |
| obsolete but are retained to maintain compatibility with existing code. New |
| applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and |
| EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context |
| instead of initializing and cleaning it up on each call and allow non default |
| implementations of digests to be specified. |
| |
| If digest contexts are not cleaned up after use, |
| memory leaks will occur. |
| |
| EVP_MD_CTX_get0_name(), EVP_MD_CTX_get_size(), EVP_MD_CTX_get_block_size(), |
| EVP_MD_CTX_get_type(), EVP_get_digestbynid() and EVP_get_digestbyobj() are |
| defined as macros. |
| |
| EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration |
| or control. |
| |
| =head1 EXAMPLES |
| |
| This example digests the data "Test Message\n" and "Hello World\n", using the |
| digest name passed on the command line. |
| |
| #include <stdio.h> |
| #include <string.h> |
| #include <openssl/evp.h> |
| |
| int main(int argc, char *argv[]) |
| { |
| EVP_MD_CTX *mdctx; |
| const EVP_MD *md; |
| char mess1[] = "Test Message\n"; |
| char mess2[] = "Hello World\n"; |
| unsigned char md_value[EVP_MAX_MD_SIZE]; |
| unsigned int md_len, i; |
| |
| if (argv[1] == NULL) { |
| printf("Usage: mdtest digestname\n"); |
| exit(1); |
| } |
| |
| md = EVP_get_digestbyname(argv[1]); |
| if (md == NULL) { |
| printf("Unknown message digest %s\n", argv[1]); |
| exit(1); |
| } |
| |
| mdctx = EVP_MD_CTX_new(); |
| EVP_DigestInit_ex2(mdctx, md, NULL); |
| EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); |
| EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); |
| EVP_DigestFinal_ex(mdctx, md_value, &md_len); |
| EVP_MD_CTX_free(mdctx); |
| |
| printf("Digest is: "); |
| for (i = 0; i < md_len; i++) |
| printf("%02x", md_value[i]); |
| printf("\n"); |
| |
| exit(0); |
| } |
| |
| =head1 SEE ALSO |
| |
| L<EVP_MD_meth_new(3)>, |
| L<openssl-dgst(1)>, |
| L<evp(7)>, |
| L<OSSL_PROVIDER(3)>, |
| L<OSSL_PARAM(3)>, |
| L<property(7)>, |
| L<crypto(7)/ALGORITHM FETCHING>, |
| L<provider-digest(7)>, |
| L<life_cycle-digest(7)> |
| |
| The full list of digest algorithms are provided below. |
| |
| L<EVP_blake2b512(3)>, |
| L<EVP_md2(3)>, |
| L<EVP_md4(3)>, |
| L<EVP_md5(3)>, |
| L<EVP_mdc2(3)>, |
| L<EVP_ripemd160(3)>, |
| L<EVP_sha1(3)>, |
| L<EVP_sha224(3)>, |
| L<EVP_sha3_224(3)>, |
| L<EVP_sm3(3)>, |
| L<EVP_whirlpool(3)> |
| |
| =head1 HISTORY |
| |
| The EVP_MD_CTX_create() and EVP_MD_CTX_destroy() functions were renamed to |
| EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0, respectively. |
| |
| The link between digests and signing algorithms was fixed in OpenSSL 1.0 and |
| later, so now EVP_sha1() can be used with RSA and DSA. |
| |
| The EVP_dss1() function was removed in OpenSSL 1.1.0. |
| |
| The EVP_MD_CTX_set_pkey_ctx() function was added in OpenSSL 1.1.1. |
| |
| The EVP_Q_digest(), EVP_DigestInit_ex2(), |
| EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), |
| EVP_MD_get_params(), EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params(), |
| EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), |
| EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() and |
| EVP_MD_CTX_gettable_params() functions were added in OpenSSL 3.0. |
| |
| The EVP_MD_type(), EVP_MD_nid(), EVP_MD_name(), EVP_MD_pkey_type(), |
| EVP_MD_size(), EVP_MD_block_size(), EVP_MD_flags(), EVP_MD_CTX_size(), |
| EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), and EVP_MD_CTX_md_data() |
| functions were renamed to include C<get> or C<get0> in their names in |
| OpenSSL 3.0, respectively. The old names are kept as non-deprecated |
| alias macros. |
| |
| The EVP_MD_CTX_md() function was deprecated in OpenSSL 3.0; use |
| EVP_MD_CTX_get0_md() instead. |
| EVP_MD_CTX_update_fn() and EVP_MD_CTX_set_update_fn() were deprecated |
| in OpenSSL 3.0. |
| |
| EVP_MD_CTX_dup() was added in OpenSSL 3.1. |
| |
| =head1 COPYRIGHT |
| |
| Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. |
| |
| Licensed under the Apache License 2.0 (the "License"). You may not use |
| this file except in compliance with the License. You can obtain a copy |
| in the file LICENSE in the source distribution or at |
| L<https://www.openssl.org/source/license.html>. |
| |
| =cut |