--- /dev/null
+=pod
+
+=head1 NAME
+
+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 - get or set certificate verification status information
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx);
+ void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s);
+ int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx);
+ X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx);
+
+ STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx);
+
+=head1 DESCRIPTION
+
+These functions are typically called after X509_verify_cert() has indicated
+an error or in a verification callback to determine the nature of an error.
+
+X509_STORE_CTX_get_error() returns the error code of B<ctx>, see
+the B<ERROR CODES> section for a full description of all error codes.
+
+X509_STORE_CTX_set_error() sets the error code of B<ctx> to B<s>. For example
+it might be used in a verification callback to set an error based on additional
+checks.
+
+X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a
+non-negative integer representing where in the certificate chain the error
+occurred. If it is zero it occured in the end entity certificate, one if
+it is the certificate which signed the end entity certificate and so on.
+
+X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which
+caused the error or B<NULL> if no certificate is relevant.
+
+X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous
+call to X509_verify_cert() is successful. If the call to X509_verify_cert()
+is B<not> successful the returned chain may be incomplete or invalid. The
+returned chain persists after the B<ctx> structure is freed, when it is
+no longer needed it should be free up using:
+
+ sk_X509_pop_free(chain, X509_free);
+
+=head1 RETURN VALUES
+
+X509_STORE_CTX_get_error() returns an B<X509_V_OK> or an error code.
+
+X509_STORE_CTX_get_error_depth() returns a non-negative error depth.
+
+X509_STORE_CTX_get_current_cert() returns the cerificate which caused the
+error or B<NULL> if no certificate is relevant to the error.
+
+=head1 ERROR CODES
+
+An exhaustive list of the error codes and messages is shown below, this also
+includes the name of the error code as defined in the header file x509_vfy.h
+Some of the error codes are defined but never returned: these are described
+as "unused".
+
+=over 4
+
+=item B<0 X509_V_OK: ok>
+
+the operation was successful.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
+
+the issuer certificate could not be found: this occurs if the issuer certificate
+of an untrusted certificate cannot be found.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
+
+the CRL of a certificate could not be found.
+
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
+
+the certificate signature could not be decrypted. This means that the actual
+signature value could not be determined rather than it not matching the
+expected value, this is only meaningful for RSA keys.
+
+=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
+
+the CRL signature could not be decrypted: this means that the actual signature
+value could not be determined rather than it not matching the expected value.
+Unused.
+
+=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
+
+the public key in the certificate SubjectPublicKeyInfo could not be read.
+
+=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
+
+the signature of the certificate is invalid.
+
+=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
+
+the signature of the certificate is invalid.
+
+=item B<X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
+
+the certificate is not yet valid: the notBefore date is after the current time.
+
+=item B<X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
+
+the certificate has expired: that is the notAfter date is before the current time.
+
+=item B<X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
+
+the CRL is not yet valid.
+
+=item B<X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
+
+the CRL has expired.
+
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
+
+the certificate notBefore field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
+
+the certificate notAfter field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
+
+the CRL lastUpdate field contains an invalid time.
+
+=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
+
+the CRL nextUpdate field contains an invalid time.
+
+=item B<X509_V_ERR_OUT_OF_MEM: out of memory>
+
+an error occurred trying to allocate memory. This should never happen.
+
+=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
+
+the passed certificate is self signed and the same certificate cannot be found
+in the list of trusted certificates.
+
+=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
+
+the certificate chain could be built up using the untrusted certificates but
+the root could not be found locally.
+
+=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
+
+the issuer certificate of a locally looked up certificate could not be found.
+This normally means the list of trusted certificates is not complete.
+
+=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
+
+no signatures could be verified because the chain contains only one certificate
+and it is not self signed.
+
+=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
+
+the certificate chain length is greater than the supplied maximum depth. Unused.
+
+=item B<X509_V_ERR_CERT_REVOKED: certificate revoked>
+
+the certificate has been revoked.
+
+=item B<X509_V_ERR_INVALID_CA: invalid CA certificate>
+
+a CA certificate is invalid. Either it is not a CA or its extensions are not
+consistent with the supplied purpose.
+
+=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
+
+the basicConstraints pathlength parameter has been exceeded.
+
+=item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
+
+the supplied certificate cannot be used for the specified purpose.
+
+=item B<X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
+
+the root CA is not marked as trusted for the specified purpose.
+
+=item B<X509_V_ERR_CERT_REJECTED: certificate rejected>
+
+the root CA is marked to reject the specified purpose.
+
+=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
+
+the current candidate issuer certificate was rejected because its subject name
+did not match the issuer name of the current certificate. This is only set
+if issuer check debugging is enabled it is used for status notification and
+is B<not> in itself an error.
+
+=item B<X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
+
+the current candidate issuer certificate was rejected because its subject key
+identifier was present and did not match the authority key identifier current
+certificate. This is only set if issuer check debugging is enabled it is used
+for status notification and is B<not> in itself an error.
+
+=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
+
+the current candidate issuer certificate was rejected because its issuer name
+and serial number was present and did not match the authority key identifier of
+the current certificate. This is only set if issuer check debugging is enabled
+it is used for status notification and is B<not> in itself an error.
+
+=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
+
+the current candidate issuer certificate was rejected because its keyUsage
+extension does not permit certificate signing. This is only set if issuer check
+debugging is enabled it is used for status notification and is B<not> in itself
+an error.
+
+=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
+
+an application specific error. This will never be returned unless explicitly
+set by an application.
+
+=head1 NOTES
+
+The above functions should be used instead of directly referencing the fields
+in the B<X509_VERIFY_CTX> structure.
+
+In versions of OpenSSL before 1.0 the current certificate returned by
+X509_STORE_CTX_get_current_cert() was never B<NULL>. Applications should
+check the return value before printing out any debugging information relating
+to the current certificate.
+
+=head1 BUGS
+
+=head1 SEE ALSO
+
+L<X509_verify_cert(3)|X509_verify_cert(3)>
+
+=head1 HISTORY
+
+TBA
+
+=cut
projects / openssl.git / blobdiff