Latest update.
This commit is contained in:
@@ -0,0 +1,244 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
provider-mac - The mac library E<lt>-E<gt> provider functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment 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.
|
||||
*/
|
||||
|
||||
/* Context management */
|
||||
void *OP_mac_newctx(void *provctx);
|
||||
void OP_mac_freectx(void *mctx);
|
||||
void *OP_mac_dupctx(void *src);
|
||||
|
||||
/* Encryption/decryption */
|
||||
int OP_mac_init(void *mctx);
|
||||
int OP_mac_update(void *mctx, const unsigned char *in, size_t inl);
|
||||
int OP_mac_final(void *mctx, unsigned char *out, size_t *outl, size_t outsize);
|
||||
|
||||
/* MAC parameter descriptors */
|
||||
const OSSL_PARAM *OP_mac_get_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_get_ctx_params(void *mctx, OSSL_PARAM params[]);
|
||||
int OP_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This documentation is primarily aimed at provider authors. See L<provider(7)>
|
||||
for further information.
|
||||
|
||||
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)>.
|
||||
|
||||
All "functions" mentioned here are passed as function pointers between
|
||||
F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
|
||||
B<OSSL_ALGORITHM> arrays that are returned by the provider's
|
||||
provider_query_operation() function
|
||||
(see L<provider-base(7)/Provider Functions>).
|
||||
|
||||
All these "functions" have a corresponding function type definition
|
||||
named B<OSSL_{name}_fn>, and a helper function to retrieve the
|
||||
function pointer from an B<OSSL_DISPATCH> element named
|
||||
B<OSSL_get_{name}>.
|
||||
For example, the "function" OP_mac_newctx() has these:
|
||||
|
||||
typedef void *(OSSL_OP_mac_newctx_fn)(void *provctx);
|
||||
static ossl_inline OSSL_OP_mac_newctx_fn
|
||||
OSSL_get_OP_mac_newctx(const OSSL_DISPATCH *opf);
|
||||
|
||||
B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
|
||||
macros in L<openssl-core_numbers.h(7)>, as follows:
|
||||
|
||||
OP_mac_newctx OSSL_FUNC_MAC_NEWCTX
|
||||
OP_mac_freectx OSSL_FUNC_MAC_FREECTX
|
||||
OP_mac_dupctx OSSL_FUNC_MAC_DUPCTX
|
||||
|
||||
OP_mac_init OSSL_FUNC_MAC_INIT
|
||||
OP_mac_update OSSL_FUNC_MAC_UPDATE
|
||||
OP_mac_final OSSL_FUNC_MAC_FINAL
|
||||
|
||||
OP_mac_get_params OSSL_FUNC_MAC_GET_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
|
||||
OP_mac_settable_ctx_params OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS
|
||||
|
||||
A mac algorithm implementation may not implement all of these functions.
|
||||
In order to be a consistent set of functions, at least the following functions
|
||||
must be implemented: OP_mac_newctx(), OP_mac_freectx(), OP_mac_init(),
|
||||
OP_mac_update(), OP_mac_final().
|
||||
All other functions are optional.
|
||||
|
||||
=head2 Context Management Functions
|
||||
|
||||
OP_mac_newctx() should create and return a pointer to a provider side
|
||||
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 paramater I<provctx> is the provider context generated during provider
|
||||
initialisation (see L<provider(3)>).
|
||||
|
||||
OP_mac_freectx() is passed a pointer to the provider side mac context in
|
||||
the I<mctx> parameter.
|
||||
If it receives NULL as I<mctx> value, it should not do anything other than
|
||||
return.
|
||||
This function should free any resources associated with that context.
|
||||
|
||||
OP_mac_dupctx() should duplicate the provider side mac context in the
|
||||
I<mctx> parameter and return the duplicate copy.
|
||||
|
||||
=head2 Encryption/Decryption Functions
|
||||
|
||||
OP_mac_init() initialises a mac operation given a newly created provider
|
||||
side mac context in the I<mctx> paramter.
|
||||
|
||||
OP_mac_update() is called to supply data for MAC computation of a previously
|
||||
initialised mac operation.
|
||||
The I<mctx> parameter contains a pointer to a previously initialised provider
|
||||
side context.
|
||||
OP_mac_update() may be called multiple times for a single mac operation.
|
||||
|
||||
OP_mac_final() completes the MAC computation started through previous
|
||||
OP_mac_init() and OP_mac_update() calls.
|
||||
The I<mctx> parameter contains a pointer to the provider side context.
|
||||
The resulting MAC should be written to I<out> and the amount of data written
|
||||
to I<*outl>, which should not exceed I<outsize> bytes.
|
||||
The same expectations apply to I<outsize> as documented for
|
||||
L<EVP_MAC_final(3)>.
|
||||
|
||||
=head2 Mac Parameters
|
||||
|
||||
See L<OSSL_PARAM(3)> for further details on the parameters structure used by
|
||||
these functions.
|
||||
|
||||
OP_mac_get_params() gets details of parameter values associated with the
|
||||
provider algorithm and stores them in I<params>.
|
||||
|
||||
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_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_get_ctx_params(), and OP_mac_set_ctx_params() can handle,
|
||||
respectively.
|
||||
|
||||
Parameters currently recognised by built-in macs are as follows. Not all
|
||||
parameters are relevant to, or are understood by all macs:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<OSSL_MAC_PARAM_KEY> (octet string)
|
||||
|
||||
Sets the key in the associated MAC ctx.
|
||||
|
||||
=item B<OSSL_MAC_PARAM_IV> (octet string)
|
||||
|
||||
Sets the IV of the underlying cipher, when applicable.
|
||||
|
||||
=item B<OSSL_MAC_PARAM_CUSTOM> (utf8 string)
|
||||
|
||||
Sets the custom string in the associated MAC ctx.
|
||||
|
||||
=item B<OSSL_MAC_PARAM_SALT> (octet string)
|
||||
|
||||
Sets the salt of the underlying cipher, when applicable.
|
||||
|
||||
=item B<OSSL_MAC_PARAM_BLOCK_XOF> (int)
|
||||
|
||||
Sets XOF mode in the associated MAC ctx.
|
||||
0 means no XOF mode, 1 means XOF mode.
|
||||
|
||||
=item B<OSSL_MAC_PARAM_FLAGS> (int)
|
||||
|
||||
Gets flags associated with the MAC.
|
||||
|
||||
=for comment We need to investigate if this is the right approach
|
||||
|
||||
=item B<OSSL_MAC_PARAM_CIPHER> (utf8 string)
|
||||
|
||||
=item B<OSSL_MAC_PARAM_DIGEST> (utf8 string)
|
||||
|
||||
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_ENGINE> (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.
|
||||
|
||||
=item 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)
|
||||
|
||||
Can be used to get the resulting MAC size.
|
||||
|
||||
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
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
OP_mac_newctx() and OP_mac_dupctx() should return the newly created
|
||||
provider side mac context, or NULL on failure.
|
||||
|
||||
OP_mac_init(), OP_mac_update(), OP_mac_final(), OP_mac_get_params(),
|
||||
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
|
||||
OP_mac_settable_ctx_params() should return a constant B<OSSL_PARAM>
|
||||
array, or NULL if none is offered.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<provider(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The provider MAC interface was introduced in OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2019 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
|
||||
Reference in New Issue
Block a user