diff options
Diffstat (limited to 'src/lib/libssl/doc/SSL_CTX_load_verify_locations.3')
| -rw-r--r-- | src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 | 161 |
1 files changed, 0 insertions, 161 deletions
diff --git a/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 b/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 deleted file mode 100644 index 09884db5da..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 +++ /dev/null | |||
| @@ -1,161 +0,0 @@ | |||
| 1 | .\" | ||
| 2 | .\" $OpenBSD: SSL_CTX_load_verify_locations.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ | ||
| 3 | .\" | ||
| 4 | .Dd $Mdocdate: December 2 2014 $ | ||
| 5 | .Dt SSL_CTX_LOAD_VERIFY_LOCATIONS 3 | ||
| 6 | .Os | ||
| 7 | .Sh NAME | ||
| 8 | .Nm SSL_CTX_load_verify_locations | ||
| 9 | .Nd set default locations for trusted CA certificates | ||
| 10 | .Sh SYNOPSIS | ||
| 11 | .In openssl/ssl.h | ||
| 12 | .Ft int | ||
| 13 | .Fo SSL_CTX_load_verify_locations | ||
| 14 | .Fa "SSL_CTX *ctx" "const char *CAfile" "const char *CApath" | ||
| 15 | .Fc | ||
| 16 | .Sh DESCRIPTION | ||
| 17 | .Fn SSL_CTX_load_verify_locations | ||
| 18 | specifies the locations for | ||
| 19 | .Fa ctx , | ||
| 20 | at which CA certificates for verification purposes are located. | ||
| 21 | The certificates available via | ||
| 22 | .Fa CAfile | ||
| 23 | and | ||
| 24 | .Fa CApath | ||
| 25 | are trusted. | ||
| 26 | .Sh NOTES | ||
| 27 | If | ||
| 28 | .Fa CAfile | ||
| 29 | is not | ||
| 30 | .Dv NULL , | ||
| 31 | it points to a file of CA certificates in PEM format. | ||
| 32 | The file can contain several CA certificates identified by sequences of: | ||
| 33 | .Bd -literal | ||
| 34 | -----BEGIN CERTIFICATE----- | ||
| 35 | ... (CA certificate in base64 encoding) ... | ||
| 36 | -----END CERTIFICATE----- | ||
| 37 | .Ed | ||
| 38 | Before, between, and after the certificates arbitrary text is allowed which can | ||
| 39 | be used, e.g., for descriptions of the certificates. | ||
| 40 | .Pp | ||
| 41 | The | ||
| 42 | .Fa CAfile | ||
| 43 | is processed on execution of the | ||
| 44 | .Fn SSL_CTX_load_verify_locations | ||
| 45 | function. | ||
| 46 | .Pp | ||
| 47 | If | ||
| 48 | .Fa CApath | ||
| 49 | is not NULL, it points to a directory containing CA certificates in PEM format. | ||
| 50 | The files each contain one CA certificate. | ||
| 51 | The files are looked up by the CA subject name hash value, | ||
| 52 | which must hence be available. | ||
| 53 | If more than one CA certificate with the same name hash value exist, | ||
| 54 | the extension must be different (e.g., | ||
| 55 | .Pa 9d66eef0.0 , | ||
| 56 | .Pa 9d66eef0.1 , | ||
| 57 | etc.). | ||
| 58 | The search is performed in the ordering of the extension number, | ||
| 59 | regardless of other properties of the certificates. | ||
| 60 | .Pp | ||
| 61 | The certificates in | ||
| 62 | .Fa CApath | ||
| 63 | are only looked up when required, e.g., when building the certificate chain or | ||
| 64 | when actually performing the verification of a peer certificate. | ||
| 65 | .Pp | ||
| 66 | When looking up CA certificates, the OpenSSL library will first search the | ||
| 67 | certificates in | ||
| 68 | .Fa CAfile , | ||
| 69 | then those in | ||
| 70 | .Fa CApath . | ||
| 71 | Certificate matching is done based on the subject name, the key identifier (if | ||
| 72 | present), and the serial number as taken from the certificate to be verified. | ||
| 73 | If these data do not match, the next certificate will be tried. | ||
| 74 | If a first certificate matching the parameters is found, | ||
| 75 | the verification process will be performed; | ||
| 76 | no other certificates for the same parameters will be searched in case of | ||
| 77 | failure. | ||
| 78 | .Pp | ||
| 79 | In server mode, when requesting a client certificate, the server must send | ||
| 80 | the list of CAs of which it will accept client certificates. | ||
| 81 | This list is not influenced by the contents of | ||
| 82 | .Fa CAfile | ||
| 83 | or | ||
| 84 | .Fa CApath | ||
| 85 | and must explicitly be set using the | ||
| 86 | .Xr SSL_CTX_set_client_CA_list 3 | ||
| 87 | family of functions. | ||
| 88 | .Pp | ||
| 89 | When building its own certificate chain, an OpenSSL client/server will try to | ||
| 90 | fill in missing certificates from | ||
| 91 | .Fa CAfile Ns / Fa CApath , | ||
| 92 | if the | ||
| 93 | certificate chain was not explicitly specified (see | ||
| 94 | .Xr SSL_CTX_add_extra_chain_cert 3 | ||
| 95 | and | ||
| 96 | .Xr SSL_CTX_use_certificate 3 ) . | ||
| 97 | .Sh WARNINGS | ||
| 98 | If several CA certificates matching the name, key identifier, and serial | ||
| 99 | number condition are available, only the first one will be examined. | ||
| 100 | This may lead to unexpected results if the same CA certificate is available | ||
| 101 | with different expiration dates. | ||
| 102 | If a | ||
| 103 | .Dq certificate expired | ||
| 104 | verification error occurs, no other certificate will be searched. | ||
| 105 | Make sure to not have expired certificates mixed with valid ones. | ||
| 106 | .Sh RETURN VALUES | ||
| 107 | The following return values can occur: | ||
| 108 | .Bl -tag -width Ds | ||
| 109 | .It 0 | ||
| 110 | The operation failed because | ||
| 111 | .Fa CAfile | ||
| 112 | and | ||
| 113 | .Fa CApath | ||
| 114 | are | ||
| 115 | .Dv NULL | ||
| 116 | or the processing at one of the locations specified failed. | ||
| 117 | Check the error stack to find out the reason. | ||
| 118 | .It 1 | ||
| 119 | The operation succeeded. | ||
| 120 | .El | ||
| 121 | .Sh EXAMPLES | ||
| 122 | Generate a CA certificate file with descriptive text from the CA certificates | ||
| 123 | .Pa ca1.pem | ||
| 124 | .Pa ca2.pem | ||
| 125 | .Pa ca3.pem : | ||
| 126 | .Bd -literal | ||
| 127 | #!/bin/sh | ||
| 128 | rm CAfile.pem | ||
| 129 | for i in ca1.pem ca2.pem ca3.pem; do | ||
| 130 | openssl x509 -in $i -text >> CAfile.pem | ||
| 131 | done | ||
| 132 | .Ed | ||
| 133 | .Pp | ||
| 134 | Prepare the directory /some/where/certs containing several CA certificates | ||
| 135 | for use as | ||
| 136 | .Fa CApath : | ||
| 137 | .Bd -literal | ||
| 138 | $ cd /some/where/certs | ||
| 139 | $ rm -f *.[0-9]* *.r[0-9]* | ||
| 140 | $ for c in *.pem; do | ||
| 141 | > [ "$c" = "*.pem" ] && continue | ||
| 142 | > hash=$(openssl x509 -noout -hash -in "$c") | ||
| 143 | > if egrep -q -- '-BEGIN( X509 | TRUSTED | )CERTIFICATE-' "$c"; then | ||
| 144 | > suf=0 | ||
| 145 | > while [ -e $hash.$suf ]; do suf=$(( $suf + 1 )); done | ||
| 146 | > ln -s "$c" $hash.$suf | ||
| 147 | > fi | ||
| 148 | > if egrep -q -- '-BEGIN X509 CRL-' "$c"; then | ||
| 149 | > suf=0 | ||
| 150 | > while [ -e $hash.r$suf ]; do suf=$(( $suf + 1 )); done | ||
| 151 | > ln -s "$c" $hash.r$suf | ||
| 152 | > fi | ||
| 153 | > done | ||
| 154 | .Ed | ||
| 155 | .Sh SEE ALSO | ||
| 156 | .Xr ssl 3 , | ||
| 157 | .Xr SSL_CTX_add_extra_chain_cert 3 , | ||
| 158 | .Xr SSL_CTX_set_cert_store 3 , | ||
| 159 | .Xr SSL_CTX_set_client_CA_list 3 , | ||
| 160 | .Xr SSL_CTX_use_certificate 3 , | ||
| 161 | .Xr SSL_get_client_CA_list 3 | ||
