doc/man3/SSL_CTX_set_alpn_select_cb.pod - third_party/openssl - Git at Google

 =pod

 =head1 NAME

 SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
 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

  #include <openssl/ssl.h>

  int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
                              unsigned int protos_len);
  int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
                          unsigned int protos_len);
  void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
                                  int (*cb) (SSL *ssl,
                                             const unsigned char **out,
                                             unsigned char *outlen,
                                             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_next_proto_negotiated(const SSL *s, const unsigned char **data,
                              unsigned *len);

 =head1 DESCRIPTION

 SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
 set the list of protocols available to be negotiated. The B<protos> must be in
 protocol-list format, described below. The length of B<protos> is specified in
 B<protos_len>.

 SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
 server to select which protocol to use for the incoming connection. When B<cb>
 is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
 the application callback.

 B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
 vector in protocol-list format. The value of the B<out>, B<outlen> vector
 should be set to the value of a single protocol selected from the B<in>,
 B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
 buffer that outlives the handshake. The B<arg> parameter is the pointer set via
 SSL_CTX_set_alpn_select_cb().

 SSL_select_next_proto() is a helper function used to select protocols. It
 implements the standard protocol selection. It is expected that this function
 is called from the application callback B<cb>. The protocol data in B<server>,
 B<server_len> and B<client>, B<client_len> must be in the protocol-list format
 described below. The first item in the B<server>, B<server_len> list that
 matches an item in the B<client>, B<client_len> list is selected, and returned
 in B<out>, B<outlen>. The B<out> value will point into either B<server> or
 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
 nonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
 included in the length. Each string is limited to 255 bytes. A byte-string
 length of 0 is invalid. A truncated byte-string is invalid. The length of the
 vector is not in the vector itself, but in a separate variable.

 Example:

  unsigned char vector[] = {
      6, 's', 'p', 'd', 'y', '/', '1',
      8, 'h', 't', 't', 'p', '/', '1', '.', '1'
  };
  unsigned int length = sizeof(vector);

 The ALPN callback is executed after the servername callback; as that servername
 callback may update the SSL_CTX, and subsequently, the ALPN callback.

 If there is no ALPN proposed in the ClientHello, the ALPN callback is not
 invoked.

 =head1 RETURN VALUES

 SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
 non-0 on failure. WARNING: these functions reverse the return value convention.

 SSL_select_next_proto() returns one of the following:

 =over 4

 =item OPENSSL_NPN_NEGOTIATED

 A match was found and is returned in B<out>, B<outlen>.

 =item OPENSSL_NPN_NO_OVERLAP

 No match was found. The first item in B<client>, B<client_len> is returned in
 B<out>, B<outlen>.

 =back

 The ALPN select callback B<cb>, must return one of the following:

 =over 4

 =item SSL_TLSEXT_ERR_OK

 ALPN protocol selected.

 =item SSL_TLSEXT_ERR_ALERT_FATAL

 There was no overlap between the client's supplied list and the server
 configuration.

 =item SSL_TLSEXT_ERR_NOACK

 ALPN protocol not selected, e.g., because no ALPN protocols are configured for
 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(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
 L<SSL_CTX_set_tlsext_servername_arg(3)>

 =head1 COPYRIGHT

 Copyright 2016-2020 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
	=pod

	=head1 NAME

	SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
	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

	#include <openssl/ssl.h>

	int SSL_CTX_set_alpn_protos(SSL_CTX ctx, const unsigned char protos,
	unsigned int protos_len);
	int SSL_set_alpn_protos(SSL ssl, const unsigned char protos,
	unsigned int protos_len);
	void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
	int (cb) (SSL ssl,
	const unsigned char **out,
	unsigned char *outlen,
	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_next_proto_negotiated(const SSL s, const unsigned char *data,
	unsigned *len);

	=head1 DESCRIPTION

	SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
	set the list of protocols available to be negotiated. The B<protos> must be in
	protocol-list format, described below. The length of B<protos> is specified in
	B<protos_len>.

	SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
	server to select which protocol to use for the incoming connection. When B<cb>
	is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
	the application callback.

	B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
	vector in protocol-list format. The value of the B<out>, B<outlen> vector
	should be set to the value of a single protocol selected from the B<in>,
	B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
	buffer that outlives the handshake. The B<arg> parameter is the pointer set via
	SSL_CTX_set_alpn_select_cb().

	SSL_select_next_proto() is a helper function used to select protocols. It
	implements the standard protocol selection. It is expected that this function
	is called from the application callback B<cb>. The protocol data in B<server>,
	B<server_len> and B<client>, B<client_len> must be in the protocol-list format
	described below. The first item in the B<server>, B<server_len> list that
	matches an item in the B<client>, B<client_len> list is selected, and returned
	in B<out>, B<outlen>. The B<out> value will point into either B<server> or
	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
	nonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
	included in the length. Each string is limited to 255 bytes. A byte-string
	length of 0 is invalid. A truncated byte-string is invalid. The length of the
	vector is not in the vector itself, but in a separate variable.

	Example:

	unsigned char vector[] = {
	6, 's', 'p', 'd', 'y', '/', '1',
	8, 'h', 't', 't', 'p', '/', '1', '.', '1'
	};
	unsigned int length = sizeof(vector);

	The ALPN callback is executed after the servername callback; as that servername
	callback may update the SSL_CTX, and subsequently, the ALPN callback.

	If there is no ALPN proposed in the ClientHello, the ALPN callback is not
	invoked.

	=head1 RETURN VALUES

	SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
	non-0 on failure. WARNING: these functions reverse the return value convention.

	SSL_select_next_proto() returns one of the following:

	=over 4

	=item OPENSSL_NPN_NEGOTIATED

	A match was found and is returned in B<out>, B<outlen>.

	=item OPENSSL_NPN_NO_OVERLAP

	No match was found. The first item in B<client>, B<client_len> is returned in
	B<out>, B<outlen>.

	=back

	The ALPN select callback B<cb>, must return one of the following:

	=over 4

	=item SSL_TLSEXT_ERR_OK

	ALPN protocol selected.

	=item SSL_TLSEXT_ERR_ALERT_FATAL

	There was no overlap between the client's supplied list and the server
	configuration.

	=item SSL_TLSEXT_ERR_NOACK

	ALPN protocol not selected, e.g., because no ALPN protocols are configured for
	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(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
	L<SSL_CTX_set_tlsext_servername_arg(3)>

	=head1 COPYRIGHT

	Copyright 2016-2020 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