OLD | NEW |
(Empty) | |
| 1 =pod |
| 2 |
| 3 =head1 NAME |
| 4 |
| 5 X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, X509_STORE_CTX_get_error_dep
th, X509_STORE_CTX_get_current_cert, X509_STORE_CTX_get1_chain, X509_verify_cert
_error_string - get or set certificate verification status information |
| 6 |
| 7 =head1 SYNOPSIS |
| 8 |
| 9 #include <openssl/x509.h> |
| 10 #include <openssl/x509_vfy.h> |
| 11 |
| 12 int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); |
| 13 void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s); |
| 14 int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); |
| 15 X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); |
| 16 |
| 17 STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); |
| 18 |
| 19 const char *X509_verify_cert_error_string(long n); |
| 20 |
| 21 =head1 DESCRIPTION |
| 22 |
| 23 These functions are typically called after X509_verify_cert() has indicated |
| 24 an error or in a verification callback to determine the nature of an error. |
| 25 |
| 26 X509_STORE_CTX_get_error() returns the error code of B<ctx>, see |
| 27 the B<ERROR CODES> section for a full description of all error codes. |
| 28 |
| 29 X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example |
| 30 it might be used in a verification callback to set an error based on additional |
| 31 checks. |
| 32 |
| 33 X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a |
| 34 non-negative integer representing where in the certificate chain the error |
| 35 occurred. If it is zero it occured in the end entity certificate, one if |
| 36 it is the certificate which signed the end entity certificate and so on. |
| 37 |
| 38 X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which |
| 39 caused the error or B<NULL> if no certificate is relevant. |
| 40 |
| 41 X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous |
| 42 call to X509_verify_cert() is successful. If the call to X509_verify_cert() |
| 43 is B<not> successful the returned chain may be incomplete or invalid. The |
| 44 returned chain persists after the B<ctx> structure is freed, when it is |
| 45 no longer needed it should be free up using: |
| 46 |
| 47 sk_X509_pop_free(chain, X509_free); |
| 48 |
| 49 X509_verify_cert_error_string() returns a human readable error string for |
| 50 verification error B<n>. |
| 51 |
| 52 =head1 RETURN VALUES |
| 53 |
| 54 X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code. |
| 55 |
| 56 X509_STORE_CTX_get_error_depth() returns a non-negative error depth. |
| 57 |
| 58 X509_STORE_CTX_get_current_cert() returns the cerificate which caused the |
| 59 error or B<NULL> if no certificate is relevant to the error. |
| 60 |
| 61 X509_verify_cert_error_string() returns a human readable error string for |
| 62 verification error B<n>. |
| 63 |
| 64 =head1 ERROR CODES |
| 65 |
| 66 A list of error codes and messages is shown below. Some of the |
| 67 error codes are defined but currently never returned: these are described as |
| 68 "unused". |
| 69 |
| 70 =over 4 |
| 71 |
| 72 =item B<X509_V_OK: ok> |
| 73 |
| 74 the operation was successful. |
| 75 |
| 76 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> |
| 77 |
| 78 the issuer certificate could not be found: this occurs if the issuer certificate |
| 79 of an untrusted certificate cannot be found. |
| 80 |
| 81 =item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> |
| 82 |
| 83 the CRL of a certificate could not be found. |
| 84 |
| 85 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certifica
te's signature> |
| 86 |
| 87 the certificate signature could not be decrypted. This means that the actual |
| 88 signature value could not be determined rather than it not matching the |
| 89 expected value, this is only meaningful for RSA keys. |
| 90 |
| 91 =item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's sign
ature> |
| 92 |
| 93 the CRL signature could not be decrypted: this means that the actual signature |
| 94 value could not be determined rather than it not matching the expected value. |
| 95 Unused. |
| 96 |
| 97 =item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer p
ublic key> |
| 98 |
| 99 the public key in the certificate SubjectPublicKeyInfo could not be read. |
| 100 |
| 101 =item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> |
| 102 |
| 103 the signature of the certificate is invalid. |
| 104 |
| 105 =item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> |
| 106 |
| 107 the signature of the certificate is invalid. |
| 108 |
| 109 =item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> |
| 110 |
| 111 the certificate is not yet valid: the notBefore date is after the current time. |
| 112 |
| 113 =item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> |
| 114 |
| 115 the certificate has expired: that is the notAfter date is before the current tim
e. |
| 116 |
| 117 =item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> |
| 118 |
| 119 the CRL is not yet valid. |
| 120 |
| 121 =item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> |
| 122 |
| 123 the CRL has expired. |
| 124 |
| 125 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's
notBefore field> |
| 126 |
| 127 the certificate notBefore field contains an invalid time. |
| 128 |
| 129 =item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's
notAfter field> |
| 130 |
| 131 the certificate notAfter field contains an invalid time. |
| 132 |
| 133 =item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpd
ate field> |
| 134 |
| 135 the CRL lastUpdate field contains an invalid time. |
| 136 |
| 137 =item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpd
ate field> |
| 138 |
| 139 the CRL nextUpdate field contains an invalid time. |
| 140 |
| 141 =item B<X509_V_ERR_OUT_OF_MEM: out of memory> |
| 142 |
| 143 an error occurred trying to allocate memory. This should never happen. |
| 144 |
| 145 =item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> |
| 146 |
| 147 the passed certificate is self signed and the same certificate cannot be found |
| 148 in the list of trusted certificates. |
| 149 |
| 150 =item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certifi
cate chain> |
| 151 |
| 152 the certificate chain could be built up using the untrusted certificates but |
| 153 the root could not be found locally. |
| 154 |
| 155 =item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer
certificate> |
| 156 |
| 157 the issuer certificate of a locally looked up certificate could not be found. |
| 158 This normally means the list of trusted certificates is not complete. |
| 159 |
| 160 =item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first c
ertificate> |
| 161 |
| 162 no signatures could be verified because the chain contains only one certificate |
| 163 and it is not self signed. |
| 164 |
| 165 =item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> |
| 166 |
| 167 the certificate chain length is greater than the supplied maximum depth. Unused. |
| 168 |
| 169 =item B<X509_V_ERR_CERT_REVOKED: certificate revoked> |
| 170 |
| 171 the certificate has been revoked. |
| 172 |
| 173 =item B<X509_V_ERR_INVALID_CA: invalid CA certificate> |
| 174 |
| 175 a CA certificate is invalid. Either it is not a CA or its extensions are not |
| 176 consistent with the supplied purpose. |
| 177 |
| 178 =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> |
| 179 |
| 180 the basicConstraints pathlength parameter has been exceeded. |
| 181 |
| 182 =item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> |
| 183 |
| 184 the supplied certificate cannot be used for the specified purpose. |
| 185 |
| 186 =item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> |
| 187 |
| 188 the root CA is not marked as trusted for the specified purpose. |
| 189 |
| 190 =item B<X509_V_ERR_CERT_REJECTED: certificate rejected> |
| 191 |
| 192 the root CA is marked to reject the specified purpose. |
| 193 |
| 194 =item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> |
| 195 |
| 196 the current candidate issuer certificate was rejected because its subject name |
| 197 did not match the issuer name of the current certificate. This is only set |
| 198 if issuer check debugging is enabled it is used for status notification and |
| 199 is B<not> in itself an error. |
| 200 |
| 201 =item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mism
atch> |
| 202 |
| 203 the current candidate issuer certificate was rejected because its subject key |
| 204 identifier was present and did not match the authority key identifier current |
| 205 certificate. This is only set if issuer check debugging is enabled it is used |
| 206 for status notification and is B<not> in itself an error. |
| 207 |
| 208 =item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial numb
er mismatch> |
| 209 |
| 210 the current candidate issuer certificate was rejected because its issuer name |
| 211 and serial number was present and did not match the authority key identifier of |
| 212 the current certificate. This is only set if issuer check debugging is enabled |
| 213 it is used for status notification and is B<not> in itself an error. |
| 214 |
| 215 =item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate s
igning> |
| 216 |
| 217 the current candidate issuer certificate was rejected because its keyUsage |
| 218 extension does not permit certificate signing. This is only set if issuer check |
| 219 debugging is enabled it is used for status notification and is B<not> in itself |
| 220 an error. |
| 221 |
| 222 =item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extens
ion> |
| 223 |
| 224 A certificate extension had an invalid value (for example an incorrect |
| 225 encoding) or some value inconsistent with other extensions. |
| 226 |
| 227 |
| 228 =item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate
policy extension> |
| 229 |
| 230 A certificate policies extension had an invalid value (for example an incorrect |
| 231 encoding) or some value inconsistent with other extensions. This error only |
| 232 occurs if policy processing is enabled. |
| 233 |
| 234 =item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> |
| 235 |
| 236 The verification flags were set to require and explicit policy but none was |
| 237 present. |
| 238 |
| 239 =item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> |
| 240 |
| 241 The only CRLs that could be found did not match the scope of the certificate. |
| 242 |
| 243 =item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> |
| 244 |
| 245 Some feature of a certificate extension is not supported. Unused. |
| 246 |
| 247 =item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> |
| 248 |
| 249 A name constraint violation occured in the permitted subtrees. |
| 250 |
| 251 =item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> |
| 252 |
| 253 A name constraint violation occured in the excluded subtrees. |
| 254 |
| 255 =item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supp
orted> |
| 256 |
| 257 A certificate name constraints extension included a minimum or maximum field: |
| 258 this is not supported. |
| 259 |
| 260 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type
> |
| 261 |
| 262 An unsupported name constraint type was encountered. OpenSSL currently only |
| 263 supports directory name, DNS name, email and URI types. |
| 264 |
| 265 =item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name co
nstraint syntax> |
| 266 |
| 267 The format of the name constraint is not recognised: for example an email |
| 268 address format of a form not mentioned in RFC3280. This could be caused by |
| 269 a garbage extension or some new feature not currently supported. |
| 270 |
| 271 =item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> |
| 272 |
| 273 An error occured when attempting to verify the CRL path. This error can only |
| 274 happen if extended CRL checking is enabled. |
| 275 |
| 276 =item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> |
| 277 |
| 278 an application specific error. This will never be returned unless explicitly |
| 279 set by an application. |
| 280 |
| 281 =head1 NOTES |
| 282 |
| 283 The above functions should be used instead of directly referencing the fields |
| 284 in the B<X509_VERIFY_CTX> structure. |
| 285 |
| 286 In versions of OpenSSL before 1.0 the current certificate returned by |
| 287 X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should |
| 288 check the return value before printing out any debugging information relating |
| 289 to the current certificate. |
| 290 |
| 291 If an unrecognised error code is passed to X509_verify_cert_error_string() the |
| 292 numerical value of the unknown code is returned in a static buffer. This is not |
| 293 thread safe but will never happen unless an invalid code is passed. |
| 294 |
| 295 =head1 SEE ALSO |
| 296 |
| 297 L<X509_verify_cert(3)|X509_verify_cert(3)> |
| 298 |
| 299 =head1 HISTORY |
| 300 |
| 301 TBA |
| 302 |
| 303 =cut |
OLD | NEW |