1 =pod 2 3 =head1 NAME 4 5 life_cycle-mac - The MAC algorithm life-cycle 6 7 =head1 DESCRIPTION 8 9 All message authentication codes (MACs) 10 go through a number of stages in their life-cycle: 11 12 =over 4 13 14 =item start 15 16 This state represents the MAC before it has been allocated. It is the 17 starting state for any life-cycle transitions. 18 19 =item newed 20 21 This state represents the MAC after it has been allocated. 22 23 =item initialised 24 25 This state represents the MAC when it is set up and capable of processing 26 input. 27 28 =item updated 29 30 This state represents the MAC when it is set up and capable of processing 31 additional input or generating output. 32 33 =item finaled 34 35 This state represents the MAC when it has generated output. 36 37 =item freed 38 39 This state is entered when the MAC is freed. It is the terminal state 40 for all life-cycle transitions. 41 42 =back 43 44 =head2 State Transition Diagram 45 46 The usual life-cycle of a MAC is illustrated: 47 48 =begin man 49 50 +-------------------+ 51 | start | 52 +-------------------+ 53 | 54 | EVP_MAC_CTX_new 55 v 56 +-------------------+ 57 | newed | 58 +-------------------+ 59 | 60 | EVP_MAC_init 61 v 62 +-------------------+ 63 +> | initialised | <+ 64 | +-------------------+ | 65 | | | 66 | | EVP_MAC_update | EVP_MAC_init 67 | v | 68 EVP_MAC_init | +-------------------+ | 69 | | updated | -+ 70 | +-------------------+ 71 | | | 72 | | EVP_MAC_final | EVP_MAC_finalXOF 73 | v v 74 | +-------------------+ 75 +- | finaled | 76 +-------------------+ 77 | 78 | EVP_MAC_CTX_free 79 v 80 +-------------------+ 81 | freed | 82 +-------------------+ 83 84 =end man 85 86 =for html <img src="img/mac.png"> 87 88 =head2 Formal State Transitions 89 90 This section defines all of the legal state transitions. 91 This is the canonical list. 92 93 =begin man 94 95 Function Call --------------------- Current State ---------------------- 96 start newed initialised updated finaled freed 97 EVP_MAC_CTX_new newed 98 EVP_MAC_init initialised initialised initialised initialised 99 EVP_MAC_update updated updated 100 EVP_MAC_final finaled 101 EVP_MAC_finalXOF finaled 102 EVP_MAC_CTX_free freed freed freed freed freed 103 EVP_MAC_CTX_get_params newed initialised updated 104 EVP_MAC_CTX_set_params newed initialised updated 105 EVP_MAC_CTX_gettable_params newed initialised updated 106 EVP_MAC_CTX_settable_params newed initialised updated 107 108 =end man 109 110 =begin html 111 112 <table style="border:1px solid; border-collapse:collapse"> 113 <tr><th style="border:1px solid" align="left">Function Call</th> 114 <th style="border:1px solid" colspan="6">Current State</th></tr> 115 <tr><th style="border:1px solid"></th> 116 <th style="border:1px solid" align="center">start</th> 117 <th style="border:1px solid" align="center">newed</th> 118 <th style="border:1px solid" align="center">initialised</th> 119 <th style="border:1px solid" align="center">updated</th> 120 <th style="border:1px solid" align="center">finaled</th> 121 <th style="border:1px solid" align="center">freed</th></tr> 122 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_new</th> 123 <td style="border:1px solid" align="center">newed</td> 124 <td style="border:1px solid" align="center"></td> 125 <td style="border:1px solid" align="center"></td> 126 <td style="border:1px solid" align="center"></td> 127 <td style="border:1px solid" align="center"></td> 128 <td style="border:1px solid" align="center"></td></tr> 129 <tr><th style="border:1px solid" align="left">EVP_MAC_init</th> 130 <td style="border:1px solid" align="center"></td> 131 <td style="border:1px solid" align="center">initialised</td> 132 <td style="border:1px solid" align="center">initialised</td> 133 <td style="border:1px solid" align="center">initialised</td> 134 <td style="border:1px solid" align="center">initialised</td> 135 <td style="border:1px solid" align="center"></td></tr> 136 <tr><th style="border:1px solid" align="left">EVP_MAC_update</th> 137 <td style="border:1px solid" align="center"></td> 138 <td style="border:1px solid" align="center"></td> 139 <td style="border:1px solid" align="center">updated</td> 140 <td style="border:1px solid" align="center">updated</td> 141 <td style="border:1px solid" align="center"></td> 142 <td style="border:1px solid" align="center"></td></tr> 143 <tr><th style="border:1px solid" align="left">EVP_MAC_final</th> 144 <td style="border:1px solid" align="center"></td> 145 <td style="border:1px solid" align="center"></td> 146 <td style="border:1px solid" align="center"></td> 147 <td style="border:1px solid" align="center">finaled</td> 148 <td style="border:1px solid" align="center"></td> 149 <td style="border:1px solid" align="center"></td></tr> 150 <tr><th style="border:1px solid" align="left">EVP_MAC_finalXOF</th> 151 <td style="border:1px solid" align="center"></td> 152 <td style="border:1px solid" align="center"></td> 153 <td style="border:1px solid" align="center"></td> 154 <td style="border:1px solid" align="center">finaled</td> 155 <td style="border:1px solid" align="center"></td> 156 <td style="border:1px solid" align="center"></td></tr> 157 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_free</th> 158 <td style="border:1px solid" align="center">freed</td> 159 <td style="border:1px solid" align="center">freed</td> 160 <td style="border:1px solid" align="center">freed</td> 161 <td style="border:1px solid" align="center">freed</td> 162 <td style="border:1px solid" align="center">freed</td> 163 <td style="border:1px solid" align="center"></td></tr> 164 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_get_params</th> 165 <td style="border:1px solid" align="center"></td> 166 <td style="border:1px solid" align="center">newed</td> 167 <td style="border:1px solid" align="center">initialised</td> 168 <td style="border:1px solid" align="center">updated</td> 169 <td style="border:1px solid" align="center"></td> 170 <td style="border:1px solid" align="center"></td></tr> 171 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_set_params</th> 172 <td style="border:1px solid" align="center"></td> 173 <td style="border:1px solid" align="center">newed</td> 174 <td style="border:1px solid" align="center">initialised</td> 175 <td style="border:1px solid" align="center">updated</td> 176 <td style="border:1px solid" align="center"></td> 177 <td style="border:1px solid" align="center"></td></tr> 178 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_gettable_params</th> 179 <td style="border:1px solid" align="center"></td> 180 <td style="border:1px solid" align="center">newed</td> 181 <td style="border:1px solid" align="center">initialised</td> 182 <td style="border:1px solid" align="center">updated</td> 183 <td style="border:1px solid" align="center"></td> 184 <td style="border:1px solid" align="center"></td></tr> 185 <tr><th style="border:1px solid" align="left">EVP_MAC_CTX_settable_params</th> 186 <td style="border:1px solid" align="center"></td> 187 <td style="border:1px solid" align="center">newed</td> 188 <td style="border:1px solid" align="center">initialised</td> 189 <td style="border:1px solid" align="center">updated</td> 190 <td style="border:1px solid" align="center"></td> 191 <td style="border:1px solid" align="center"></td></tr> 192 </table> 193 194 =end html 195 196 =head1 NOTES 197 198 At some point the EVP layer will begin enforcing the transitions described 199 herein. 200 201 =head1 SEE ALSO 202 203 L<provider-mac(7)>, L<EVP_MAC(3)>. 204 205 =head1 HISTORY 206 207 The provider MAC interface was introduced in OpenSSL 3.0. 208 209 =head1 COPYRIGHT 210 211 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. 212 213 Licensed under the Apache License 2.0 (the "License"). You may not use 214 this file except in compliance with the License. You can obtain a copy 215 in the file LICENSE in the source distribution or at 216 L<https://www.openssl.org/source/license.html>. 217 218 =cut 219
Indexes created Fri Oct 09 00:27:48 UTC 2026