projects / thirdparty / openssl.git / blame
| Commit | Line | Data |
|---|---|---|
| 13938ace DSH |
1 | =pod |
| 2 | ||
| 3 | =head1 NAME | |
| 4 | ||
| 5 | pkcs7 - PKCS#7 utility | |
| 6 | ||
| 7 | =head1 SYNOPSIS | |
| 8 | ||
| 9 | B<openssl> B<verify> | |
| 10 | [B<-CApath directory>] | |
| 11 | [B<-CAfile file>] | |
| 12 | [B<-purpose purpose>] | |
| 13 | [B<-untrusted file>] | |
| 14 | [B<-help>] | |
| 15 | [B<-verbose>] | |
| 16 | [B<->] | |
| 17 | [certificates] | |
| 18 | ||
| 19 | ||
| 20 | =head1 DESCRIPTION | |
| 21 | ||
| 22 | The B<verify> command verifies certificate chains. | |
| 23 | ||
| 24 | =head1 COMMAND OPTIONS | |
| 25 | ||
| 26 | =over 4 | |
| 27 | ||
| 28 | =item B<-CApath directory> | |
| 29 | ||
| 30 | A directory of trusted certificates. The certificates should have names | |
| 31 | of the form: hash.0 or have symbolic links to them of this | |
| 32 | form ("hash" is the hashed certificate subject name: see the B<-hash> option | |
| 33 | of the B<x509> utility). Under Unix the B<c_rehash> script will automatically | |
| 34 | create symbolic links to a directory of certificates. | |
| 35 | ||
| 36 | =item B<-CAfile file> | |
| 37 | ||
| 38 | A file of trusted certificates. The file should contain multiple certificates | |
| 39 | in PEM format concatenated together. | |
| 40 | ||
| 41 | =item B<-untrusted file> | |
| 42 | ||
| 43 | A file of untrusted certificates. The file should contain multiple certificates | |
| 44 | ||
| 45 | =item B<-purpose purpose> | |
| 46 | ||
| 47 | the intended use for the certificate. Without this option no chain verification | |
| 48 | will be done. Currently accepted uses are B<sslclient>, B<sslserver>, | |
| 49 | B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> | |
| 50 | section for more information. | |
| 51 | ||
| 52 | =item B<-help> | |
| 53 | ||
| 54 | prints out a usage message. | |
| 55 | ||
| 56 | =item B<-verbose> | |
| 57 | ||
| 58 | print extra information about the operations being performed. | |
| 59 | ||
| 60 | =item B<-> | |
| 61 | ||
| 62 | marks the last option. All arguments following this are assumed to be | |
| 63 | certificate files. | |
| 64 | ||
| 65 | ||
| 66 | =item B<certificates> | |
| 67 | ||
| 68 | one or more certificates to verify. If no certificate filenames are included | |
| 69 | then an attempt is made to read a certificate from standard input. They should | |
| 70 | all be in PEM format. | |
| 71 | ||
| 72 | ||
| 73 | =back | |
| 74 | ||
| 75 | =head1 VERIFY OPERATION | |
| 76 | ||
| 77 | The B<verify> program uses the same functions as the internal SSL and S/MIME | |
| 78 | verification, therefore this description applies to these verify operations | |
| 79 | too. | |
| 80 | ||
| 81 | There is one crucial difference between the verify operations performed | |
| 82 | by the B<verify> program: wherever possible an attempt is made to continue | |
| 83 | after an error whereas normally the verify operation would halt on the | |
| 84 | first error. This allows all the problems with a certificate chain to be | |
| 85 | determined. | |
| 86 | ||
| 87 | The verify operation consists of a number of separate steps. | |
| 88 | ||
| 89 | Firstly a certificate chain is built up starting from the supplied certificate | |
| 90 | and ending in the root CA. It is an error if the whole chain cannot be built | |
| 91 | up. The chain is built up by looking up a certificate whose subject name | |
| 92 | matches the issuer name of the current certificate. If a certificate is found | |
| 93 | whose subject and issuer names are identical it is assumed to be the root CA. | |
| 94 | The lookup first looks in the list of untrusted certificates and if no match | |
| 95 | is found the remaining lookups are from the trusted certficates. The root CA | |
| 96 | is always looked up in the trusted certificate list: if the certificate to | |
| 97 | verify is a root certificate then an exact match must be found in the trusted | |
| 98 | list. | |
| 99 | ||
| 100 | The second operation is to check every untrusted certificate's extensions for | |
| 101 | consistency with the supplied purpose. If the B<-purpose> option is not included | |
| 102 | then no checks are done. The supplied or "leaf" certificate must have extensions | |
| 103 | compatible with the supplied purpose and all other certificates must also be valid | |
| 104 | CA certificates. The precise extensions required are described in more detail in | |
| 105 | the B<CERTIFICATE EXTENSIONS> section. | |
| 106 | ||
| 107 | The third operation is to check the trust settings on the root CA. The root | |
| 108 | CA should be trusted for the supplied purpose. For compatability with previous | |
| 109 | versions of SSLeay and OpenSSL a certificate with no trust settings is considered | |
| 110 | to be valid for all purposes. | |
| 111 | ||
| 112 | The final operation is to check the validity of the certificate chain. The validity | |
| 113 | period is checked against the current system time and the notBefore and notAfter | |
| 114 | dates in the certificate. The certificate signatures are also checked at this | |
| 115 | point. | |
| 116 | ||
| 117 | If all operations complete successfully then certificate is considered valid. If | |
| 118 | any operation fails then the certificate is not valid. | |
| 119 | ||
| 120 | =head1 CERTIFICATE EXTENSIONS | |
| 121 | ||
| 122 | ...to be added... | |
| 123 | ||
| 124 | =head1 SEE ALSO | |
| 125 | ||
| 126 | x509(1) | |
| 127 | ||
| 128 | =cut |