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