=head1 SYNOPSIS
-=for comment multiple includes
+=for openssl multiple includes
#include <openssl/core_numbers.h>
#include <openssl/core_names.h>
/* MAC parameter descriptors */
const OSSL_PARAM *OP_mac_get_params(void);
- const OSSL_PARAM *OP_mac_ctx_get_params(void);
- const OSSL_PARAM *OP_mac_ctx_set_params(void);
+ const OSSL_PARAM *OP_mac_get_ctx_params(void);
+ const OSSL_PARAM *OP_mac_set_ctx_params(void);
/* MAC parameters */
int OP_mac_get_params(OSSL_PARAM params[]);
- int OP_mac_ctx_get_params(void *mctx, OSSL_PARAM params[]);
- int OP_mac_ctx_set_params(void *mctx, const OSSL_PARAM params[]);
+ int OP_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]);
+ int OP_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]);
=head1 DESCRIPTION
The MAC operation enables providers to implement mac algorithms and make
them available to applications via the API functions L<EVP_MAC_init(3)>,
-L<EVP_MACM_update(3)> and L<EVP_MAC_final(3)>.
+L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)>.
All "functions" mentioned here are passed as function pointers between
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
OP_mac_final OSSL_FUNC_MAC_FINAL
OP_mac_get_params OSSL_FUNC_MAC_GET_PARAMS
- OP_mac_ctx_get_params OSSL_FUNC_MAC_CTX_GET_PARAMS
- OP_mac_ctx_set_params OSSL_FUNC_MAC_CTX_SET_PARAMS
+ OP_mac_get_ctx_params OSSL_FUNC_MAC_GET_CTX_PARAMS
+ OP_mac_set_ctx_params OSSL_FUNC_MAC_SET_CTX_PARAMS
OP_mac_gettable_params OSSL_FUNC_MAC_GETTABLE_PARAMS
OP_mac_gettable_ctx_params OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS
structure for holding context information during a mac operation.
A pointer to this context will be passed back in a number of the other mac
operation function calls.
-The param
ater I<provctx> is the provider context generated during provider
-initialisation (see L<provider(3)>).
+The param
eter I<provctx> is the provider context generated during provider
+initialisation (see L<provider(7)>).
OP_mac_freectx() is passed a pointer to the provider side mac context in
the I<mctx> parameter.
=head2 Encryption/Decryption Functions
OP_mac_init() initialises a mac operation given a newly created provider
-side mac context in the I<mctx> paramter.
+side mac context in the I<mctx> parameter.
OP_mac_update() is called to supply data for MAC computation of a previously
initialised mac operation.
OP_mac_get_params() gets details of parameter values associated with the
provider algorithm and stores them in I<params>.
-OP_mac_ctx_set_params() sets mac parameters associated with the given
+OP_mac_set_ctx_params() sets mac parameters associated with the given
provider side mac context I<mctx> to I<params>.
Any parameter settings are additional to any that were previously set.
-OP_mac_ctx_get_params() gets details of currently set parameter values
+OP_mac_get_ctx_params() gets details of currently set parameter values
associated with the given provider side mac context I<mctx> and stores them
in I<params>.
OP_mac_gettable_params(), OP_mac_gettable_ctx_params(), and
OP_mac_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
as descriptors of the parameters that OP_mac_get_params(),
-OP_mac_ctx_get_params(), and OP_mac_ctx_set_params() can handle,
+OP_mac_get_ctx_params(), and OP_mac_set_ctx_params() can handle,
respectively.
Parameters currently recognised by built-in macs are as follows. Not all
=over 4
-=item B<OSSL_MAC_PARAM_KEY> (octet string)
+=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
Sets the key in the associated MAC ctx.
-=item B<OSSL_MAC_PARAM_IV> (octet string)
+=item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string>
Sets the IV of the underlying cipher, when applicable.
-=item B<OSSL_MAC_PARAM_CUSTOM> (utf8 string)
+=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <UTF8 string>
Sets the custom string in the associated MAC ctx.
-=item B<OSSL_MAC_PARAM_SALT> (octet string)
+=item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string>
Sets the salt of the underlying cipher, when applicable.
-=item B<OSSL_MAC_PARAM_BLOCK_XOF> (int)
+=item "xof" (B<OSSL_MAC_PARAM_BLOCK_XOF>) <integer>
Sets XOF mode in the associated MAC ctx.
0 means no XOF mode, 1 means XOF mode.
-=item B<OSSL_MAC_PARAM_FLAGS> (int)
+=item "flags" (B<OSSL_MAC_PARAM_FLAGS>) <integer>
Gets flags associated with the MAC.
=for comment We need to investigate if this is the right approach
-=item B<OSSL_MAC_PARAM_ALGORITHM> (utf8 string)
+=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
-Sets the name of the underlying algorithm to be used.
-It must name a suitable algorithm for the MAC that's being used.
-
-=item B<OSSL_MAC_PARAM_MD> (utf8 string)
-
-=item B<OSSL_MAC_PARAM_DIGEST> (utf8 string)
-
-=item B<OSSL_MAC_PARAM_CIPHER> (utf8 string)
-
-These have the same meaning as B<OSSL_MAC_PARAM_ALGORITHM>, but specify
-the expected operation for the underlying algorithm.
-These are regarded as antiquated, but are kept for easier transition from
-legacy MAC implementations.
-
-=item B<OSSL_MAC_PARAM_ENGINE> (utf8 string)
+=item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string>
-Sets the name of an engine that implements the underlying algorithm.
-This must be given together with the algorithm naming parameter to be
-considered valid.
+Sets the name of the underlying cipher or digest to be used.
+It must name a suitable algorithm for the MAC that's being used.
-=item B<OSSL_MAC_PARAM_PROPERTIES> (utf8 string)
+=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
Sets the properties to be queried when trying to fetch the underlying algorithm.
This must be given together with the algorithm naming parameter to be
considered valid.
-Note that both this and B<OSSL_MAC_PARAM_ENGINE> can be given at the same time.
-If the underlying algorithm ends up being fetched from a provider, offered by
-and engine, or a built in legacy function depends on what is available.
-
-=item B<OSSL_MAC_PARAM_SIZE> (int)
-
-=item B<OSSL_MAC_PARAM_DIGESTSIZE> (int)
+=item "size" (B<OSSL_MAC_PARAM_SIZE>) <integer>
-=item B<OSSL_MAC_PARAM_OUTLEN> (int)
+Can be used to get the resulting MAC size.
-All three names are considered the same.
-B<OSSL_MAC_PARAM_SIZE> and B<OSSL_MAC_PARAM_DIGESTSIZE> are considered
-antiquated, but are kept for easier transition from legacy MAC implementations.
+With some MAC algorithms, it can also be used to set the size that the
+resulting MAC should have.
+Allowable sizes are decided within each implementation.
=back
provider side mac context, or NULL on failure.
OP_mac_init(), OP_mac_update(), OP_mac_final(), OP_mac_get_params(),
-OP_mac_ctx_get_params() and OP_mac_ctx_set_params() should return 1 for
+OP_mac_get_ctx_params() and OP_mac_set_ctx_params() should return 1 for
success or 0 on error.
OP_mac_gettable_params(), OP_mac_gettable_ctx_params() and
projects / openssl.git / blobdiff