| Matt Caswell | 249e3a1 | 2017-03-24 17:37:23 +0000 | [diff] [blame] | 1 | =pod |
| 2 | |
| 3 | =head1 NAME |
| 4 | |
| 5 | SSL_in_before, |
| 6 | SSL_in_init, |
| 7 | SSL_is_init_finished, |
| 8 | SSL_in_connect_init, |
| 9 | SSL_in_accept_init, |
| 10 | SSL_get_state |
| 11 | - retrieve information about the handshake state machine |
| 12 | |
| 13 | =head1 SYNOPSIS |
| 14 | |
| 15 | #include <openssl/ssl.h> |
| 16 | |
| 17 | int SSL_in_init(SSL *s); |
| 18 | int SSL_in_before(SSL *s); |
| 19 | int SSL_is_init_finished(SSL *s); |
| 20 | |
| 21 | int SSL_in_connect_init(SSL *s); |
| 22 | int SSL_in_accept_init(SSL *s); |
| 23 | |
| 24 | OSSL_HANDSHAKE_STATE SSL_get_state(const SSL *ssl); |
| 25 | |
| 26 | =head1 DESCRIPTION |
| 27 | |
| 28 | SSL_in_init() returns 1 if the SSL/TLS state machine is currently processing or |
| 29 | awaiting handshake messages, or 0 otherwise. |
| 30 | |
| 31 | SSL_in_before() returns 1 if no SSL/TLS handshake has yet been initiated, or 0 |
| 32 | otherwise. |
| 33 | |
| 34 | SSL_is_init_finished() returns 1 if the SSL/TLS connection is in a state where |
| 35 | fully protected application data can be transferred or 0 otherwise. |
| 36 | |
| 37 | Note that in some circumstances (such as when early data is being transferred) |
| 38 | SSL_in_init(), SSL_in_before() and SSL_is_init_finished() can all return 0. |
| 39 | |
| 40 | SSL_in_connect_init() returns 1 if B<s> is acting as a client and SSL_in_init() |
| 41 | would return 1, or 0 otherwise. |
| 42 | |
| 43 | SSL_in_accept_init() returns 1 if B<s> is acting as a server and SSL_in_init() |
| 44 | would return 1, or 0 otherwise. |
| 45 | |
| 46 | SSL_in_connect_init() and SSL_in_accept_init() are implemented as macros. |
| 47 | |
| 48 | SSL_get_state() returns a value indicating the current state of the handshake |
| 49 | state machine. OSSL_HANDSHAKE_STATE is an enumerated type where each value |
| 50 | indicates a discrete state machine state. Note that future versions of OpenSSL |
| 51 | may define more states so applications should expect to receive unrecognised |
| 52 | state values. The naming format is made up of a number of elements as follows: |
| 53 | |
| 54 | B<protocol>_ST_B<role>_B<message> |
| 55 | |
| 56 | B<protocol> is one of TLS or DTLS. DTLS is used where a state is specific to the |
| 57 | DTLS protocol. Otherwise TLS is used. |
| 58 | |
| 59 | B<role> is one of CR, CW, SR or SW to indicate "client reading", |
| 60 | "client writing", "server reading" or "server writing" respectively. |
| 61 | |
| 62 | B<message> is the name of a handshake message that is being or has been sent, or |
| 63 | is being or has been processed. |
| 64 | |
| 65 | Additionally there are some special states that do not conform to the above |
| 66 | format. These are: |
| 67 | |
| 68 | =over 4 |
| 69 | |
| 70 | =item TLS_ST_BEFORE |
| 71 | |
| 72 | No handshake messages have yet been been sent or received. |
| 73 | |
| 74 | =item TLS_ST_OK |
| 75 | |
| 76 | Handshake message sending/processing has completed. |
| 77 | |
| 78 | =item TLS_ST_EARLY_DATA |
| 79 | |
| 80 | Early data is being processed |
| 81 | |
| 82 | =item TLS_ST_PENDING_EARLY_DATA_END |
| 83 | |
| 84 | Awaiting the end of early data processing |
| 85 | |
| 86 | =back |
| 87 | |
| 88 | =head1 RETURN VALUES |
| 89 | |
| 90 | SSL_in_init(), SSL_in_before(), SSL_is_init_finished(), SSL_in_connect_init() |
| 91 | and SSL_in_accept_init() return values as indicated above. |
| 92 | |
| 93 | SSL_get_state() returns the current handshake state. |
| 94 | |
| 95 | |
| 96 | =head1 SEE ALSO |
| 97 | |
| 98 | L<ssl(7)>, |
| 99 | L<SSL_read_early_data(3)> |
| 100 | |
| 101 | =head1 COPYRIGHT |
| 102 | |
| 103 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. |
| 104 | |
| 105 | Licensed under the OpenSSL license (the "License"). You may not use |
| 106 | this file except in compliance with the License. You can obtain a copy |
| 107 | in the file LICENSE in the source distribution or at |
| 108 | L<https://www.openssl.org/source/license.html>. |
| 109 | |
| 110 | =cut |
