convert X509 manuals from pod to mdoc

1 files changed, 297 insertions, 0 deletions

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