1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384SjkimX509_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 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384Sjkim #include <openssl/x509.h> 10238384Sjkim #include <openssl/x509_vfy.h> 11238384Sjkim 12238384Sjkim int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); 13238384Sjkim void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s); 14238384Sjkim int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); 15238384Sjkim X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); 16238384Sjkim 17238384Sjkim STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); 18238384Sjkim 19238384Sjkim const char *X509_verify_cert_error_string(long n); 20238384Sjkim 21238384Sjkim=head1 DESCRIPTION 22238384Sjkim 23238384SjkimThese functions are typically called after X509_verify_cert() has indicated 24238384Sjkiman error or in a verification callback to determine the nature of an error. 25238384Sjkim 26238384SjkimX509_STORE_CTX_get_error() returns the error code of B<ctx>, see 27238384Sjkimthe B<ERROR CODES> section for a full description of all error codes. 28238384Sjkim 29238384SjkimX509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example 30238384Sjkimit might be used in a verification callback to set an error based on additional 31238384Sjkimchecks. 32238384Sjkim 33238384SjkimX509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a 34238384Sjkimnon-negative integer representing where in the certificate chain the error 35238384Sjkimoccurred. If it is zero it occured in the end entity certificate, one if 36238384Sjkimit is the certificate which signed the end entity certificate and so on. 37238384Sjkim 38238384SjkimX509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which 39238384Sjkimcaused the error or B<NULL> if no certificate is relevant. 40238384Sjkim 41238384SjkimX509_STORE_CTX_get1_chain() returns a complete validate chain if a previous 42238384Sjkimcall to X509_verify_cert() is successful. If the call to X509_verify_cert() 43238384Sjkimis B<not> successful the returned chain may be incomplete or invalid. The 44238384Sjkimreturned chain persists after the B<ctx> structure is freed, when it is 45238384Sjkimno longer needed it should be free up using: 46238384Sjkim 47238384Sjkim sk_X509_pop_free(chain, X509_free); 48238384Sjkim 49238384SjkimX509_verify_cert_error_string() returns a human readable error string for 50238384Sjkimverification error B<n>. 51238384Sjkim 52238384Sjkim=head1 RETURN VALUES 53238384Sjkim 54238384SjkimX509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code. 55238384Sjkim 56238384SjkimX509_STORE_CTX_get_error_depth() returns a non-negative error depth. 57238384Sjkim 58238384SjkimX509_STORE_CTX_get_current_cert() returns the cerificate which caused the 59238384Sjkimerror or B<NULL> if no certificate is relevant to the error. 60238384Sjkim 61238384SjkimX509_verify_cert_error_string() returns a human readable error string for 62238384Sjkimverification error B<n>. 63238384Sjkim 64238384Sjkim=head1 ERROR CODES 65238384Sjkim 66238384SjkimA list of error codes and messages is shown below. Some of the 67238384Sjkimerror codes are defined but currently never returned: these are described as 68238384Sjkim"unused". 69238384Sjkim 70238384Sjkim=over 4 71238384Sjkim 72238384Sjkim=item B<X509_V_OK: ok> 73238384Sjkim 74238384Sjkimthe operation was successful. 75238384Sjkim 76238384Sjkim=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate> 77238384Sjkim 78238384Sjkimthe issuer certificate could not be found: this occurs if the issuer certificate 79238384Sjkimof an untrusted certificate cannot be found. 80238384Sjkim 81238384Sjkim=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL> 82238384Sjkim 83238384Sjkimthe CRL of a certificate could not be found. 84238384Sjkim 85238384Sjkim=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature> 86238384Sjkim 87238384Sjkimthe certificate signature could not be decrypted. This means that the actual 88238384Sjkimsignature value could not be determined rather than it not matching the 89238384Sjkimexpected value, this is only meaningful for RSA keys. 90238384Sjkim 91238384Sjkim=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature> 92238384Sjkim 93238384Sjkimthe CRL signature could not be decrypted: this means that the actual signature 94238384Sjkimvalue could not be determined rather than it not matching the expected value. 95238384SjkimUnused. 96238384Sjkim 97238384Sjkim=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key> 98238384Sjkim 99238384Sjkimthe public key in the certificate SubjectPublicKeyInfo could not be read. 100238384Sjkim 101238384Sjkim=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure> 102238384Sjkim 103238384Sjkimthe signature of the certificate is invalid. 104238384Sjkim 105238384Sjkim=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure> 106238384Sjkim 107238384Sjkimthe signature of the certificate is invalid. 108238384Sjkim 109238384Sjkim=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid> 110238384Sjkim 111238384Sjkimthe certificate is not yet valid: the notBefore date is after the current time. 112238384Sjkim 113238384Sjkim=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired> 114238384Sjkim 115238384Sjkimthe certificate has expired: that is the notAfter date is before the current time. 116238384Sjkim 117238384Sjkim=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid> 118238384Sjkim 119238384Sjkimthe CRL is not yet valid. 120238384Sjkim 121238384Sjkim=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired> 122238384Sjkim 123238384Sjkimthe CRL has expired. 124238384Sjkim 125238384Sjkim=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field> 126238384Sjkim 127238384Sjkimthe certificate notBefore field contains an invalid time. 128238384Sjkim 129238384Sjkim=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field> 130238384Sjkim 131238384Sjkimthe certificate notAfter field contains an invalid time. 132238384Sjkim 133238384Sjkim=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field> 134238384Sjkim 135238384Sjkimthe CRL lastUpdate field contains an invalid time. 136238384Sjkim 137238384Sjkim=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field> 138238384Sjkim 139238384Sjkimthe CRL nextUpdate field contains an invalid time. 140238384Sjkim 141238384Sjkim=item B<X509_V_ERR_OUT_OF_MEM: out of memory> 142238384Sjkim 143238384Sjkiman error occurred trying to allocate memory. This should never happen. 144238384Sjkim 145238384Sjkim=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate> 146238384Sjkim 147238384Sjkimthe passed certificate is self signed and the same certificate cannot be found 148238384Sjkimin the list of trusted certificates. 149238384Sjkim 150238384Sjkim=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain> 151238384Sjkim 152238384Sjkimthe certificate chain could be built up using the untrusted certificates but 153238384Sjkimthe root could not be found locally. 154238384Sjkim 155238384Sjkim=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate> 156238384Sjkim 157238384Sjkimthe issuer certificate of a locally looked up certificate could not be found. 158238384SjkimThis normally means the list of trusted certificates is not complete. 159238384Sjkim 160238384Sjkim=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate> 161238384Sjkim 162238384Sjkimno signatures could be verified because the chain contains only one certificate 163238384Sjkimand it is not self signed. 164238384Sjkim 165238384Sjkim=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long> 166238384Sjkim 167238384Sjkimthe certificate chain length is greater than the supplied maximum depth. Unused. 168238384Sjkim 169238384Sjkim=item B<X509_V_ERR_CERT_REVOKED: certificate revoked> 170238384Sjkim 171238384Sjkimthe certificate has been revoked. 172238384Sjkim 173238384Sjkim=item B<X509_V_ERR_INVALID_CA: invalid CA certificate> 174238384Sjkim 175238384Sjkima CA certificate is invalid. Either it is not a CA or its extensions are not 176238384Sjkimconsistent with the supplied purpose. 177238384Sjkim 178238384Sjkim=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> 179238384Sjkim 180238384Sjkimthe basicConstraints pathlength parameter has been exceeded. 181238384Sjkim 182238384Sjkim=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> 183238384Sjkim 184238384Sjkimthe supplied certificate cannot be used for the specified purpose. 185238384Sjkim 186238384Sjkim=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted> 187238384Sjkim 188238384Sjkimthe root CA is not marked as trusted for the specified purpose. 189238384Sjkim 190238384Sjkim=item B<X509_V_ERR_CERT_REJECTED: certificate rejected> 191238384Sjkim 192238384Sjkimthe root CA is marked to reject the specified purpose. 193238384Sjkim 194238384Sjkim=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch> 195238384Sjkim 196238384Sjkimthe current candidate issuer certificate was rejected because its subject name 197238384Sjkimdid not match the issuer name of the current certificate. This is only set 198238384Sjkimif issuer check debugging is enabled it is used for status notification and 199238384Sjkimis B<not> in itself an error. 200238384Sjkim 201238384Sjkim=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch> 202238384Sjkim 203238384Sjkimthe current candidate issuer certificate was rejected because its subject key 204238384Sjkimidentifier was present and did not match the authority key identifier current 205238384Sjkimcertificate. This is only set if issuer check debugging is enabled it is used 206238384Sjkimfor status notification and is B<not> in itself an error. 207238384Sjkim 208238384Sjkim=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch> 209238384Sjkim 210238384Sjkimthe current candidate issuer certificate was rejected because its issuer name 211238384Sjkimand serial number was present and did not match the authority key identifier of 212238384Sjkimthe current certificate. This is only set if issuer check debugging is enabled 213238384Sjkimit is used for status notification and is B<not> in itself an error. 214238384Sjkim 215238384Sjkim=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing> 216238384Sjkim 217238384Sjkimthe current candidate issuer certificate was rejected because its keyUsage 218238384Sjkimextension does not permit certificate signing. This is only set if issuer check 219238384Sjkimdebugging is enabled it is used for status notification and is B<not> in itself 220238384Sjkiman error. 221238384Sjkim 222238384Sjkim=item B<X509_V_ERR_INVALID_EXTENSION: invalid or inconsistent certificate extension> 223238384Sjkim 224238384SjkimA certificate extension had an invalid value (for example an incorrect 225238384Sjkimencoding) or some value inconsistent with other extensions. 226238384Sjkim 227238384Sjkim 228238384Sjkim=item B<X509_V_ERR_INVALID_POLICY_EXTENSION: invalid or inconsistent certificate policy extension> 229238384Sjkim 230238384SjkimA certificate policies extension had an invalid value (for example an incorrect 231238384Sjkimencoding) or some value inconsistent with other extensions. This error only 232238384Sjkimoccurs if policy processing is enabled. 233238384Sjkim 234238384Sjkim=item B<X509_V_ERR_NO_EXPLICIT_POLICY: no explicit policy> 235238384Sjkim 236238384SjkimThe verification flags were set to require and explicit policy but none was 237238384Sjkimpresent. 238238384Sjkim 239238384Sjkim=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE: Different CRL scope> 240238384Sjkim 241238384SjkimThe only CRLs that could be found did not match the scope of the certificate. 242238384Sjkim 243238384Sjkim=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE: Unsupported extension feature> 244238384Sjkim 245238384SjkimSome feature of a certificate extension is not supported. Unused. 246238384Sjkim 247238384Sjkim=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation> 248238384Sjkim 249238384SjkimA name constraint violation occured in the permitted subtrees. 250238384Sjkim 251238384Sjkim=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation> 252238384Sjkim 253238384SjkimA name constraint violation occured in the excluded subtrees. 254238384Sjkim 255238384Sjkim=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported> 256238384Sjkim 257238384SjkimA certificate name constraints extension included a minimum or maximum field: 258238384Sjkimthis is not supported. 259238384Sjkim 260238384Sjkim=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE: unsupported name constraint type> 261238384Sjkim 262238384SjkimAn unsupported name constraint type was encountered. OpenSSL currently only 263238384Sjkimsupports directory name, DNS name, email and URI types. 264238384Sjkim 265238384Sjkim=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX: unsupported or invalid name constraint syntax> 266238384Sjkim 267238384SjkimThe format of the name constraint is not recognised: for example an email 268238384Sjkimaddress format of a form not mentioned in RFC3280. This could be caused by 269238384Sjkima garbage extension or some new feature not currently supported. 270238384Sjkim 271238384Sjkim=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error> 272238384Sjkim 273238384SjkimAn error occured when attempting to verify the CRL path. This error can only 274238384Sjkimhappen if extended CRL checking is enabled. 275238384Sjkim 276238384Sjkim=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure> 277238384Sjkim 278238384Sjkiman application specific error. This will never be returned unless explicitly 279238384Sjkimset by an application. 280238384Sjkim 281264331Sjkim=back 282264331Sjkim 283238384Sjkim=head1 NOTES 284238384Sjkim 285238384SjkimThe above functions should be used instead of directly referencing the fields 286238384Sjkimin the B<X509_VERIFY_CTX> structure. 287238384Sjkim 288238384SjkimIn versions of OpenSSL before 1.0 the current certificate returned by 289238384SjkimX509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should 290238384Sjkimcheck the return value before printing out any debugging information relating 291238384Sjkimto the current certificate. 292238384Sjkim 293238384SjkimIf an unrecognised error code is passed to X509_verify_cert_error_string() the 294238384Sjkimnumerical value of the unknown code is returned in a static buffer. This is not 295238384Sjkimthread safe but will never happen unless an invalid code is passed. 296238384Sjkim 297238384Sjkim=head1 SEE ALSO 298238384Sjkim 299238384SjkimL<X509_verify_cert(3)|X509_verify_cert(3)> 300238384Sjkim 301238384Sjkim=head1 HISTORY 302238384Sjkim 303238384SjkimTBA 304238384Sjkim 305238384Sjkim=cut 306