From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- .../doc/ssl/SSL_CTX_set_alpn_select_cb.pod | 197 +++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod (limited to 'openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod') diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod new file mode 100644 index 0000000..56c8609 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod @@ -0,0 +1,197 @@ +=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 + + 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 must be in +protocol-list format, described below. The length of B is specified in +B. + +SSL_CTX_set_alpn_select_cb() sets the application callback B used by a +server to select which protocol to use for the incoming connection. When B +is NULL, ALPN is not used. The B value is a pointer which is passed to +the application callback. + +B is the application defined callback. The B, B parameters are a +vector in protocol-list format. The value of the B, B vector +should be set to the value of a single protocol selected from the B, +B vector. The B buffer may point directly into B, or to a +buffer that outlives the handshake. The B 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. The protocol data in B, +B and B, B must be in the protocol-list format +described below. The first item in the B, B list that +matches an item in the B, B list is selected, and returned +in B, B. The B value will point into either B or +B, so it should be copied immediately. If no match is found, the first +item in B, B is returned in B, B. This +function can also be used in the NPN callback. + +SSL_CTX_set_next_proto_select_cb() sets a callback B that is called when a +client needs to select a protocol from the server's provided list, and a +user-defined pointer argument B which will be passed to this callback. +For the callback itself, B +must be set to point to the selected protocol (which may be within B). +The length of the protocol name must be written into B. The +server's advertised protocols are provided in B and B. The +callback can assume that B is syntactically valid. The client must +select a protocol. It is fatal to the connection if this callback returns +a value other than B. The B parameter is the pointer +set via SSL_CTX_set_next_proto_select_cb(). + +SSL_CTX_set_next_protos_advertised_cb() sets a callback B 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 to point to it and B to its length. This +memory will not be modified, but the B does keep a +reference to it. The callback should return B 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 +with length B. It is not NUL-terminated. B is set to NULL and B +is set to 0 if no protocol has been selected. B must not be freed. + +SSL_get0_next_proto_negotiated() sets B and B 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 is set to NULL and +B 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 +non-empty, 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, B. + +=item OPENSSL_NPN_NO_OVERLAP + +No match was found. The first item in B, B is returned in +B, B. + +=back + +The ALPN select callback B, 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 if successful. Any other value is fatal to the connection. + +The callback set using SSL_CTX_set_next_protos_advertised_cb() should return +B if it wishes to advertise. Otherwise, no such extension +will be included in the ServerHello. + +=head1 SEE ALSO + +L, L, +L + +=head1 COPYRIGHT + +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 +in the file LICENSE in the source distribution or at +L. + +=cut -- cgit v1.2.3