doc/crypto/X509_STORE_CTX_get_error.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_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
  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 occurred 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 certificate 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 certificate'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 signature>
  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 public 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 time.
 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 lastUpdate 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 nextUpdate 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 certificate 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 certificate>
 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 mismatch>
 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 number 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 signing>
 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 extension>
 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 occurred in the permitted subtrees.
 250
 251 =item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
 252
 253 A 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
 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 constraint 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 occurred 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 =back
 282
 283 =head1 NOTES
 284
 285 The above functions should be used instead of directly referencing the fields
 286 in the B<X509_VERIFY_CTX> structure.
 287
 288 In versions of OpenSSL before 1.0 the current certificate returned by
 289 X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should
 290 check the return value before printing out any debugging information relating
 291 to the current certificate.
 292
 293 If an unrecognised error code is passed to X509_verify_cert_error_string() the
 294 numerical value of the unknown code is returned in a static buffer. This is not
 295 thread safe but will never happen unless an invalid code is passed.
 296
 297 =head1 SEE ALSO
 298
 299 L<X509_verify_cert(3)>
 300
 301 =head1 HISTORY
 302
 303 TBA
 304
 305 =cut