1=pod 2 3=head1 NAME 4 5life_cycle-kdf - The KDF algorithm life-cycle 6 7=head1 DESCRIPTION 8 9All key derivation functions (KDFs) and pseudo random functions (PRFs) 10go through a number of stages in their life-cycle: 11 12=over 4 13 14=item start 15 16This state represents the KDF/PRF before it has been allocated. It is the 17starting state for any life-cycle transitions. 18 19=item newed 20 21This state represents the KDF/PRF after it has been allocated. 22 23=item deriving 24 25This state represents the KDF/PRF when it is set up and capable of generating 26output. 27 28=item freed 29 30This state is entered when the KDF/PRF is freed. It is the terminal state 31for all life-cycle transitions. 32 33=back 34 35=head2 State Transition Diagram 36 37The usual life-cycle of a KDF/PRF is illustrated: 38 39=begin man 40 41 +-------------------+ 42 | start | 43 +-------------------+ 44 | 45 | EVP_KDF_CTX_new 46 v 47 +-------------------+ 48 | newed | <+ 49 +-------------------+ | 50 | | 51 | EVP_KDF_derive | 52 v | EVP_KDF_CTX_reset 53 EVP_KDF_derive +-------------------+ | 54 + - - - - - - - - | | | 55 ' | deriving | | 56 + - - - - - - - -> | | -+ 57 +-------------------+ 58 | 59 | EVP_KDF_CTX_free 60 v 61 +-------------------+ 62 | freed | 63 +-------------------+ 64 65=end man 66 67=for html <img src="img/kdf.png"> 68 69=head2 Formal State Transitions 70 71This section defines all of the legal state transitions. 72This is the canonical list. 73 74=begin man 75 76 Function Call ------------- Current State ------------- 77 start newed deriving freed 78 EVP_KDF_CTX_new newed 79 EVP_KDF_derive deriving deriving 80 EVP_KDF_CTX_free freed freed freed 81 EVP_KDF_CTX_reset newed newed 82 EVP_KDF_CTX_get_params newed deriving 83 EVP_KDF_CTX_set_params newed deriving 84 EVP_KDF_CTX_gettable_params newed deriving 85 EVP_KDF_CTX_settable_params newed deriving 86 87=end man 88 89=begin html 90 91<table style="border:1px solid; border-collapse:collapse"> 92<tr><th style="border:1px solid" align="left">Function Call</th> 93 <th style="border:1px solid" colspan="4">Current State</th></tr> 94<tr><th style="border:1px solid"></th> 95 <th style="border:1px solid" align="center">start</th> 96 <th style="border:1px solid" align="center">newed</th> 97 <th style="border:1px solid" align="center">deriving</th> 98 <th style="border:1px solid" align="center">freed</th></tr> 99<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_new</th> 100 <td style="border:1px solid" align="center">newed</td> 101 <td style="border:1px solid"></td> 102 <td style="border:1px solid"></td> 103 <td style="border:1px solid"></td></tr> 104<tr><th style="border:1px solid" align="left">EVP_KDF_derive</th> 105 <td style="border:1px solid" align="center"></td> 106 <td style="border:1px solid" align="center">deriving</td> 107 <td style="border:1px solid" align="center">deriving</td> 108 <td style="border:1px solid"></td></tr> 109<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_free</th> 110 <td style="border:1px solid" align="center">freed</td> 111 <td style="border:1px solid" align="center">freed</td> 112 <td style="border:1px solid" align="center">freed</td> 113 <td style="border:1px solid"></td></tr> 114<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_reset</th> 115 <td style="border:1px solid" align="center"></td> 116 <td style="border:1px solid" align="center">newed</td> 117 <td style="border:1px solid" align="center">newed</td> 118 <td style="border:1px solid"></td></tr> 119<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_get_params</th> 120 <td style="border:1px solid" align="center"></td> 121 <td style="border:1px solid" align="center">newed</td> 122 <td style="border:1px solid" align="center">deriving</td> 123 <td style="border:1px solid"></td></tr> 124<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_set_params</th> 125 <td style="border:1px solid" align="center"></td> 126 <td style="border:1px solid" align="center">newed</td> 127 <td style="border:1px solid" align="center">deriving</td> 128 <td style="border:1px solid"></td></tr> 129<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_gettable_params</th> 130 <td style="border:1px solid" align="center"></td> 131 <td style="border:1px solid" align="center">newed</td> 132 <td style="border:1px solid" align="center">deriving</td> 133 <td style="border:1px solid"></td></tr> 134<tr><th style="border:1px solid" align="left">EVP_KDF_CTX_settable_params</th> 135 <td style="border:1px solid" align="center"></td> 136 <td style="border:1px solid" align="center">newed</td> 137 <td style="border:1px solid" align="center">deriving</td> 138 <td style="border:1px solid"></td></tr> 139</table> 140 141=end html 142 143=head1 NOTES 144 145At some point the EVP layer will begin enforcing the transitions described 146herein. 147 148=head1 SEE ALSO 149 150L<provider-kdf(7)>, L<EVP_KDF(3)>. 151 152=head1 HISTORY 153 154The provider KDF interface was introduced in OpenSSL 3.0. 155 156=head1 COPYRIGHT 157 158Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. 159 160Licensed under the Apache License 2.0 (the "License"). You may not use 161this file except in compliance with the License. You can obtain a copy 162in the file LICENSE in the source distribution or at 163L<https://www.openssl.org/source/license.html>. 164 165=cut 166
