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