Next: Verifying a certificate in the context of TLS session, Previous: X.509 public and private keys, Up: X.509 certificates [Contents][Index]
Verifying certificate paths is important in X.509 authentication. For this purpose the following functions are provided.
list: The list
clist: A list of CAs
clist_size: The length of the CA list
flags: should be 0 or an or’ed sequence of GNUTLS_TL
options.
This function will add the given certificate authorities to the trusted list. The list of CAs must not be deinitialized during this structure’s lifetime.
If the flag GNUTLS_TL_NO_DUPLICATES
is specified, then
the provided clist
entries that are duplicates will not be
added to the list and will be deinitialized.
Returns: The number of added elements is returned.
Since: 3.0.0
list: The list
cert: A certificate
name: An identifier for the certificate
name_size: The size of the identifier
flags: should be 0.
This function will add the given certificate to the trusted
list and associate it with a name. The certificate will not be
be used for verification with gnutls_x509_trust_list_verify_crt()
but with gnutls_x509_trust_list_verify_named_crt()
or
gnutls_x509_trust_list_verify_crt2()
- the latter only since
GnuTLS 3.4.0 and if a hostname is provided.
In principle this function can be used to set individual "server" certificates that are trusted by the user for that specific server but for no other purposes.
The certificate must not be deinitialized during the lifetime of the trusted list.
Returns: On success, GNUTLS_E_SUCCESS
(0) is returned, otherwise a
negative error value.
Since: 3.0.0
list: The list
crl_list: A list of CRLs
crl_size: The length of the CRL list
flags: if GNUTLS_TL_VERIFY_CRL is given the CRLs will be verified before being added.
verification_flags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
This function will add the given certificate revocation lists to the trusted list. The list of CRLs must not be deinitialized during this structure’s lifetime.
This function must be called after gnutls_x509_trust_list_add_cas()
to allow verifying the CRLs for validity.
Returns: The number of added elements is returned.
Since: 3.0
list: The list
cert_list: is the certificate list to be verified
cert_list_size: is the certificate list size
flags: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
voutput: will hold the certificate verification output.
func: If non-null will be called on each chain element verification with the output.
This function will try to verify the given certificate and return
its status. The voutput
parameter will hold an OR’ed sequence of
gnutls_certificate_status_t
flags.
The details of the verification are the same as in gnutls_x509_trust_list_verify_crt2()
.
Returns: On success, GNUTLS_E_SUCCESS
(0) is returned, otherwise a
negative error value.
Since: 3.0
list: The list
cert_list: is the certificate list to be verified
cert_list_size: is the certificate list size
data: an array of typed data
elements: the number of data elements
flags: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
voutput: will hold the certificate verification output.
func: If non-null will be called on each chain element verification with the output.
This function will attempt to verify the given certificate and return
its status. The voutput
parameter will hold an OR’ed sequence of
gnutls_certificate_status_t
flags. When a chain of cert_list_size
with
more than one certificates is provided, the verification status will apply
to the first certificate in the chain that failed verification. The
verification process starts from the end of the chain (from CA to end
certificate).
Additionally a certificate verification profile can be specified
from the ones in gnutls_certificate_verification_profiles_t
by
ORing the result of GNUTLS_PROFILE_TO_VFLAGS()
to the verification
flags.
The acceptable data
types are GNUTLS_DT_DNS_HOSTNAME
and GNUTLS_DT_KEY_PURPOSE_OID
.
The former accepts as data a null-terminated hostname, and the latter a null-terminated
object identifier (e.g., GNUTLS_KP_TLS_WWW_SERVER
).
If a DNS hostname is provided then this function will compare
the hostname in the certificate against the given. If names do not match the
GNUTLS_CERT_UNEXPECTED_OWNER
status flag will be set. In addition it
will consider certificates provided with gnutls_x509_trust_list_add_named_crt()
.
If a key purpose OID is provided and the end-certificate contains the extended key
usage PKIX extension, it will be required to match the provided OID
or be marked for any purpose, otherwise verification will fail with
GNUTLS_CERT_PURPOSE_MISMATCH
status.
Returns: On success, GNUTLS_E_SUCCESS
(0) is returned, otherwise a
negative error value. Note that verification failure will not result to an
error code, only voutput
will be updated.
Since: 3.3.8
list: The list
cert: is the certificate to be verified
name: is the certificate’s name
name_size: is the certificate’s name size
flags: Flags that may be used to change the verification algorithm. Use OR of the gnutls_certificate_verify_flags enumerations.
voutput: will hold the certificate verification output.
func: If non-null will be called on each chain element verification with the output.
This function will try to find a certificate that is associated with the provided
name –see gnutls_x509_trust_list_add_named_crt()
. If a match is found the
certificate is considered valid. In addition to that this function will also
check CRLs. The voutput
parameter will hold an OR’ed sequence of
gnutls_certificate_status_t
flags.
Additionally a certificate verification profile can be specified
from the ones in gnutls_certificate_verification_profiles_t
by
ORing the result of GNUTLS_PROFILE_TO_VFLAGS()
to the verification
flags.
Returns: On success, GNUTLS_E_SUCCESS
(0) is returned, otherwise a
negative error value.
Since: 3.0.0
list: The list
ca_file: A file containing a list of CAs (optional)
crl_file: A file containing a list of CRLs (optional)
type: The format of the certificates
tl_flags: GNUTLS_TL_*
tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
This function will add the given certificate authorities
to the trusted list. PKCS 11
URLs are also accepted, instead
of files, by this function. A PKCS 11
URL implies a trust
database (a specially marked module in p11-kit); the URL "pkcs11:"
implies all trust databases in the system. Only a single URL specifying
trust databases can be set; they cannot be stacked with multiple calls.
Returns: The number of added elements is returned.
Since: 3.1
list: The list
cas: A buffer containing a list of CAs (optional)
crls: A buffer containing a list of CRLs (optional)
type: The format of the certificates
tl_flags: GNUTLS_TL_*
tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
This function will add the given certificate authorities to the trusted list.
Returns: The number of added elements is returned.
Since: 3.1
list: The structure of the list
tl_flags: GNUTLS_TL_*
tl_vflags: gnutls_certificate_verify_flags if flags specifies GNUTLS_TL_VERIFY_CRL
This function adds the system’s default trusted certificate
authorities to the trusted list. Note that on unsupported systems
this function returns GNUTLS_E_UNIMPLEMENTED_FEATURE
.
This function implies the flag GNUTLS_TL_NO_DUPLICATES
.
Returns: The number of added elements or a negative error code on error.
Since: 3.1
The verification function will verify a given certificate chain against a list of certificate
authorities and certificate revocation lists, and output
a bit-wise OR of elements of the gnutls_certificate_status_t
enumeration shown in Figure 4.2. The GNUTLS_CERT_INVALID
flag
is always set on a verification error and more detailed flags will also be set when appropriate.
GNUTLS_CERT_INVALID
The certificate is not signed by one of the
known authorities or the signature is invalid (deprecated by the flags
GNUTLS_CERT_SIGNATURE_FAILURE
and GNUTLS_CERT_SIGNER_NOT_FOUND
).
GNUTLS_CERT_REVOKED
Certificate is revoked by its authority. In X.509 this will be set only if CRLs are checked.
GNUTLS_CERT_SIGNER_NOT_FOUND
The certificate’s issuer is not known. This is the case if the issuer is not included in the trusted certificate list.
GNUTLS_CERT_SIGNER_NOT_CA
The certificate’s signer was not a CA. This may happen if this was a version 1 certificate, which is common with some CAs, or a version 3 certificate without the basic constrains extension.
GNUTLS_CERT_INSECURE_ALGORITHM
The certificate was signed using an insecure algorithm such as MD2 or MD5. These algorithms have been broken and should not be trusted.
GNUTLS_CERT_NOT_ACTIVATED
The certificate is not yet activated.
GNUTLS_CERT_EXPIRED
The certificate has expired.
GNUTLS_CERT_SIGNATURE_FAILURE
The signature verification failed.
GNUTLS_CERT_REVOCATION_DATA_SUPERSEDED
The revocation data are old and have been superseded.
GNUTLS_CERT_UNEXPECTED_OWNER
The owner is not the expected one.
GNUTLS_CERT_REVOCATION_DATA_ISSUED_IN_FUTURE
The revocation data have a future issue date.
GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE
The certificate’s signer constraints were violated.
GNUTLS_CERT_MISMATCH
The certificate presented isn’t the expected one (TOFU)
GNUTLS_CERT_PURPOSE_MISMATCH
The certificate or an intermediate does not match the intended purpose (extended key usage).
Figure 4.2: The gnutls_certificate_status_t
enumeration.
An example of certificate verification is shown in ex-verify2. It is also possible to have a set of certificates that are trusted for a particular server but not to authorize other certificates. This purpose is served by the functions gnutls_x509_trust_list_add_named_crt and gnutls_x509_trust_list_verify_named_crt.
Next: Verifying a certificate in the context of TLS session, Previous: X.509 public and private keys, Up: X.509 certificates [Contents][Index]