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