2021-06-07 13:11:28 +08:00
|
|
|
=pod
|
|
|
|
|
|
|
|
|
|
=head1 NAME
|
|
|
|
|
|
|
|
|
|
life_cycle-cipher - The cipher algorithm life-cycle
|
|
|
|
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
|
|
|
|
|
All symmetric ciphers (CIPHERs) go through a number of stages in their
|
|
|
|
|
life-cycle:
|
|
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
|
|
=item start
|
|
|
|
|
|
|
|
|
|
This state represents the CIPHER before it has been allocated. It is the
|
|
|
|
|
starting state for any life-cycle transitions.
|
|
|
|
|
|
|
|
|
|
=item newed
|
|
|
|
|
|
|
|
|
|
This state represents the CIPHER after it has been allocated.
|
|
|
|
|
|
|
|
|
|
=item initialised
|
|
|
|
|
|
|
|
|
|
These states represent the CIPHER when it is set up and capable of processing
|
|
|
|
|
input. There are three possible initialised states:
|
|
|
|
|
|
|
|
|
|
=over 4
|
|
|
|
|
|
|
|
|
|
=item initialised using EVP_CipherInit
|
|
|
|
|
|
|
|
|
|
=item initialised for decryption using EVP_DecryptInit
|
|
|
|
|
|
|
|
|
|
=item initialised for encryption using EVP_EncryptInit
|
|
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
|
|
=item updated
|
|
|
|
|
|
|
|
|
|
These states represent the CIPHER when it is set up and capable of processing
|
|
|
|
|
additional input or generating output. The three possible states directly
|
|
|
|
|
correspond to those for initialised above. The three different streams should
|
|
|
|
|
not be mixed.
|
|
|
|
|
|
|
|
|
|
=item finaled
|
|
|
|
|
|
|
|
|
|
This state represents the CIPHER when it has generated output.
|
|
|
|
|
|
|
|
|
|
=item freed
|
|
|
|
|
|
|
|
|
|
This state is entered when the CIPHER is freed. It is the terminal state
|
|
|
|
|
for all life-cycle transitions.
|
|
|
|
|
|
|
|
|
|
=back
|
|
|
|
|
|
|
|
|
|
=head2 State Transition Diagram
|
|
|
|
|
|
|
|
|
|
The usual life-cycle of a CIPHER is illustrated:
|
|
|
|
|
|
|
|
|
|
=begin man
|
|
|
|
|
|
|
|
|
|
+---------------------------+
|
|
|
|
|
| |
|
|
|
|
|
| start |
|
|
|
|
|
| |
|
|
|
|
|
+---------------------------+ + - - - - - - - - - - - - - +
|
|
|
|
|
| ' any of the initialised '
|
|
|
|
|
| EVP_CIPHER_CTX_new ' updated or finaled states '
|
|
|
|
|
v ' '
|
|
|
|
|
+---------------------------+ + - - - - - - - - - - - - - +
|
|
|
|
|
| | |
|
|
|
|
|
| newed | | EVP_CIPHER_CTX_reset
|
|
|
|
|
| | <----+
|
|
|
|
|
+---------------------------+
|
|
|
|
|
| | |
|
|
|
|
|
+---------+ | +---------+
|
|
|
|
|
EVP_DecryptInit | | EVP_CipherInit | EVP_EncryptInit
|
|
|
|
|
v v v
|
|
|
|
|
+---------------------------+ +---------------------------+ +---------------------------+
|
|
|
|
|
| | | | | |
|
|
|
|
|
| initialised | | initialised | | initialised |
|
|
|
|
|
| for decryption | | | | for encryption |
|
|
|
|
|
+---------------------------+ +---------------------------+ +---------------------------+
|
|
|
|
|
| | |
|
|
|
|
|
| EVP_DecryptUpdate | EVP_CipherUpdate EVP_EncryptUpdate |
|
|
|
|
|
| v |
|
|
|
|
|
| +---------------------------+ |
|
|
|
|
|
| | |--------------------+ |
|
|
|
|
|
| | updated | EVP_CipherUpdate | |
|
|
|
|
|
| | | <------------------+ |
|
|
|
|
|
v +---------------------------+ v
|
|
|
|
|
+---------------------------+ | +---------------------------+
|
|
|
|
|
| |---------------------+ | | |
|
|
|
|
|
| updated | EVP_DecryptUpdate | | | updated |------+
|
|
|
|
|
| for decryption | <-------------------+ | | for encryption | |
|
|
|
|
|
+---------------------------+ | +---------------------------+ |
|
|
|
|
|
| EVP_CipherFinal | | ^ |
|
|
|
|
|
+-------+ | +--------+ | |
|
|
|
|
|
EVP_DecryptFinal | | | EVP_EncryptFinal +-------------------+
|
|
|
|
|
v v v EVP_EncryptUpdate
|
|
|
|
|
+---------------------------+
|
|
|
|
|
| |-----------------------------+
|
|
|
|
|
| finaled | |
|
|
|
|
|
| | <---------------------------+
|
|
|
|
|
+---------------------------+ EVP_CIPHER_CTX_get_params
|
|
|
|
|
| (AEAD encryption)
|
|
|
|
|
| EVP_CIPHER_CTX_free
|
|
|
|
|
v
|
|
|
|
|
+---------------------------+
|
|
|
|
|
| |
|
|
|
|
|
| freed |
|
|
|
|
|
| |
|
|
|
|
|
+---------------------------+
|
|
|
|
|
|
|
|
|
|
=end man
|
|
|
|
|
|
|
|
|
|
=for html <img src="img/cipher.png">
|
|
|
|
|
|
|
|
|
|
=head2 Formal State Transitions
|
|
|
|
|
|
|
|
|
|
This section defines all of the legal state transitions.
|
|
|
|
|
This is the canonical list.
|
|
|
|
|
|
|
|
|
|
=begin man
|
|
|
|
|
|
|
|
|
|
Function Call ---------------------------------------------- Current State -----------------------------------------------
|
|
|
|
|
start newed initialised updated finaled initialised updated initialised updated freed
|
|
|
|
|
decryption decryption encryption encryption
|
2021-09-21 08:59:56 +08:00
|
|
|
EVP_CIPHER_CTX_new newed
|
2021-06-07 13:11:28 +08:00
|
|
|
EVP_CipherInit initialised initialised initialised initialised initialised initialised initialised initialised
|
|
|
|
|
EVP_DecryptInit initialised initialised initialised initialised initialised initialised initialised initialised
|
2021-09-21 08:59:56 +08:00
|
|
|
decryption decryption decryption decryption decryption decryption decryption decryption
|
2021-06-07 13:11:28 +08:00
|
|
|
EVP_EncryptInit initialised initialised initialised initialised initialised initialised initialised initialised
|
2021-09-21 08:59:56 +08:00
|
|
|
encryption encryption encryption encryption encryption encryption encryption encryption
|
2021-06-07 13:11:28 +08:00
|
|
|
EVP_CipherUpdate updated updated
|
|
|
|
|
EVP_DecryptUpdate updated updated
|
|
|
|
|
decryption decryption
|
|
|
|
|
EVP_EncryptUpdate updated updated
|
|
|
|
|
encryption encryption
|
|
|
|
|
EVP_CipherFinal finaled
|
|
|
|
|
EVP_DecryptFinal finaled
|
|
|
|
|
EVP_EncryptFinal finaled
|
|
|
|
|
EVP_CIPHER_CTX_free freed freed freed freed freed freed freed freed freed
|
|
|
|
|
EVP_CIPHER_CTX_reset newed newed newed newed newed newed newed newed
|
|
|
|
|
EVP_CIPHER_CTX_get_params newed initialised updated initialised updated initialised updated
|
|
|
|
|
decryption decryption encryption encryption
|
|
|
|
|
EVP_CIPHER_CTX_set_params newed initialised updated initialised updated initialised updated
|
|
|
|
|
decryption decryption encryption encryption
|
|
|
|
|
EVP_CIPHER_CTX_gettable_params newed initialised updated initialised updated initialised updated
|
|
|
|
|
decryption decryption encryption encryption
|
|
|
|
|
EVP_CIPHER_CTX_settable_params newed initialised updated initialised updated initialised updated
|
|
|
|
|
decryption decryption encryption encryption
|
|
|
|
|
|
|
|
|
|
=end man
|
|
|
|
|
|
|
|
|
|
=begin html
|
|
|
|
|
|
|
|
|
|
<table style="border:1px solid; border-collapse:collapse">
|
|
|
|
|
<tr><th style="border:1px solid" align="left">Function Call</th>
|
|
|
|
|
<th style="border:1px solid" colspan="10">Current State</th></tr>
|
|
|
|
|
<tr><th style="border:1px solid"></th>
|
|
|
|
|
<th style="border:1px solid" align="center">start</th>
|
|
|
|
|
<th style="border:1px solid" align="center">newed</th>
|
|
|
|
|
<th style="border:1px solid" align="center">initialised</th>
|
|
|
|
|
<th style="border:1px solid" align="center">updated</th>
|
|
|
|
|
<th style="border:1px solid" align="center">finaled</th>
|
|
|
|
|
<th style="border:1px solid" align="center">initialised<br>decryption</th>
|
|
|
|
|
<th style="border:1px solid" align="center">updated<br>decryption</th>
|
|
|
|
|
<th style="border:1px solid" align="center">initialised<br>encryption</th>
|
|
|
|
|
<th style="border:1px solid" align="center">updated<br>encryption</th>
|
|
|
|
|
<th style="border:1px solid" align="center">freed</th></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_new</th>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CipherInit</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_DecryptInit</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_EncryptInit</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CipherUpdate</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_DecryptUpdate</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_EncryptUpdate</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CipherFinal</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">finaled</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_DecryptFinal</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">finaled<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_EncryptFinal</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">finaled<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_free</th>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">freed</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_reset</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_get_params</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_set_params</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_gettable_params</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
<tr><th style="border:1px solid" align="left">EVP_CIPHER_CTX_settable_params</th>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">newed</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>decryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">initialised<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center">updated<br>encryption</td>
|
|
|
|
|
<td style="border:1px solid" align="center"></td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
=end html
|
|
|
|
|
|
|
|
|
|
=head1 NOTES
|
|
|
|
|
|
|
|
|
|
At some point the EVP layer will begin enforcing the transitions described
|
|
|
|
|
herein.
|
|
|
|
|
|
|
|
|
|
=head1 SEE ALSO
|
|
|
|
|
|
|
|
|
|
L<provider-cipher(7)>, L<EVP_EncryptInit(3)>
|
|
|
|
|
|
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
|
|
|
|
|
|
Copyright 2021 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
|
