doc/man3/X509_STORE_CTX_get_error.pod

   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 non-negative 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 non-negative 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 could not be found: this occurs if the issuer certificate
 105 of an untrusted certificate cannot be found.
 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 of a locally looked up certificate could not be found.
 184 This normally means the list of trusted certificates is not complete.
 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-2016 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