SSL_CTX_set_verify.pod 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355
  1. =pod
  2. =head1 NAME
  3. SSL_get_ex_data_X509_STORE_CTX_idx,
  4. SSL_CTX_set_verify, SSL_set_verify,
  5. SSL_CTX_set_verify_depth, SSL_set_verify_depth,
  6. SSL_verify_cb,
  7. SSL_verify_client_post_handshake,
  8. SSL_force_post_handshake_auth
  9. - set peer certificate verification parameters
  10. =head1 SYNOPSIS
  11. #include <openssl/ssl.h>
  12. typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx);
  13. void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback);
  14. void SSL_set_verify(SSL *ssl, int mode, SSL_verify_cb verify_callback);
  15. SSL_get_ex_data_X509_STORE_CTX_idx(void);
  16. void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth);
  17. void SSL_set_verify_depth(SSL *ssl, int depth);
  18. int SSL_verify_client_post_handshake(SSL *ssl);
  19. void SSL_force_post_handshake_auth(SSL *ssl);
  20. =head1 DESCRIPTION
  21. SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
  22. specifies the B<verify_callback> function to be used. If no callback function
  23. shall be specified, the NULL pointer can be used for B<verify_callback>.
  24. SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
  25. specifies the B<verify_callback> function to be used. If no callback function
  26. shall be specified, the NULL pointer can be used for B<verify_callback>. In
  27. this case last B<verify_callback> set specifically for this B<ssl> remains. If
  28. no special B<callback> was set before, the default callback for the underlying
  29. B<ctx> is used, that was valid at the time B<ssl> was created with
  30. L<SSL_new(3)>. Within the callback function,
  31. B<SSL_get_ex_data_X509_STORE_CTX_idx> can be called to get the data index
  32. of the current SSL object that is doing the verification.
  33. SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
  34. verification that shall be allowed for B<ctx>.
  35. SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
  36. verification that shall be allowed for B<ssl>.
  37. SSL_force_post_handshake_auth() forces the Post-Handshake Authentication
  38. extension to be added to the ClientHello regardless of certificate configuration
  39. at the time of the initial handshake, such that post-handshake authentication
  40. can be requested by the server. A certificate callback will need to be set via
  41. SSL_CTX_set_client_cert_cb() if no certificate is provided at initialization.
  42. SSL_verify_client_post_handshake() causes a CertificateRequest message to be
  43. sent by a server on the given B<ssl> connection. The SSL_VERIFY_PEER flag must
  44. be set; the SSL_VERIFY_POST_HANDSHAKE flag is optional.
  45. =head1 NOTES
  46. The verification of certificates can be controlled by a set of logically
  47. or'ed B<mode> flags:
  48. =over 4
  49. =item SSL_VERIFY_NONE
  50. B<Server mode:> the server will not send a client certificate request to the
  51. client, so the client will not send a certificate.
  52. B<Client mode:> if not using an anonymous cipher (by default disabled), the
  53. server will send a certificate which will be checked. The result of the
  54. certificate verification process can be checked after the TLS/SSL handshake
  55. using the L<SSL_get_verify_result(3)> function.
  56. The handshake will be continued regardless of the verification result.
  57. =item SSL_VERIFY_PEER
  58. B<Server mode:> the server sends a client certificate request to the client.
  59. The certificate returned (if any) is checked. If the verification process
  60. fails, the TLS/SSL handshake is
  61. immediately terminated with an alert message containing the reason for
  62. the verification failure.
  63. The behaviour can be controlled by the additional
  64. SSL_VERIFY_FAIL_IF_NO_PEER_CERT, SSL_VERIFY_CLIENT_ONCE and
  65. SSL_VERIFY_POST_HANDSHAKE flags.
  66. B<Client mode:> the server certificate is verified. If the verification process
  67. fails, the TLS/SSL handshake is
  68. immediately terminated with an alert message containing the reason for
  69. the verification failure. If no server certificate is sent, because an
  70. anonymous cipher is used, SSL_VERIFY_PEER is ignored.
  71. =item SSL_VERIFY_FAIL_IF_NO_PEER_CERT
  72. B<Server mode:> if the client did not return a certificate, the TLS/SSL
  73. handshake is immediately terminated with a "handshake failure" alert.
  74. This flag must be used together with SSL_VERIFY_PEER.
  75. B<Client mode:> ignored
  76. =item SSL_VERIFY_CLIENT_ONCE
  77. B<Server mode:> only request a client certificate once during the
  78. connection. Do not ask for a client certificate again during
  79. renegotiation or post-authentication if a certificate was requested
  80. during the initial handshake. This flag must be used together with
  81. SSL_VERIFY_PEER.
  82. B<Client mode:> ignored
  83. =item SSL_VERIFY_POST_HANDSHAKE
  84. B<Server mode:> the server will not send a client certificate request
  85. during the initial handshake, but will send the request via
  86. SSL_verify_client_post_handshake(). This allows the SSL_CTX or SSL
  87. to be configured for post-handshake peer verification before the
  88. handshake occurs. This flag must be used together with
  89. SSL_VERIFY_PEER. TLSv1.3 only; no effect on pre-TLSv1.3 connections.
  90. B<Client mode:> ignored
  91. =back
  92. If the B<mode> is SSL_VERIFY_NONE none of the other flags may be set.
  93. The actual verification procedure is performed either using the built-in
  94. verification procedure or using another application provided verification
  95. function set with
  96. L<SSL_CTX_set_cert_verify_callback(3)>.
  97. The following descriptions apply in the case of the built-in procedure. An
  98. application provided procedure also has access to the verify depth information
  99. and the verify_callback() function, but the way this information is used
  100. may be different.
  101. SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set a limit on the
  102. number of certificates between the end-entity and trust-anchor certificates.
  103. Neither the
  104. end-entity nor the trust-anchor certificates count against B<depth>. If the
  105. certificate chain needed to reach a trusted issuer is longer than B<depth+2>,
  106. X509_V_ERR_CERT_CHAIN_TOO_LONG will be issued.
  107. The depth count is "level 0:peer certificate", "level 1: CA certificate",
  108. "level 2: higher level CA certificate", and so on. Setting the maximum
  109. depth to 2 allows the levels 0, 1, 2 and 3 (0 being the end-entity and 3 the
  110. trust-anchor).
  111. The default depth limit is 100,
  112. allowing for the peer certificate, at most 100 intermediate CA certificates and
  113. a final trust anchor certificate.
  114. The B<verify_callback> function is used to control the behaviour when the
  115. SSL_VERIFY_PEER flag is set. It must be supplied by the application and
  116. receives two arguments: B<preverify_ok> indicates, whether the verification of
  117. the certificate in question was passed (preverify_ok=1) or not
  118. (preverify_ok=0). B<x509_ctx> is a pointer to the complete context used
  119. for the certificate chain verification.
  120. The certificate chain is checked starting with the deepest nesting level
  121. (the root CA certificate) and worked upward to the peer's certificate.
  122. At each level signatures and issuer attributes are checked. Whenever
  123. a verification error is found, the error number is stored in B<x509_ctx>
  124. and B<verify_callback> is called with B<preverify_ok>=0. By applying
  125. X509_CTX_store_* functions B<verify_callback> can locate the certificate
  126. in question and perform additional steps (see EXAMPLES). If no error is
  127. found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
  128. before advancing to the next level.
  129. The return value of B<verify_callback> controls the strategy of the further
  130. verification process. If B<verify_callback> returns 0, the verification
  131. process is immediately stopped with "verification failed" state. If
  132. SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
  133. the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
  134. the verification process is continued. If B<verify_callback> always returns
  135. 1, the TLS/SSL handshake will not be terminated with respect to verification
  136. failures and the connection will be established. The calling process can
  137. however retrieve the error code of the last verification error using
  138. L<SSL_get_verify_result(3)> or by maintaining its
  139. own error storage managed by B<verify_callback>.
  140. If no B<verify_callback> is specified, the default callback will be used.
  141. Its return value is identical to B<preverify_ok>, so that any verification
  142. failure will lead to a termination of the TLS/SSL handshake with an
  143. alert message, if SSL_VERIFY_PEER is set.
  144. After calling SSL_force_post_handshake_auth(), the client will need to add a
  145. certificate or certificate callback to its configuration before it can
  146. successfully authenticate. This must be called before SSL_connect().
  147. SSL_verify_client_post_handshake() requires that verify flags have been
  148. previously set, and that a client sent the post-handshake authentication
  149. extension. When the client returns a certificate the verify callback will be
  150. invoked. A write operation must take place for the Certificate Request to be
  151. sent to the client, this can be done with SSL_do_handshake() or SSL_write_ex().
  152. Only one certificate request may be outstanding at any time.
  153. When post-handshake authentication occurs, a refreshed NewSessionTicket
  154. message is sent to the client.
  155. =head1 BUGS
  156. In client mode, it is not checked whether the SSL_VERIFY_PEER flag
  157. is set, but whether any flags are set. This can lead to
  158. unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as
  159. required.
  160. =head1 RETURN VALUES
  161. The SSL*_set_verify*() functions do not provide diagnostic information.
  162. The SSL_verify_client_post_handshake() function returns 1 if the request
  163. succeeded, and 0 if the request failed. The error stack can be examined
  164. to determine the failure reason.
  165. =head1 EXAMPLES
  166. The following code sequence realizes an example B<verify_callback> function
  167. that will always continue the TLS/SSL handshake regardless of verification
  168. failure, if wished. The callback realizes a verification depth limit with
  169. more informational output.
  170. All verification errors are printed; information about the certificate chain
  171. is printed on request.
  172. The example is realized for a server that does allow but not require client
  173. certificates.
  174. The example makes use of the ex_data technique to store application data
  175. into/retrieve application data from the SSL structure
  176. (see L<CRYPTO_get_ex_new_index(3)>,
  177. L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
  178. ...
  179. typedef struct {
  180. int verbose_mode;
  181. int verify_depth;
  182. int always_continue;
  183. } mydata_t;
  184. int mydata_index;
  185. ...
  186. static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
  187. {
  188. char buf[256];
  189. X509 *err_cert;
  190. int err, depth;
  191. SSL *ssl;
  192. mydata_t *mydata;
  193. err_cert = X509_STORE_CTX_get_current_cert(ctx);
  194. err = X509_STORE_CTX_get_error(ctx);
  195. depth = X509_STORE_CTX_get_error_depth(ctx);
  196. /*
  197. * Retrieve the pointer to the SSL of the connection currently treated
  198. * and the application specific data stored into the SSL object.
  199. */
  200. ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
  201. mydata = SSL_get_ex_data(ssl, mydata_index);
  202. X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
  203. /*
  204. * Catch a too long certificate chain. The depth limit set using
  205. * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
  206. * that whenever the "depth>verify_depth" condition is met, we
  207. * have violated the limit and want to log this error condition.
  208. * We must do it here, because the CHAIN_TOO_LONG error would not
  209. * be found explicitly; only errors introduced by cutting off the
  210. * additional certificates would be logged.
  211. */
  212. if (depth > mydata->verify_depth) {
  213. preverify_ok = 0;
  214. err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
  215. X509_STORE_CTX_set_error(ctx, err);
  216. }
  217. if (!preverify_ok) {
  218. printf("verify error:num=%d:%s:depth=%d:%s\n", err,
  219. X509_verify_cert_error_string(err), depth, buf);
  220. } else if (mydata->verbose_mode) {
  221. printf("depth=%d:%s\n", depth, buf);
  222. }
  223. /*
  224. * At this point, err contains the last verification error. We can use
  225. * it for something special
  226. */
  227. if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) {
  228. X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256);
  229. printf("issuer= %s\n", buf);
  230. }
  231. if (mydata->always_continue)
  232. return 1;
  233. else
  234. return preverify_ok;
  235. }
  236. ...
  237. mydata_t mydata;
  238. ...
  239. mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
  240. ...
  241. SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | SSL_VERIFY_CLIENT_ONCE,
  242. verify_callback);
  243. /*
  244. * Let the verify_callback catch the verify_depth error so that we get
  245. * an appropriate error in the logfile.
  246. */
  247. SSL_CTX_set_verify_depth(verify_depth + 1);
  248. /*
  249. * Set up the SSL specific data into "mydata" and store it into th SSL
  250. * structure.
  251. */
  252. mydata.verify_depth = verify_depth; ...
  253. SSL_set_ex_data(ssl, mydata_index, &mydata);
  254. ...
  255. SSL_accept(ssl); /* check of success left out for clarity */
  256. if (peer = SSL_get_peer_certificate(ssl)) {
  257. if (SSL_get_verify_result(ssl) == X509_V_OK) {
  258. /* The client sent a certificate which verified OK */
  259. }
  260. }
  261. =head1 SEE ALSO
  262. L<ssl(7)>, L<SSL_new(3)>,
  263. L<SSL_CTX_get_verify_mode(3)>,
  264. L<SSL_get_verify_result(3)>,
  265. L<SSL_CTX_load_verify_locations(3)>,
  266. L<SSL_get_peer_certificate(3)>,
  267. L<SSL_CTX_set_cert_verify_callback(3)>,
  268. L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
  269. L<SSL_CTX_set_client_cert_cb(3)>,
  270. L<CRYPTO_get_ex_new_index(3)>
  271. =head1 HISTORY
  272. The SSL_VERIFY_POST_HANDSHAKE option, and the SSL_verify_client_post_handshake()
  273. and SSL_force_post_handshake_auth() functions were added in OpenSSL 1.1.1.
  274. =head1 COPYRIGHT
  275. Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
  276. Licensed under the OpenSSL license (the "License"). You may not use
  277. this file except in compliance with the License. You can obtain a copy
  278. in the file LICENSE in the source distribution or at
  279. L<https://www.openssl.org/source/license.html>.
  280. =cut