diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ssl/SSL_CTX_set_alpn_select_cb.pod | 67 |
1 files changed, 61 insertions, 6 deletions
diff --git a/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/doc/ssl/SSL_CTX_set_alpn_select_cb.pod index d96185c4e2..56c86097b6 100644 --- a/doc/ssl/SSL_CTX_set_alpn_select_cb.pod +++ b/doc/ssl/SSL_CTX_set_alpn_select_cb.pod @@ -3,8 +3,9 @@ =head1 NAME SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, -SSL_select_next_proto, SSL_get0_alpn_selected - handle application layer -protocol negotiation (ALPN) +SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, +SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated +- handle application layer protocol negotiation (ALPN) =head1 SYNOPSIS @@ -21,13 +22,30 @@ protocol negotiation (ALPN) const unsigned char *in, unsigned int inlen, void *arg), void *arg); + void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, + unsigned int *len); + + void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx, + int (*cb)(SSL *ssl, + const unsigned char **out, + unsigned int *outlen, + void *arg), + void *arg); + void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx, + int (*cb)(SSL *s, + unsigned char **out, + unsigned char *outlen, + const unsigned char *in, + unsigned int inlen, + void *arg), + void *arg); int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, const unsigned char *server, unsigned int server_len, const unsigned char *client, unsigned int client_len) - void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, - unsigned int *len); + void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data, + unsigned *len); =head1 DESCRIPTION @@ -59,10 +77,40 @@ B<client>, so it should be copied immediately. If no match is found, the first item in B<client>, B<client_len> is returned in B<out>, B<outlen>. This function can also be used in the NPN callback. +SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a +client needs to select a protocol from the server's provided list, and a +user-defined pointer argument B<arg> which will be passed to this callback. +For the callback itself, B<out> +must be set to point to the selected protocol (which may be within B<in>). +The length of the protocol name must be written into B<outlen>. The +server's advertised protocols are provided in B<in> and B<inlen>. The +callback can assume that B<in> is syntactically valid. The client must +select a protocol. It is fatal to the connection if this callback returns +a value other than B<SSL_TLSEXT_ERR_OK>. The B<arg> parameter is the pointer +set via SSL_CTX_set_next_proto_select_cb(). + +SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called +when a TLS server needs a list of supported protocols for Next Protocol +Negotiation. The returned list must be in protocol-list format, described +below. The list is +returned by setting B<out> to point to it and B<outlen> to its length. This +memory will not be modified, but the B<SSL> does keep a +reference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it +wishes to advertise. Otherwise, no such extension will be included in the +ServerHello. + SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data> with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len> is set to 0 if no protocol has been selected. B<data> must not be freed. +SSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the +client's requested protocol for this connection. If the client did not +request any protocol or NPN is not enabled, then B<data> is set to NULL and +B<len> to 0. Note that +the client can request any protocol it chooses. The value returned from +this function need not be a member of the list of supported protocols +provided by the callback. + =head1 NOTES The protocol-lists must be in wire-format, which is defined as a vector of @@ -125,14 +173,21 @@ this connection. =back +The callback set using SSL_CTX_set_next_proto_select_cb() should return +B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection. + +The callback set using SSL_CTX_set_next_protos_advertised_cb() should return +B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension +will be included in the ServerHello. + =head1 SEE ALSO -L<ssl(3)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, +L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, L<SSL_CTX_set_tlsext_servername_arg(3)> =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy |