diff options
Diffstat (limited to 'secure/lib/libcrypto/man/verify.1')
| -rw-r--r-- | secure/lib/libcrypto/man/verify.1 | 408 |
1 files changed, 408 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/verify.1 b/secure/lib/libcrypto/man/verify.1 new file mode 100644 index 0000000..cc52986 --- /dev/null +++ b/secure/lib/libcrypto/man/verify.1 @@ -0,0 +1,408 @@ +.\" Automatically generated by Pod::Man version 1.15 +.\" Thu May 9 13:15:13 2002 +.\" +.\" Standard preamble: +.\" ====================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R + +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used +.\" to do unbreakable dashes and therefore won't be available. \*(C` and +.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr +.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and +.\" index entries marked with X<> in POD. Of course, you'll have to process +.\" the output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it +.\" makes way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +.bd B 3 +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ====================================================================== +.\" +.IX Title "VERIFY 1" +.TH VERIFY 1 "perl v5.6.1" "2002-01-27" "User Contributed Perl Documentation" +.UC +.SH "NAME" +verify \- Utility to verify certificates. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBopenssl\fR \fBverify\fR +[\fB\-CApath directory\fR] +[\fB\-CAfile file\fR] +[\fB\-purpose purpose\fR] +[\fB\-untrusted file\fR] +[\fB\-help\fR] +[\fB\-issuer_checks\fR] +[\fB\-verbose\fR] +[\fB-\fR] +[certificates] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBverify\fR command verifies certificate chains. +.SH "COMMAND OPTIONS" +.IX Header "COMMAND OPTIONS" +.Ip "\fB\-CApath directory\fR" 4 +.IX Item "-CApath directory" +A directory of trusted certificates. The certificates should have names +of the form: hash.0 or have symbolic links to them of this +form (\*(L"hash\*(R" is the hashed certificate subject name: see the \fB\-hash\fR option +of the \fBx509\fR utility). Under Unix the \fBc_rehash\fR script will automatically +create symbolic links to a directory of certificates. +.Ip "\fB\-CAfile file\fR" 4 +.IX Item "-CAfile file" +A file of trusted certificates. The file should contain multiple certificates +in \s-1PEM\s0 format concatenated together. +.Ip "\fB\-untrusted file\fR" 4 +.IX Item "-untrusted file" +A file of untrusted certificates. The file should contain multiple certificates +.Ip "\fB\-purpose purpose\fR" 4 +.IX Item "-purpose purpose" +the intended use for the certificate. Without this option no chain verification +will be done. Currently accepted uses are \fBsslclient\fR, \fBsslserver\fR, +\&\fBnssslserver\fR, \fBsmimesign\fR, \fBsmimeencrypt\fR. See the \fB\s-1VERIFY\s0 \s-1OPERATION\s0\fR +section for more information. +.Ip "\fB\-help\fR" 4 +.IX Item "-help" +prints out a usage message. +.Ip "\fB\-verbose\fR" 4 +.IX Item "-verbose" +print extra information about the operations being performed. +.Ip "\fB\-issuer_checks\fR" 4 +.IX Item "-issuer_checks" +print out diagnostics relating to searches for the issuer certificate +of the current certificate. This shows why each candidate issuer +certificate was rejected. However the presence of rejection messages +does not itself imply that anything is wrong: during the normal +verify process several rejections may take place. +.Ip "\fB-\fR" 4 +.IX Item "-" +marks the last option. All arguments following this are assumed to be +certificate files. This is useful if the first certificate filename begins +with a \fB-\fR. +.Ip "\fBcertificates\fR" 4 +.IX Item "certificates" +one or more certificates to verify. If no certificate filenames are included +then an attempt is made to read a certificate from standard input. They should +all be in \s-1PEM\s0 format. +.SH "VERIFY OPERATION" +.IX Header "VERIFY OPERATION" +The \fBverify\fR program uses the same functions as the internal \s-1SSL\s0 and S/MIME +verification, therefore this description applies to these verify operations +too. +.PP +There is one crucial difference between the verify operations performed +by the \fBverify\fR program: wherever possible an attempt is made to continue +after an error whereas normally the verify operation would halt on the +first error. This allows all the problems with a certificate chain to be +determined. +.PP +The verify operation consists of a number of separate steps. +.PP +Firstly a certificate chain is built up starting from the supplied certificate +and ending in the root \s-1CA\s0. It is an error if the whole chain cannot be built +up. The chain is built up by looking up the issuers certificate of the current +certificate. If a certificate is found which is its own issuer it is assumed +to be the root \s-1CA\s0. +.PP +The process of 'looking up the issuers certificate' itself involves a number +of steps. In versions of OpenSSL before 0.9.5a the first certificate whose +subject name matched the issuer of the current certificate was assumed to be +the issuers certificate. In OpenSSL 0.9.6 and later all certificates +whose subject name matches the issuer name of the current certificate are +subject to further tests. The relevant authority key identifier components +of the current certificate (if present) must match the subject key identifier +(if present) and issuer and serial number of the candidate issuer, in addition +the keyUsage extension of the candidate issuer (if present) must permit +certificate signing. +.PP +The lookup first looks in the list of untrusted certificates and if no match +is found the remaining lookups are from the trusted certificates. The root \s-1CA\s0 +is always looked up in the trusted certificate list: if the certificate to +verify is a root certificate then an exact match must be found in the trusted +list. +.PP +The second operation is to check every untrusted certificate's extensions for +consistency with the supplied purpose. If the \fB\-purpose\fR option is not included +then no checks are done. The supplied or \*(L"leaf\*(R" certificate must have extensions +compatible with the supplied purpose and all other certificates must also be valid +\&\s-1CA\s0 certificates. The precise extensions required are described in more detail in +the \fB\s-1CERTIFICATE\s0 \s-1EXTENSIONS\s0\fR section of the \fBx509\fR utility. +.PP +The third operation is to check the trust settings on the root \s-1CA\s0. The root +\&\s-1CA\s0 should be trusted for the supplied purpose. For compatibility with previous +versions of SSLeay and OpenSSL a certificate with no trust settings is considered +to be valid for all purposes. +.PP +The final operation is to check the validity of the certificate chain. The validity +period is checked against the current system time and the notBefore and notAfter +dates in the certificate. The certificate signatures are also checked at this +point. +.PP +If all operations complete successfully then certificate is considered valid. If +any operation fails then the certificate is not valid. +.SH "DIAGNOSTICS" +.IX Header "DIAGNOSTICS" +When a verify operation fails the output messages can be somewhat cryptic. The +general form of the error message is: +.PP +.Vb 2 +\& server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) +\& error 24 at 1 depth lookup:invalid CA certificate +.Ve +The first line contains the name of the certificate being verified followed by +the subject name of the certificate. The second line contains the error number +and the depth. The depth is number of the certificate being verified when a +problem was detected starting with zero for the certificate being verified itself +then 1 for the \s-1CA\s0 that signed the certificate and so on. Finally a text version +of the error number is presented. +.PP +An exhaustive list of the error codes and messages is shown below, this also +includes the name of the error code as defined in the header file x509_vfy.h +Some of the error codes are defined but never returned: these are described +as \*(L"unused\*(R". +.Ip "\fB0 X509_V_OK: ok\fR" 4 +.IX Item "0 X509_V_OK: ok" +the operation was successful. +.Ip "\fB2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate\fR" 4 +.IX Item "2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate" +the issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. +.Ip "\fB3 X509_V_ERR_UNABLE_TO_GET_CRL unable to get certificate \s-1CRL\s0\fR" 4 +.IX Item "3 X509_V_ERR_UNABLE_TO_GET_CRL unable to get certificate CRL" +the \s-1CRL\s0 of a certificate could not be found. Unused. +.Ip "\fB4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature\fR" 4 +.IX Item "4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature" +the certificate signature could not be decrypted. This means that the actual signature value +could not be determined rather than it not matching the expected value, this is only +meaningful for \s-1RSA\s0 keys. +.Ip "\fB5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt \s-1CRL\s0's signature\fR" 4 +.IX Item "5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature" +the \s-1CRL\s0 signature could not be decrypted: this means that the actual signature value +could not be determined rather than it not matching the expected value. Unused. +.Ip "\fB6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key\fR" 4 +.IX Item "6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key" +the public key in the certificate SubjectPublicKeyInfo could not be read. +.Ip "\fB7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure\fR" 4 +.IX Item "7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure" +the signature of the certificate is invalid. +.Ip "\fB8 X509_V_ERR_CRL_SIGNATURE_FAILURE: \s-1CRL\s0 signature failure\fR" 4 +.IX Item "8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure" +the signature of the certificate is invalid. Unused. +.Ip "\fB9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid\fR" 4 +.IX Item "9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid" +the certificate is not yet valid: the notBefore date is after the current time. +.Ip "\fB10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired\fR" 4 +.IX Item "10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired" +the certificate has expired: that is the notAfter date is before the current time. +.Ip "\fB11 X509_V_ERR_CRL_NOT_YET_VALID: \s-1CRL\s0 is not yet valid\fR" 4 +.IX Item "11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid" +the \s-1CRL\s0 is not yet valid. Unused. +.Ip "\fB12 X509_V_ERR_CRL_HAS_EXPIRED: \s-1CRL\s0 has expired\fR" 4 +.IX Item "12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired" +the \s-1CRL\s0 has expired. Unused. +.Ip "\fB13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field\fR" 4 +.IX Item "13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field" +the certificate notBefore field contains an invalid time. +.Ip "\fB14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field\fR" 4 +.IX Item "14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field" +the certificate notAfter field contains an invalid time. +.Ip "\fB15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in \s-1CRL\s0's lastUpdate field\fR" 4 +.IX Item "15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field" +the \s-1CRL\s0 lastUpdate field contains an invalid time. Unused. +.Ip "\fB16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in \s-1CRL\s0's nextUpdate field\fR" 4 +.IX Item "16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field" +the \s-1CRL\s0 nextUpdate field contains an invalid time. Unused. +.Ip "\fB17 X509_V_ERR_OUT_OF_MEM: out of memory\fR" 4 +.IX Item "17 X509_V_ERR_OUT_OF_MEM: out of memory" +an error occurred trying to allocate memory. This should never happen. +.Ip "\fB18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate\fR" 4 +.IX Item "18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate" +the passed certificate is self signed and the same certificate cannot be found in the list of +trusted certificates. +.Ip "\fB19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain\fR" 4 +.IX Item "19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain" +the certificate chain could be built up using the untrusted certificates but the root could not +be found locally. +.Ip "\fB20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate\fR" 4 +.IX Item "20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate" +the issuer certificate of a locally looked up certificate could not be found. This normally means +the list of trusted certificates is not complete. +.Ip "\fB21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate\fR" 4 +.IX Item "21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate" +no signatures could be verified because the chain contains only one certificate and it is not +self signed. +.Ip "\fB22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long\fR" 4 +.IX Item "22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long" +the certificate chain length is greater than the supplied maximum depth. Unused. +.Ip "\fB23 X509_V_ERR_CERT_REVOKED: certificate revoked\fR" 4 +.IX Item "23 X509_V_ERR_CERT_REVOKED: certificate revoked" +the certificate has been revoked. Unused. +.Ip "\fB24 X509_V_ERR_INVALID_CA: invalid \s-1CA\s0 certificate\fR" 4 +.IX Item "24 X509_V_ERR_INVALID_CA: invalid CA certificate" +a \s-1CA\s0 certificate is invalid. Either it is not a \s-1CA\s0 or its extensions are not consistent +with the supplied purpose. +.Ip "\fB25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded\fR" 4 +.IX Item "25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded" +the basicConstraints pathlength parameter has been exceeded. +.Ip "\fB26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose\fR" 4 +.IX Item "26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose" +the supplied certificate cannot be used for the specified purpose. +.Ip "\fB27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted\fR" 4 +.IX Item "27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted" +the root \s-1CA\s0 is not marked as trusted for the specified purpose. +.Ip "\fB28 X509_V_ERR_CERT_REJECTED: certificate rejected\fR" 4 +.IX Item "28 X509_V_ERR_CERT_REJECTED: certificate rejected" +the root \s-1CA\s0 is marked to reject the specified purpose. +.Ip "\fB29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch\fR" 4 +.IX Item "29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch" +the current candidate issuer certificate was rejected because its subject name +did not match the issuer name of the current certificate. Only displayed when +the \fB\-issuer_checks\fR option is set. +.Ip "\fB30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch\fR" 4 +.IX Item "30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch" +the current candidate issuer certificate was rejected because its subject key +identifier was present and did not match the authority key identifier current +certificate. Only displayed when the \fB\-issuer_checks\fR option is set. +.Ip "\fB31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch\fR" 4 +.IX Item "31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch" +the current candidate issuer certificate was rejected because its issuer name +and serial number was present and did not match the authority key identifier +of the current certificate. Only displayed when the \fB\-issuer_checks\fR option is set. +.Ip "\fB32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing\fR" 4 +.IX Item "32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing" +the current candidate issuer certificate was rejected because its keyUsage extension +does not permit certificate signing. +.Ip "\fB50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure\fR" 4 +.IX Item "50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure" +an application specific error. Unused. +.SH "BUGS" +.IX Header "BUGS" +Although the issuer checks are a considerably improvement over the old technique they still +suffer from limitations in the underlying X509_LOOKUP \s-1API\s0. One consequence of this is that +trusted certificates with matching subject name must either appear in a file (as specified by the +\&\fB\-CAfile\fR option) or a directory (as specified by \fB\-CApath\fR. If they occur in both then only +the certificates in the file will be recognised. +.PP +Previous versions of OpenSSL assume certificates with matching subject name are identical and +mishandled them. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +x509(1) |
