5 provider-mac - The mac library E<lt>-E<gt> provider functions
9 =for openssl multiple includes
11 #include <openssl/core_dispatch.h>
12 #include <openssl/core_names.h>
15 * None of these are actual functions, but are displayed like this for
16 * the function signatures for functions that are offered as function
17 * pointers in OSSL_DISPATCH arrays.
20 /* Context management */
21 void *OSSL_FUNC_mac_newctx(void *provctx);
22 void OSSL_FUNC_mac_freectx(void *mctx);
23 void *OSSL_FUNC_mac_dupctx(void *src);
25 /* Encryption/decryption */
26 int OSSL_FUNC_mac_init(void *mctx, unsigned char *key, size_t keylen,
27 const OSSL_PARAM params[]);
28 int OSSL_FUNC_mac_update(void *mctx, const unsigned char *in, size_t inl);
29 int OSSL_FUNC_mac_final(void *mctx, unsigned char *out, size_t *outl, size_t outsize);
31 /* MAC parameter descriptors */
32 const OSSL_PARAM *OSSL_FUNC_mac_gettable_params(void *provctx);
33 const OSSL_PARAM *OSSL_FUNC_mac_gettable_ctx_params(void *mctx, void *provctx);
34 const OSSL_PARAM *OSSL_FUNC_mac_settable_ctx_params(void *mctx, void *provctx);
37 int OSSL_FUNC_mac_get_params(OSSL_PARAM params[]);
38 int OSSL_FUNC_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]);
39 int OSSL_FUNC_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]);
43 This documentation is primarily aimed at provider authors. See L<provider(7)>
44 for further information.
46 The MAC operation enables providers to implement mac algorithms and make
47 them available to applications via the API functions L<EVP_MAC_init(3)>,
48 L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)>.
50 All "functions" mentioned here are passed as function pointers between
51 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
52 B<OSSL_ALGORITHM> arrays that are returned by the provider's
53 provider_query_operation() function
54 (see L<provider-base(7)/Provider Functions>).
56 All these "functions" have a corresponding function type definition
57 named B<OSSL_{name}_fn>, and a helper function to retrieve the
58 function pointer from an B<OSSL_DISPATCH> element named
60 For example, the "function" OSSL_FUNC_mac_newctx() has these:
62 typedef void *(OSSL_OSSL_FUNC_mac_newctx_fn)(void *provctx);
63 static ossl_inline OSSL_OSSL_FUNC_mac_newctx_fn
64 OSSL_FUNC_mac_newctx(const OSSL_DISPATCH *opf);
66 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
67 macros in L<openssl-core_dispatch.h(7)>, as follows:
69 OSSL_FUNC_mac_newctx OSSL_FUNC_MAC_NEWCTX
70 OSSL_FUNC_mac_freectx OSSL_FUNC_MAC_FREECTX
71 OSSL_FUNC_mac_dupctx OSSL_FUNC_MAC_DUPCTX
73 OSSL_FUNC_mac_init OSSL_FUNC_MAC_INIT
74 OSSL_FUNC_mac_update OSSL_FUNC_MAC_UPDATE
75 OSSL_FUNC_mac_final OSSL_FUNC_MAC_FINAL
77 OSSL_FUNC_mac_get_params OSSL_FUNC_MAC_GET_PARAMS
78 OSSL_FUNC_mac_get_ctx_params OSSL_FUNC_MAC_GET_CTX_PARAMS
79 OSSL_FUNC_mac_set_ctx_params OSSL_FUNC_MAC_SET_CTX_PARAMS
81 OSSL_FUNC_mac_gettable_params OSSL_FUNC_MAC_GETTABLE_PARAMS
82 OSSL_FUNC_mac_gettable_ctx_params OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS
83 OSSL_FUNC_mac_settable_ctx_params OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS
85 A mac algorithm implementation may not implement all of these functions.
86 In order to be a consistent set of functions, at least the following functions
87 must be implemented: OSSL_FUNC_mac_newctx(), OSSL_FUNC_mac_freectx(), OSSL_FUNC_mac_init(),
88 OSSL_FUNC_mac_update(), OSSL_FUNC_mac_final().
89 All other functions are optional.
91 =head2 Context Management Functions
93 OSSL_FUNC_mac_newctx() should create and return a pointer to a provider side
94 structure for holding context information during a mac operation.
95 A pointer to this context will be passed back in a number of the other mac
96 operation function calls.
97 The parameter I<provctx> is the provider context generated during provider
98 initialisation (see L<provider(7)>).
100 OSSL_FUNC_mac_freectx() is passed a pointer to the provider side mac context in
101 the I<mctx> parameter.
102 If it receives NULL as I<mctx> value, it should not do anything other than
104 This function should free any resources associated with that context.
106 OSSL_FUNC_mac_dupctx() should duplicate the provider side mac context in the
107 I<mctx> parameter and return the duplicate copy.
109 =head2 Encryption/Decryption Functions
111 OSSL_FUNC_mac_init() initialises a mac operation given a newly created provider
112 side mac context in the I<mctx> parameter. The I<params> are set before setting
113 the MAC I<key> of I<keylen> bytes.
115 OSSL_FUNC_mac_update() is called to supply data for MAC computation of a previously
116 initialised mac operation.
117 The I<mctx> parameter contains a pointer to a previously initialised provider
119 OSSL_FUNC_mac_update() may be called multiple times for a single mac operation.
121 OSSL_FUNC_mac_final() completes the MAC computation started through previous
122 OSSL_FUNC_mac_init() and OSSL_FUNC_mac_update() calls.
123 The I<mctx> parameter contains a pointer to the provider side context.
124 The resulting MAC should be written to I<out> and the amount of data written
125 to I<*outl>, which should not exceed I<outsize> bytes.
126 The same expectations apply to I<outsize> as documented for
129 =head2 Mac Parameters
131 See L<OSSL_PARAM(3)> for further details on the parameters structure used by
134 OSSL_FUNC_mac_get_params() gets details of parameter values associated with the
135 provider algorithm and stores them in I<params>.
137 OSSL_FUNC_mac_set_ctx_params() sets mac parameters associated with the given
138 provider side mac context I<mctx> to I<params>.
139 Any parameter settings are additional to any that were previously set.
141 OSSL_FUNC_mac_get_ctx_params() gets details of currently set parameter values
142 associated with the given provider side mac context I<mctx> and stores them
145 OSSL_FUNC_mac_gettable_params(), OSSL_FUNC_mac_gettable_ctx_params(),
146 and OSSL_FUNC_mac_settable_ctx_params() all return constant B<OSSL_PARAM>
147 arrays as descriptors of the parameters that OSSL_FUNC_mac_get_params(),
148 OSSL_FUNC_mac_get_ctx_params(), and OSSL_FUNC_mac_set_ctx_params()
149 can handle, respectively. OSSL_FUNC_mac_gettable_ctx_params() and
150 OSSL_FUNC_mac_settable_ctx_params() will return the parameters associated
151 with the provider side context I<mctx> in its current state if it is
152 not NULL. Otherwise, they return the parameters associated with the
153 provider side algorithm I<provctx>.
155 All MAC implementations are expected to handle the following parameters:
159 =item with OSSL_FUNC_set_ctx_params():
163 =item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
165 Sets the key in the associated MAC ctx. This is identical to passing a I<key>
166 argument to the OSSL_FUNC_mac_init() function.
170 =item with OSSL_FUNC_get_params():
174 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <integer>
176 Can be used to get the default MAC size (which might be the only allowable
177 MAC size for the implementation).
179 Note that some implementations allow setting the size that the resulting MAC
180 should have as well, see the documentation of the implementation.
188 OSSL_FUNC_mac_newctx() and OSSL_FUNC_mac_dupctx() should return the newly created
189 provider side mac context, or NULL on failure.
191 OSSL_FUNC_mac_init(), OSSL_FUNC_mac_update(), OSSL_FUNC_mac_final(), OSSL_FUNC_mac_get_params(),
192 OSSL_FUNC_mac_get_ctx_params() and OSSL_FUNC_mac_set_ctx_params() should return 1 for
193 success or 0 on error.
195 OSSL_FUNC_mac_gettable_params(), OSSL_FUNC_mac_gettable_ctx_params() and
196 OSSL_FUNC_mac_settable_ctx_params() should return a constant B<OSSL_PARAM>
197 array, or NULL if none is offered.
202 L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
203 L<EVP_MAC-HMAC(7)>, L<EVP_MAC-KMAC(7)>, L<EVP_MAC-Poly1305(7)>,
204 L<EVP_MAC-Siphash(7)>
209 The provider MAC interface was introduced in OpenSSL 3.0.
213 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
215 Licensed under the Apache License 2.0 (the "License"). You may not use
216 this file except in compliance with the License. You can obtain a copy
217 in the file LICENSE in the source distribution or at
218 L<https://www.openssl.org/source/license.html>.