| SSL_CTX_set_alpn_select_cb.3 (340704) | SSL_CTX_set_alpn_select_cb.3 (344604) |
|---|---|
| 1.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) | 1.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) |
| 2.\" 3.\" Standard preamble: 4.\" ======================================================================== 5.de Sp \" Vertical space (when we can't use .PP) 6.if t .sp .5v 7.if n .sp 8.. 9.de Vb \" Begin verbatim text --- 39 unchanged lines hidden (view full) --- 49.\" If the F register is >0, we'll generate index entries on stderr for 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 51.\" entries marked with X<> in POD. Of course, you'll have to process the 52.\" output yourself in some meaningful fashion. 53.\" 54.\" Avoid warning from groff about undefined register 'F'. 55.de IX 56.. | 2.\" 3.\" Standard preamble: 4.\" ======================================================================== 5.de Sp \" Vertical space (when we can't use .PP) 6.if t .sp .5v 7.if n .sp 8.. 9.de Vb \" Begin verbatim text --- 39 unchanged lines hidden (view full) --- 49.\" If the F register is >0, we'll generate index entries on stderr for 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 51.\" entries marked with X<> in POD. Of course, you'll have to process the 52.\" output yourself in some meaningful fashion. 53.\" 54.\" Avoid warning from groff about undefined register 'F'. 55.de IX 56.. |
| 57.if !\nF .nr F 0 58.if \nF>0 \{\ 59. de IX 60. tm Index:\\$1\t\\n%\t"\\$2" | 57.nr rF 0 58.if \n(.g .if rF .nr rF 1 59.if (\n(rF:(\n(.g==0)) \{\ 60. if \nF \{\ 61. de IX 62. tm Index:\\$1\t\\n%\t"\\$2" |
| 61.. | 63.. |
| 62. if !\nF==2 \{\ 63. nr % 0 64. nr F 2 | 64. if !\nF==2 \{\ 65. nr % 0 66. nr F 2 67. \} |
| 65. \} 66.\} | 68. \} 69.\} |
| 70.rr rF |
|
| 67.\" 68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 69.\" Fear. Run. Save yourself. No user-serviceable parts. 70. \" fudge factors for nroff and troff 71.if n \{\ 72. ds #H 0 73. ds #V .8m 74. ds #F .3m --- 49 unchanged lines hidden (view full) --- 124. ds Th \o'LP' 125. ds ae ae 126. ds Ae AE 127.\} 128.rm #[ #] #H #V #F C 129.\" ======================================================================== 130.\" 131.IX Title "SSL_CTX_set_alpn_select_cb 3" | 71.\" 72.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 73.\" Fear. Run. Save yourself. No user-serviceable parts. 74. \" fudge factors for nroff and troff 75.if n \{\ 76. ds #H 0 77. ds #V .8m 78. ds #F .3m --- 49 unchanged lines hidden (view full) --- 128. ds Th \o'LP' 129. ds ae ae 130. ds Ae AE 131.\} 132.rm #[ #] #H #V #F C 133.\" ======================================================================== 134.\" 135.IX Title "SSL_CTX_set_alpn_select_cb 3" |
| 132.TH SSL_CTX_set_alpn_select_cb 3 "2018-11-20" "1.0.2q" "OpenSSL" | 136.TH SSL_CTX_set_alpn_select_cb 3 "2019-02-26" "1.0.2r" "OpenSSL" |
| 133.\" For nroff, turn off justification. Always turn off hyphenation; it makes 134.\" way too many mistakes in technical documents. 135.if n .ad l 136.nh 137.SH "NAME" 138SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, 139SSL_select_next_proto, SSL_get0_alpn_selected \- handle application layer 140protocol negotiation (ALPN) --- 18 unchanged lines hidden (view full) --- 159\& unsigned int server_len, 160\& const unsigned char *client, 161\& unsigned int client_len) 162\& void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, 163\& unsigned int *len); 164.Ve 165.SH "DESCRIPTION" 166.IX Header "DESCRIPTION" | 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes 138.\" way too many mistakes in technical documents. 139.if n .ad l 140.nh 141.SH "NAME" 142SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, 143SSL_select_next_proto, SSL_get0_alpn_selected \- handle application layer 144protocol negotiation (ALPN) --- 18 unchanged lines hidden (view full) --- 163\& unsigned int server_len, 164\& const unsigned char *client, 165\& unsigned int client_len) 166\& void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, 167\& unsigned int *len); 168.Ve 169.SH "DESCRIPTION" 170.IX Header "DESCRIPTION" |
| 167\&\fISSL_CTX_set_alpn_protos()\fR and \fISSL_set_alpn_protos()\fR are used by the client to | 171\&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR are used by the client to |
| 168set the list of protocols available to be negotiated. The \fBprotos\fR must be in 169protocol-list format, described below. The length of \fBprotos\fR is specified in 170\&\fBprotos_len\fR. 171.PP | 172set the list of protocols available to be negotiated. The \fBprotos\fR must be in 173protocol-list format, described below. The length of \fBprotos\fR is specified in 174\&\fBprotos_len\fR. 175.PP |
| 172\&\fISSL_CTX_set_alpn_select_cb()\fR sets the application callback \fBcb\fR used by a | 176\&\fBSSL_CTX_set_alpn_select_cb()\fR sets the application callback \fBcb\fR used by a |
| 173server to select which protocol to use for the incoming connection. When \fBcb\fR 174is \s-1NULL, ALPN\s0 is not used. The \fBarg\fR value is a pointer which is passed to 175the application callback. 176.PP 177\&\fBcb\fR is the application defined callback. The \fBin\fR, \fBinlen\fR parameters are a 178vector in protocol-list format. The value of the \fBout\fR, \fBoutlen\fR vector 179should be set to the value of a single protocol selected from the \fBin\fR, 180\&\fBinlen\fR vector. The \fBarg\fR parameter is the pointer set via | 177server to select which protocol to use for the incoming connection. When \fBcb\fR 178is \s-1NULL, ALPN\s0 is not used. The \fBarg\fR value is a pointer which is passed to 179the application callback. 180.PP 181\&\fBcb\fR is the application defined callback. The \fBin\fR, \fBinlen\fR parameters are a 182vector in protocol-list format. The value of the \fBout\fR, \fBoutlen\fR vector 183should be set to the value of a single protocol selected from the \fBin\fR, 184\&\fBinlen\fR vector. The \fBarg\fR parameter is the pointer set via |
| 181\&\fISSL_CTX_set_alpn_select_cb()\fR. | 185\&\fBSSL_CTX_set_alpn_select_cb()\fR. |
| 182.PP | 186.PP |
| 183\&\fISSL_select_next_proto()\fR is a helper function used to select protocols. It | 187\&\fBSSL_select_next_proto()\fR is a helper function used to select protocols. It |
| 184implements the standard protocol selection. It is expected that this function 185is called from the application callback \fBcb\fR. The protocol data in \fBserver\fR, 186\&\fBserver_len\fR and \fBclient\fR, \fBclient_len\fR must be in the protocol-list format 187described below. The first item in the \fBserver\fR, \fBserver_len\fR list that 188matches an item in the \fBclient\fR, \fBclient_len\fR list is selected, and returned 189in \fBout\fR, \fBoutlen\fR. The \fBout\fR value will point into either \fBserver\fR or 190\&\fBclient\fR, so it should be copied immediately. If no match is found, the first 191item in \fBclient\fR, \fBclient_len\fR is returned in \fBout\fR, \fBoutlen\fR. This 192function can also be used in the \s-1NPN\s0 callback. 193.PP | 188implements the standard protocol selection. It is expected that this function 189is called from the application callback \fBcb\fR. The protocol data in \fBserver\fR, 190\&\fBserver_len\fR and \fBclient\fR, \fBclient_len\fR must be in the protocol-list format 191described below. The first item in the \fBserver\fR, \fBserver_len\fR list that 192matches an item in the \fBclient\fR, \fBclient_len\fR list is selected, and returned 193in \fBout\fR, \fBoutlen\fR. The \fBout\fR value will point into either \fBserver\fR or 194\&\fBclient\fR, so it should be copied immediately. If no match is found, the first 195item in \fBclient\fR, \fBclient_len\fR is returned in \fBout\fR, \fBoutlen\fR. This 196function can also be used in the \s-1NPN\s0 callback. 197.PP |
| 194\&\fISSL_get0_alpn_selected()\fR returns a pointer to the selected protocol in \fBdata\fR | 198\&\fBSSL_get0_alpn_selected()\fR returns a pointer to the selected protocol in \fBdata\fR |
| 195with length \fBlen\fR. It is not NUL-terminated. \fBdata\fR is set to \s-1NULL\s0 and \fBlen\fR 196is set to 0 if no protocol has been selected. \fBdata\fR must not be freed. 197.SH "NOTES" 198.IX Header "NOTES" 199The protocol-lists must be in wire-format, which is defined as a vector of 200non-empty, 8\-bit length-prefixed, byte strings. The length-prefix byte is not 201included in the length. Each string is limited to 255 bytes. A byte-string 202length of 0 is invalid. A truncated byte-string is invalid. The length of the --- 11 unchanged lines hidden (view full) --- 214.PP 215The \s-1ALPN\s0 callback is executed after the servername callback; as that servername 216callback may update the \s-1SSL_CTX,\s0 and subsequently, the \s-1ALPN\s0 callback. 217.PP 218If there is no \s-1ALPN\s0 proposed in the ClientHello, the \s-1ALPN\s0 callback is not 219invoked. 220.SH "RETURN VALUES" 221.IX Header "RETURN VALUES" | 199with length \fBlen\fR. It is not NUL-terminated. \fBdata\fR is set to \s-1NULL\s0 and \fBlen\fR 200is set to 0 if no protocol has been selected. \fBdata\fR must not be freed. 201.SH "NOTES" 202.IX Header "NOTES" 203The protocol-lists must be in wire-format, which is defined as a vector of 204non-empty, 8\-bit length-prefixed, byte strings. The length-prefix byte is not 205included in the length. Each string is limited to 255 bytes. A byte-string 206length of 0 is invalid. A truncated byte-string is invalid. The length of the --- 11 unchanged lines hidden (view full) --- 218.PP 219The \s-1ALPN\s0 callback is executed after the servername callback; as that servername 220callback may update the \s-1SSL_CTX,\s0 and subsequently, the \s-1ALPN\s0 callback. 221.PP 222If there is no \s-1ALPN\s0 proposed in the ClientHello, the \s-1ALPN\s0 callback is not 223invoked. 224.SH "RETURN VALUES" 225.IX Header "RETURN VALUES" |
| 222\&\fISSL_CTX_set_alpn_protos()\fR and \fISSL_set_alpn_protos()\fR return 0 on success, and | 226\&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR return 0 on success, and |
| 223non\-0 on failure. \s-1WARNING:\s0 these functions reverse the return value convention. 224.PP | 227non\-0 on failure. \s-1WARNING:\s0 these functions reverse the return value convention. 228.PP |
| 225\&\fISSL_select_next_proto()\fR returns one of the following: | 229\&\fBSSL_select_next_proto()\fR returns one of the following: |
| 226.IP "\s-1OPENSSL_NPN_NEGOTIATED\s0" 4 227.IX Item "OPENSSL_NPN_NEGOTIATED" 228A match was found and is returned in \fBout\fR, \fBoutlen\fR. 229.IP "\s-1OPENSSL_NPN_NO_OVERLAP\s0" 4 230.IX Item "OPENSSL_NPN_NO_OVERLAP" 231No match was found. The first item in \fBclient\fR, \fBclient_len\fR is returned in 232\&\fBout\fR, \fBoutlen\fR. 233.PP 234The \s-1ALPN\s0 select callback \fBcb\fR, must return one of the following: 235.IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4 236.IX Item "SSL_TLSEXT_ERR_OK" 237\&\s-1ALPN\s0 protocol selected. 238.IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4 239.IX Item "SSL_TLSEXT_ERR_NOACK" 240\&\s-1ALPN\s0 protocol not selected. 241.SH "SEE ALSO" 242.IX Header "SEE ALSO" | 230.IP "\s-1OPENSSL_NPN_NEGOTIATED\s0" 4 231.IX Item "OPENSSL_NPN_NEGOTIATED" 232A match was found and is returned in \fBout\fR, \fBoutlen\fR. 233.IP "\s-1OPENSSL_NPN_NO_OVERLAP\s0" 4 234.IX Item "OPENSSL_NPN_NO_OVERLAP" 235No match was found. The first item in \fBclient\fR, \fBclient_len\fR is returned in 236\&\fBout\fR, \fBoutlen\fR. 237.PP 238The \s-1ALPN\s0 select callback \fBcb\fR, must return one of the following: 239.IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4 240.IX Item "SSL_TLSEXT_ERR_OK" 241\&\s-1ALPN\s0 protocol selected. 242.IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4 243.IX Item "SSL_TLSEXT_ERR_NOACK" 244\&\s-1ALPN\s0 protocol not selected. 245.SH "SEE ALSO" 246.IX Header "SEE ALSO" |
| 243\&\fIssl\fR\|(3), \fISSL_CTX_set_tlsext_servername_callback\fR\|(3), 244\&\fISSL_CTX_set_tlsext_servername_arg\fR\|(3) | 247\&\fBssl\fR\|(3), \fBSSL_CTX_set_tlsext_servername_callback\fR\|(3), 248\&\fBSSL_CTX_set_tlsext_servername_arg\fR\|(3) |