| SSL_CTX_set_cert_cb.3 (340704) | SSL_CTX_set_cert_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_cert_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_cert_cb 3" |
| 132.TH SSL_CTX_set_cert_cb 3 "2018-11-20" "1.0.2q" "OpenSSL" | 136.TH SSL_CTX_set_cert_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_cert_cb, SSL_set_cert_cb \- handle certificate callback function 139.SH "SYNOPSIS" 140.IX Header "SYNOPSIS" 141.Vb 1 142\& #include <openssl/ssl.h> 143\& 144\& void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 145\& void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 146\& 147\& int (*cert_cb)(SSL *ssl, void *arg); 148.Ve 149.SH "DESCRIPTION" 150.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_cert_cb, SSL_set_cert_cb \- handle certificate callback function 143.SH "SYNOPSIS" 144.IX Header "SYNOPSIS" 145.Vb 1 146\& #include <openssl/ssl.h> 147\& 148\& void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 149\& void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); 150\& 151\& int (*cert_cb)(SSL *ssl, void *arg); 152.Ve 153.SH "DESCRIPTION" 154.IX Header "DESCRIPTION" |
| 151\&\fISSL_CTX_set_cert_cb()\fR and \fISSL_set_cert_cb()\fR sets the \fB\f(BIcert_cb()\fB\fR callback, | 155\&\fBSSL_CTX_set_cert_cb()\fR and \fBSSL_set_cert_cb()\fR sets the \fB\fBcert_cb()\fB\fR callback, |
| 152\&\fBarg\fR value is pointer which is passed to the application callback. 153.PP | 156\&\fBarg\fR value is pointer which is passed to the application callback. 157.PP |
| 154When \fB\f(BIcert_cb()\fB\fR is \s-1NULL,\s0 no callback function is used. | 158When \fB\fBcert_cb()\fB\fR is \s-1NULL,\s0 no callback function is used. |
| 155.PP | 159.PP |
| 156\&\fIcert_cb()\fR is the application defined callback. It is called before a | 160\&\fBcert_cb()\fR is the application defined callback. It is called before a |
| 157certificate will be used by a client or server. The callback can then inspect 158the passed \fBssl\fR structure and set or clear any appropriate certificates. If 159the callback is successful it \fB\s-1MUST\s0\fR return 1 even if no certificates have 160been set. A zero is returned on error which will abort the handshake with a 161fatal internal error alert. A negative return value will suspend the handshake 162and the handshake function will return immediately. | 161certificate will be used by a client or server. The callback can then inspect 162the passed \fBssl\fR structure and set or clear any appropriate certificates. If 163the callback is successful it \fB\s-1MUST\s0\fR return 1 even if no certificates have 164been set. A zero is returned on error which will abort the handshake with a 165fatal internal error alert. A negative return value will suspend the handshake 166and the handshake function will return immediately. |
| 163\&\fISSL_get_error\fR\|(3) will return \s-1SSL_ERROR_WANT_X509_LOOKUP\s0 to | 167\&\fBSSL_get_error\fR\|(3) will return \s-1SSL_ERROR_WANT_X509_LOOKUP\s0 to |
| 164indicate, that the handshake was suspended. The next call to the handshake | 168indicate, that the handshake was suspended. The next call to the handshake |
| 165function will again lead to the call of \fIcert_cb()\fR. It is the job of the 166\&\fIcert_cb()\fR to store information about the state of the last call, | 169function will again lead to the call of \fBcert_cb()\fR. It is the job of the 170\&\fBcert_cb()\fR to store information about the state of the last call, |
| 167if required to continue. 168.SH "NOTES" 169.IX Header "NOTES" | 171if required to continue. 172.SH "NOTES" 173.IX Header "NOTES" |
| 170An application will typically call \fISSL_use_certificate()\fR and 171\&\fISSL_use_PrivateKey()\fR to set the end entity certificate and private key. | 174An application will typically call \fBSSL_use_certificate()\fR and 175\&\fBSSL_use_PrivateKey()\fR to set the end entity certificate and private key. |
| 172It can add intermediate and optionally the root \s-1CA\s0 certificates using | 176It can add intermediate and optionally the root \s-1CA\s0 certificates using |
| 173\&\fISSL_add1_chain_cert()\fR. | 177\&\fBSSL_add1_chain_cert()\fR. |
| 174.PP | 178.PP |
| 175It might also call \fISSL_certs_clear()\fR to delete any certificates associated | 179It might also call \fBSSL_certs_clear()\fR to delete any certificates associated |
| 176with the \fB\s-1SSL\s0\fR object. 177.PP 178The certificate callback functionality supercedes the (largely broken) 179functionality provided by the old client certificate callback interface. 180It is \fBalways\fR called even is a certificate is already set so the callback 181can modify or delete the existing certificate. 182.PP 183A more advanced callback might examine the handshake parameters and set 184whatever chain is appropriate. For example a legacy client supporting only 185\&\s-1TLS\s0 v1.0 might receive a certificate chain signed using \s-1SHA1\s0 whereas a 186\&\s-1TLS\s0 v1.2 client which advertises support for \s-1SHA256\s0 could receive a chain 187using \s-1SHA256.\s0 188.PP 189Normal server sanity checks are performed on any certificates set 190by the callback. So if an \s-1EC\s0 chain is set for a curve the client does not 191support it will \fBnot\fR be used. 192.SH "SEE ALSO" 193.IX Header "SEE ALSO" | 180with the \fB\s-1SSL\s0\fR object. 181.PP 182The certificate callback functionality supercedes the (largely broken) 183functionality provided by the old client certificate callback interface. 184It is \fBalways\fR called even is a certificate is already set so the callback 185can modify or delete the existing certificate. 186.PP 187A more advanced callback might examine the handshake parameters and set 188whatever chain is appropriate. For example a legacy client supporting only 189\&\s-1TLS\s0 v1.0 might receive a certificate chain signed using \s-1SHA1\s0 whereas a 190\&\s-1TLS\s0 v1.2 client which advertises support for \s-1SHA256\s0 could receive a chain 191using \s-1SHA256.\s0 192.PP 193Normal server sanity checks are performed on any certificates set 194by the callback. So if an \s-1EC\s0 chain is set for a curve the client does not 195support it will \fBnot\fR be used. 196.SH "SEE ALSO" 197.IX Header "SEE ALSO" |
| 194\&\fIssl\fR\|(3), \fISSL_use_certificate\fR\|(3), 195\&\fISSL_add1_chain_cert\fR\|(3), 196\&\fISSL_get_client_CA_list\fR\|(3), 197\&\fISSL_clear\fR\|(3), \fISSL_free\fR\|(3) | 198\&\fBssl\fR\|(3), \fBSSL_use_certificate\fR\|(3), 199\&\fBSSL_add1_chain_cert\fR\|(3), 200\&\fBSSL_get_client_CA_list\fR\|(3), 201\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3) |