From e23d00ab37299e14c06d5d2b599a3793e3d0575c Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 4 Nov 2016 15:29:03 +0000 Subject: convert X509 manuals from pod to mdoc --- src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 | 297 +++++++++++++++++++++++ 1 file changed, 297 insertions(+) create mode 100644 src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 (limited to 'src/lib/libcrypto/man/X509_STORE_CTX_get_error.3') diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 b/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 new file mode 100644 index 0000000000..f31e438cde --- /dev/null +++ b/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 @@ -0,0 +1,297 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_STORE_CTX_GET_ERROR 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_get_error , +.Nm X509_STORE_CTX_set_error , +.Nm X509_STORE_CTX_get_error_depth , +.Nm X509_STORE_CTX_get_current_cert , +.Nm X509_STORE_CTX_get1_chain , +.Nm X509_verify_cert_error_string +.Nd get or set certificate verification status information +.Sh SYNOPSIS +.In openssl/x509.h +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_CTX_get_error +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_error +.Fa "X509_STORE_CTX *ctx" +.Fa "int s" +.Fc +.Ft int +.Fo X509_STORE_CTX_get_error_depth +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft X509 * +.Fo X509_STORE_CTX_get_current_cert +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_CTX_get1_chain +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft const char * +.Fo X509_verify_cert_error_string +.Fa "long n" +.Fc +.Sh DESCRIPTION +These functions are typically called after +.Xr X509_verify_cert 3 +has indicated an error or in a verification callback to determine the +nature of an error. +.Pp +.Fn X509_STORE_CTX_get_error +returns the error code of +.Fa ctx . +See the +.Sy ERROR CODES +section for a full description of all error codes. +.Pp +.Fn X509_STORE_CTX_set_error +sets the error code of +.Fa ctx +to +.Fa s . +For example it might be used in a verification callback to set an error +based on additional checks. +.Pp +.Fn X509_STORE_CTX_get_error_depth +returns the depth of the error. +This is a non-negative integer representing where in the certificate +chain the error occurred. +If it is zero, it occurred in the end entity certificate, one if it is +the certificate which signed the end entity certificate, and so on. +.Pp +.Fn X509_STORE_CTX_get_current_cert +returns the certificate in +.Fa ctx +which caused the error or +.Dv NULL +if no certificate is relevant. +.Pp +.Fn X509_STORE_CTX_get1_chain +returns a complete validate chain if a previous call to +.Xr X509_verify_cert 3 +is successful. +If the call to +.Xr X509_verify_cert 3 +is +.Sy not +successful, the returned chain may be incomplete or invalid. +The returned chain persists after the +.Fa ctx +structure is freed. +When it is no longer needed, it should be free up using +.Fn sk_X509_pop_free chain X509_free . +.Pp +.Fn X509_verify_cert_error_string +returns a human readable error string for verification error +.Fa n . +.Pp +The above functions should be used instead of directly referencing the +fields in the +.Sy X509_VERIFY_CTX +structure. +.Pp +In versions of OpenSSL before 1.0, the current certificate returned by +.Fn X509_STORE_CTX_get_current_cert +was never +.Dv NULL . +Applications should check the return value before printing out any +debugging information relating to the current certificate. +.Pp +If an unrecognised error code is passed to +.Fn X509_verify_cert_error_string , +the numerical value of the unknown code is returned in a static buffer. +This is not thread safe but will never happen unless an invalid code is +passed. +.Sh RETURN VALUES +.Fn X509_STORE_CTX_get_error +returns +.Dv X509_V_OK +or an error code. +.Pp +.Fn X509_STORE_CTX_get_error_depth +returns a non-negative error depth. +.Pp +.Fn X509_STORE_CTX_get_current_cert +returns the certificate which caused the error or +.Dv NULL +if no certificate is relevant to the error. +.Pp +.Fn X509_verify_cert_error_string +returns a human readable error string for verification error +.Fa n . +.Sh ERROR CODES +A list of error codes and messages is shown below. +Some of the error codes are defined but currently never returned: +these are described as "unused". +.Bl -tag -width Ds +.It Dv X509_V_OK : No ok +The operation was successful. +.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_GET_CRL : No unable to get certificate CRL +The CRL of a certificate could not be found. +.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY : \ + No unable to decode issuer public key +The public key in the certificate SubjectPublicKeyInfo could not be read. +.It Dv X509_V_ERR_CERT_SIGNATURE_FAILURE : No certificate signature failure +The signature of the certificate is invalid. +.It Dv X509_V_ERR_CRL_SIGNATURE_FAILURE : No CRL signature failure +The signature of the certificate is invalid. +.It Dv X509_V_ERR_CERT_NOT_YET_VALID : No certificate is not yet valid +The certificate is not yet valid: the notBefore date is after the +current time. +.It Dv X509_V_ERR_CERT_HAS_EXPIRED : No certificate has expired +The certificate has expired: that is the notAfter date is before the +current time. +.It Dv X509_V_ERR_CRL_NOT_YET_VALID : No CRL is not yet valid +The CRL is not yet valid. +.It Dv X509_V_ERR_CRL_HAS_EXPIRED : No CRL has expired +The CRL has expired. +.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD : \ + No format error in certificate's notBefore field +The certificate notBefore field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD : \ + No format error in certificate's notAfter field +The certificate notAfter field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD : \ + No format error in CRL's lastUpdate field +The CRL lastUpdate field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD : \ + No format error in CRL's nextUpdate field +The CRL nextUpdate field contains an invalid time. +.It Dv X509_V_ERR_OUT_OF_MEM : No out of memory +An error occurred trying to allocate memory. +This should never happen. +.It Dv X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT : No self signed certificate +The passed certificate is self signed and the same certificate cannot be +found in the list of trusted certificates. +.It Dv X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY : \ + No 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. +.It Dv X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE : \ + No unable to verify the first certificate +No signatures could be verified because the chain contains only one +certificate and it is not self signed. +.It Dv X509_V_ERR_CERT_CHAIN_TOO_LONG : No certificate chain too long +The certificate chain length is greater than the supplied maximum depth. +Unused. +.It Dv X509_V_ERR_CERT_REVOKED : No certificate revoked +The certificate has been revoked. +.It Dv X509_V_ERR_INVALID_CA : No invalid CA certificate +A CA certificate is invalid. +Either it is not a CA or its extensions are not consistent with the +supplied purpose. +.It Dv X509_V_ERR_PATH_LENGTH_EXCEEDED : No path length constraint exceeded +The basicConstraints pathlength parameter has been exceeded. +.It Dv X509_V_ERR_INVALID_PURPOSE : No unsupported certificate purpose +The supplied certificate cannot be used for the specified purpose. +.It Dv X509_V_ERR_CERT_UNTRUSTED : No certificate not trusted +The root CA is not marked as trusted for the specified purpose. +.It Dv X509_V_ERR_CERT_REJECTED : No certificate rejected +The root CA is marked to reject the specified purpose. +.It Dv X509_V_ERR_SUBJECT_ISSUER_MISMATCH : No 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 +.Sy not +in itself an error. +.It Dv X509_V_ERR_AKID_SKID_MISMATCH : \ + No 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 +.Sy not +in itself an error. +.It Dv X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH : \ + Noauthority 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 +.Sy not +in itself an error. +.It Dv X509_V_ERR_KEYUSAGE_NO_CERTSIGN : \ + No 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 +.Sy not +in itself an error. +.It Dv X509_V_ERR_INVALID_EXTENSION : \ + No invalid or inconsistent certificate extension +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. +.It Dv X509_V_ERR_INVALID_POLICY_EXTENSION : \ + No invalid or inconsistent certificate policy extension +A certificate policies extension had an invalid value (for example an +incorrect encoding) or some value inconsistent with other extensions. +This error only occurs if policy processing is enabled. +.It Dv X509_V_ERR_NO_EXPLICIT_POLICY : No no explicit policy +The verification flags were set to require and explicit policy but none +was present. +.It Dv X509_V_ERR_DIFFERENT_CRL_SCOPE : No different CRL scope +The only CRLs that could be found did not match the scope of the +certificate. +.It Dv X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE : \ + No unsupported extension feature +Some feature of a certificate extension is not supported. +Unused. +.It Dv X509_V_ERR_PERMITTED_VIOLATION : No permitted subtree violation +A name constraint violation occurred in the permitted subtrees. +.It Dv X509_V_ERR_EXCLUDED_VIOLATION : No excluded subtree violation +A name constraint violation occurred in the excluded subtrees. +.It Dv X509_V_ERR_SUBTREE_MINMAX : \ + No name constraints minimum and maximum not supported +A certificate name constraints extension included a minimum or maximum +field: this is not supported. +.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE : \ + No unsupported name constraint type +An unsupported name constraint type was encountered. +OpenSSL currently only supports directory name, DNS name, email and URI +types. +.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX : \ + No unsupported or invalid name constraint syntax +The format of the name constraint is not recognised: for example an +email address format of a form not mentioned in RFC3280. +This could be caused by a garbage extension or some new feature not +currently supported. +.It Dv X509_V_ERR_CRL_PATH_VALIDATION_ERROR : No CRL path validation error +An error occurred when attempting to verify the CRL path. +This error can only happen if extended CRL checking is enabled. +.It Dv X509_V_ERR_APPLICATION_VERIFICATION : \ + No application verification failure +An application specific error. +This will never be returned unless explicitly set by an application. +.El +.Sh SEE ALSO +.Xr X509_verify_cert 3 -- cgit v1.2.3-55-g6feb