SSL_set_session_secret_cb¶

NAME¶

SSL_set_session_secret_cb, tls_session_secret_cb_fn, SSL_set_session_ticket_ext, SSL_set_session_ticket_ext_cb, tls_session_ticket_ext_cb_fn - set the session secret and EAP-FAST session ticket extension callbacks

SYNOPSIS¶

#include <openssl/ssl.h>

typedef int (*tls_session_secret_cb_fn)(SSL *s, void *secret, int *secret_len,
                                        STACK_OF(SSL_CIPHER) *peer_ciphers,
                                        const SSL_CIPHER **cipher, void *arg);

int SSL_set_session_secret_cb(SSL *s,
                              tls_session_secret_cb_fn session_secret_cb,
                              void *arg);

typedef int (*tls_session_ticket_ext_cb_fn)(SSL *s, const unsigned char *data,
                                            int len, void *arg);

int SSL_set_session_ticket_ext(SSL *s, void *ext_data, int ext_len);

int SSL_set_session_ticket_ext_cb(SSL *s,
                                  tls_session_ticket_ext_cb_fn cb,
                                  void *arg);

DESCRIPTION¶

SSL_set_session_secret_cb() sets the session secret callback to be used (session_secret_cb), and an optional argument (arg) to be passed to that callback when it is called. This is only useful for an implementation of EAP-FAST (RFC4851). The presence of the callback also modifies the internal OpenSSL TLS state machine to match the modified TLS behaviour as described in RFC4851. Therefore this callback should not be used except when implementing EAP-FAST.

The callback is expected to set the master secret to be used by filling in the data pointed to by *secret. The size of the secret buffer is initially available in *secret_len and may be updated by the callback (but must not be larger than the initial value).

On the server side the set of ciphersuites offered by the peer is provided in the peer_ciphers stack. Optionally the callback may select the preferred ciphersuite by setting it in *cipher.

On the client side the peer_ciphers stack will always be NULL. The callback may specify the preferred cipher in *cipher and this will be associated with the SSL_SESSION - but it does not affect the ciphersuite selected by the server.

The callback is also supplied with an additional argument in arg which is the argument that was provided to the original SSL_set_session_secret_cb() call.

SSL_set_session_ticket_ext() is used on the client-side to set the session ticket extension data for EAP-FAST (RFC4851). The ext_data argument is a pointer to the extension data, and ext_len is the length of that data. ext_len must be between 0 and 65535. If ext_data is NULL, then the session ticket extension will not be sent.

SSL_set_session_ticket_ext_cb() is used on the server-side to set a callback (cb) that will be called when a session ticket extension is received. The callback is supplied with the extension data in data and its length in len, as well as the additional argument arg that was provided when the callback was set.

RETURN VALUES¶

SSL_set_session_secret_cb(), SSL_set_session_ticket_ext(), and SSL_set_session_ticket_ext_cb() return 1 on success and 0 on failure.

If the session secret callback returns 1 then this indicates it has successfully set the secret. A return value of 0 indicates that the secret has not been set. On the client this will cause an immediate abort of the handshake.

The session ticket extension callback should return 1 for success. A return value of 0 indicates failure and will cause the handshake to abort immediately.

COPYRIGHT¶

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 https://www.openssl.org/source/license.html.