1 =pod 2 3 =head1 NAME 4 5 provider-mac - The mac library E<lt>-E<gt> provider functions 6 7 =head1 SYNOPSIS 8 9 =for openssl multiple includes 10 11 #include <openssl/core_dispatch.h> 12 #include <openssl/core_names.h> 13 14 /* 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. 18 */ 19 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); 24 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_init_skey(void *mctx, const void *key, const OSSL_PARAM params[]); 29 int OSSL_FUNC_mac_update(void *mctx, const unsigned char *in, size_t inl); 30 int OSSL_FUNC_mac_final(void *mctx, unsigned char *out, size_t *outl, size_t outsize); 31 32 /* MAC parameter descriptors */ 33 const OSSL_PARAM *OSSL_FUNC_mac_gettable_params(void *provctx); 34 const OSSL_PARAM *OSSL_FUNC_mac_gettable_ctx_params(void *mctx, void *provctx); 35 const OSSL_PARAM *OSSL_FUNC_mac_settable_ctx_params(void *mctx, void *provctx); 36 37 /* MAC parameters */ 38 int OSSL_FUNC_mac_get_params(OSSL_PARAM params[]); 39 int OSSL_FUNC_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]); 40 int OSSL_FUNC_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]); 41 42 =head1 DESCRIPTION 43 44 This documentation is primarily aimed at provider authors. See L<provider(7)> 45 for further information. 46 47 The MAC operation enables providers to implement mac algorithms and make 48 them available to applications via the API functions L<EVP_MAC_init(3)>, 49 L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)>. 50 51 All "functions" mentioned here are passed as function pointers between 52 F<libcrypto> and the provider in L<OSSL_DISPATCH(3)> arrays via 53 L<OSSL_ALGORITHM(3)> arrays that are returned by the provider's 54 provider_query_operation() function 55 (see L<provider-base(7)/Provider Functions>). 56 57 All these "functions" have a corresponding function type definition 58 named B<OSSL_FUNC_{name}_fn>, and a helper function to retrieve the 59 function pointer from an L<OSSL_DISPATCH(3)> element named 60 B<OSSL_FUNC_{name}>. 61 For example, the "function" OSSL_FUNC_mac_newctx() has these: 62 63 typedef void *(OSSL_FUNC_mac_newctx_fn)(void *provctx); 64 static ossl_inline OSSL_FUNC_mac_newctx_fn 65 OSSL_FUNC_mac_newctx(const OSSL_DISPATCH *opf); 66 67 L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as 68 macros in L<openssl-core_dispatch.h(7)>, as follows: 69 70 OSSL_FUNC_mac_newctx OSSL_FUNC_MAC_NEWCTX 71 OSSL_FUNC_mac_freectx OSSL_FUNC_MAC_FREECTX 72 OSSL_FUNC_mac_dupctx OSSL_FUNC_MAC_DUPCTX 73 74 OSSL_FUNC_mac_init OSSL_FUNC_MAC_INIT 75 OSSL_FUNC_mac_init_skey OSSL_FUNC_MAC_INIT_SKEY 76 OSSL_FUNC_mac_update OSSL_FUNC_MAC_UPDATE 77 OSSL_FUNC_mac_final OSSL_FUNC_MAC_FINAL 78 79 OSSL_FUNC_mac_get_params OSSL_FUNC_MAC_GET_PARAMS 80 OSSL_FUNC_mac_get_ctx_params OSSL_FUNC_MAC_GET_CTX_PARAMS 81 OSSL_FUNC_mac_set_ctx_params OSSL_FUNC_MAC_SET_CTX_PARAMS 82 83 OSSL_FUNC_mac_gettable_params OSSL_FUNC_MAC_GETTABLE_PARAMS 84 OSSL_FUNC_mac_gettable_ctx_params OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS 85 OSSL_FUNC_mac_settable_ctx_params OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS 86 87 A mac algorithm implementation may not implement all of these functions. 88 In order to be a consistent set of functions, at least the following functions 89 must be implemented: OSSL_FUNC_mac_newctx(), OSSL_FUNC_mac_freectx(), 90 at least one of OSSL_FUNC_mac_init() or OSSL_FUNC_mac_init_skey(), 91 OSSL_FUNC_mac_update(), OSSL_FUNC_mac_final(). 92 All other functions are optional. 93 94 =head2 Context Management Functions 95 96 OSSL_FUNC_mac_newctx() should create and return a pointer to a provider side 97 structure for holding context information during a mac operation. 98 A pointer to this context will be passed back in a number of the other mac 99 operation function calls. 100 The parameter I<provctx> is the provider context generated during provider 101 initialisation (see L<provider(7)>). 102 103 OSSL_FUNC_mac_freectx() is passed a pointer to the provider side mac context in 104 the I<mctx> parameter. 105 If it receives NULL as I<mctx> value, it should not do anything other than 106 return. 107 This function should free any resources associated with that context. 108 109 OSSL_FUNC_mac_dupctx() should duplicate the provider side mac context in the 110 I<mctx> parameter and return the duplicate copy. 111 112 =head2 Encryption/Decryption Functions 113 114 OSSL_FUNC_mac_init() initialises a mac operation given a newly created provider 115 side mac context in the I<mctx> parameter. The I<params> are set before setting 116 the MAC I<key> of I<keylen> bytes. 117 118 OSSL_FUNC_mac_init_skey() is similar but uses an opaque provider-specific object 119 to initialize the MAC context. 120 121 OSSL_FUNC_mac_update() is called to supply data for MAC computation of a previously 122 initialised mac operation. 123 The I<mctx> parameter contains a pointer to a previously initialised provider 124 side context. 125 OSSL_FUNC_mac_update() may be called multiple times for a single mac operation. 126 127 OSSL_FUNC_mac_final() completes the MAC computation started through previous 128 OSSL_FUNC_mac_init() and OSSL_FUNC_mac_update() calls. 129 The I<mctx> parameter contains a pointer to the provider side context. 130 The resulting MAC should be written to I<out> and the amount of data written 131 to I<*outl>, which should not exceed I<outsize> bytes. 132 The same expectations apply to I<outsize> as documented for 133 L<EVP_MAC_final(3)>. 134 135 =head2 Mac Parameters 136 137 See L<OSSL_PARAM(3)> for further details on the parameters structure used by 138 these functions. 139 140 OSSL_FUNC_mac_get_params() gets details of parameter values associated with the 141 provider algorithm and stores them in I<params>. 142 143 OSSL_FUNC_mac_set_ctx_params() sets mac parameters associated with the given 144 provider side mac context I<mctx> to I<params>. 145 Any parameter settings are additional to any that were previously set. 146 Passing NULL for I<params> should return true. 147 148 OSSL_FUNC_mac_get_ctx_params() gets details of currently set parameter values 149 associated with the given provider side mac context I<mctx> and stores them 150 in I<params>. 151 Passing NULL for I<params> should return true. 152 153 OSSL_FUNC_mac_gettable_params(), OSSL_FUNC_mac_gettable_ctx_params(), 154 and OSSL_FUNC_mac_settable_ctx_params() all return constant L<OSSL_PARAM(3)> 155 arrays as descriptors of the parameters that OSSL_FUNC_mac_get_params(), 156 OSSL_FUNC_mac_get_ctx_params(), and OSSL_FUNC_mac_set_ctx_params() 157 can handle, respectively. OSSL_FUNC_mac_gettable_ctx_params() and 158 OSSL_FUNC_mac_settable_ctx_params() will return the parameters associated 159 with the provider side context I<mctx> in its current state if it is 160 not NULL. Otherwise, they return the parameters associated with the 161 provider side algorithm I<provctx>. 162 163 All MAC implementations are expected to handle the following parameters: 164 165 =over 4 166 167 =item with OSSL_FUNC_set_ctx_params(): 168 169 =over 4 170 171 =item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string> 172 173 Sets the key in the associated MAC ctx. This is identical to passing a I<key> 174 argument to the OSSL_FUNC_mac_init() function. 175 176 =back 177 178 =item with OSSL_FUNC_get_params(): 179 180 =over 4 181 182 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <integer> 183 184 Can be used to get the default MAC size (which might be the only allowable 185 MAC size for the implementation). 186 187 Note that some implementations allow setting the size that the resulting MAC 188 should have as well, see the documentation of the implementation. 189 190 =back 191 192 =over 4 193 194 =item "size" (B<OSSL_MAC_PARAM_BLOCK_SIZE>) <integer> 195 196 Can be used to get the MAC block size (if supported by the algorithm). 197 198 =back 199 200 =back 201 202 The OpenSSL FIPS provider may support the following parameters: 203 204 =over 4 205 206 =item "fips-indicator" (B<OSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR>) <int> 207 208 A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 209 This may be used after calling the final function. It may return 0 if 210 either "no-short-mac" or "key-check" are set to 0. 211 212 =item "no-short-mac" (B<OSSL_MAC_PARAM_FIPS_NO_SHORT_MAC>) <integer> 213 214 If required this parameter should be set early via an init function. 215 The default value of 1 causes an error when too short MAC output is 216 asked for. Setting this to 0 will ignore the error and set the approved 217 "fips-indicator" to 0. 218 This option breaks FIPS compliance if it causes the approved "fips-indicator" 219 to return 0. 220 221 =item "key-check" (B<OSSL_MAC_PARAM_FIPS_KEY_CHECK>) <integer> 222 223 If required this parameter should be set before OSSL_FUNC_mac_init. 224 The default value of 1 causes an error when small key sizes are 225 asked for. Setting this to 0 will ignore the error and set the approved 226 "fips-indicator" to 0. 227 This option breaks FIPS compliance if it causes the approved "fips-indicator" 228 to return 0. 229 230 =back 231 232 =head1 NOTES 233 234 The MAC life-cycle is described in L<life_cycle-rand(7)>. Providers should 235 ensure that the various transitions listed there are supported. At some point 236 the EVP layer will begin enforcing the listed transitions. 237 238 =head1 RETURN VALUES 239 240 OSSL_FUNC_mac_newctx() and OSSL_FUNC_mac_dupctx() should return the newly created 241 provider side mac context, or NULL on failure. 242 243 OSSL_FUNC_mac_init(), OSSL_FUNC_mac_init_skey(), 244 OSSL_FUNC_mac_update(), OSSL_FUNC_mac_final(), OSSL_FUNC_mac_get_params(), 245 OSSL_FUNC_mac_get_ctx_params() and OSSL_FUNC_mac_set_ctx_params() should return 1 for 246 success or 0 on error. 247 248 OSSL_FUNC_mac_gettable_params(), OSSL_FUNC_mac_gettable_ctx_params() and 249 OSSL_FUNC_mac_settable_ctx_params() should return a constant L<OSSL_PARAM(3)> 250 array, or NULL if none is offered. 251 252 =head1 SEE ALSO 253 254 L<provider(7)>, 255 L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>, 256 L<EVP_MAC-HMAC(7)>, L<EVP_MAC-KMAC(7)>, L<EVP_MAC-Poly1305(7)>, 257 L<EVP_MAC-Siphash(7)>, 258 L<life_cycle-mac(7)>, L<EVP_MAC(3)> 259 260 =head1 HISTORY 261 262 The provider MAC interface was introduced in OpenSSL 3.0. 263 The parameters "no-short-mac" and "fips-indicator" were added in OpenSSL 3.4. 264 265 The function OSSL_FUNC_mac_init_skey() was introduced in OpenSSL 3.5. 266 267 =head1 COPYRIGHT 268 269 Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. 270 271 Licensed under the Apache License 2.0 (the "License"). You may not use 272 this file except in compliance with the License. You can obtain a copy 273 in the file LICENSE in the source distribution or at 274 L<https://www.openssl.org/source/license.html>. 275 276 =cut 277
Indexes created Mon Oct 12 00:27:07 UTC 2026