[openssl-commits] [openssl] OpenSSL_1_1_0-stable update
Rich Salz
rsalz at openssl.org
Wed Apr 19 16:48:46 UTC 2017
The branch OpenSSL_1_1_0-stable has been updated
via 48e017b9ca6876f709197de22b986e8238868ce4 (commit)
from cff4c7b9d01ebe68217d491841424b8223d8507d (commit)
- Log -----------------------------------------------------------------
commit 48e017b9ca6876f709197de22b986e8238868ce4
Author: Rich Salz <rsalz at openssl.org>
Date: Wed Apr 19 12:38:27 2017 -0400
Document Next Protocol Negotiation APIs
Add callback function prototypes, fix description
Reviewed-by: Kurt Roeckx <kurt at openssl.org>
Reviewed-by: Rich Salz <rsalz at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3084)
(cherry picked from commit 87b81496fec2f969371b3167dea3b6aaed9f9f9d)
-----------------------------------------------------------------------
Summary of changes:
doc/ssl/SSL_CTX_set_alpn_select_cb.pod | 67 +++++++++++++++++++++++++++++++---
1 file 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 d96185c..56c8609 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
More information about the openssl-commits
mailing list