|
Packit |
549fdc |
@node Certificate authentication
|
|
Packit |
549fdc |
@section Certificate authentication
|
|
Packit |
549fdc |
@cindex certificate authentication
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The most known authentication method of @acronym{TLS} are certificates.
|
|
Packit |
549fdc |
The PKIX @xcite{PKIX} public key infrastructure is daily used by anyone
|
|
Packit |
549fdc |
using a browser today. @acronym{GnuTLS} provides a simple API to
|
|
Packit |
549fdc |
use the @acronym{X.509} certificates @xcite{PKIX}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The key exchange algorithms supported by certificate authentication are
|
|
Packit |
549fdc |
shown in @ref{tab:key-exchange}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@float Table,tab:key-exchange
|
|
Packit |
549fdc |
@multitable @columnfractions .2 .7
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@headitem Key exchange @tab Description
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item RSA @tab
|
|
Packit |
549fdc |
The RSA algorithm is used to encrypt a key and send it to the peer.
|
|
Packit |
549fdc |
The certificate must allow the key to be used for encryption.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item DHE_@-RSA @tab
|
|
Packit |
549fdc |
The RSA algorithm is used to sign ephemeral Diffie-Hellman parameters
|
|
Packit |
549fdc |
which are sent to the peer. The key in the certificate must allow the
|
|
Packit |
549fdc |
key to be used for signing. Note that key exchange algorithms which
|
|
Packit |
549fdc |
use ephemeral Diffie-Hellman parameters, offer perfect forward
|
|
Packit |
549fdc |
secrecy. That means that even if the private key used for signing is
|
|
Packit |
549fdc |
compromised, it cannot be used to reveal past session data.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item ECDHE_@-RSA @tab
|
|
Packit |
549fdc |
The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman
|
|
Packit |
549fdc |
parameters which are sent to the peer. The key in the certificate must allow
|
|
Packit |
549fdc |
the key to be used for signing. It also offers perfect forward
|
|
Packit |
549fdc |
secrecy. That means that even if the private key used for signing is
|
|
Packit |
549fdc |
compromised, it cannot be used to reveal past session data.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item DHE_@-DSS @tab
|
|
Packit |
549fdc |
The DSA algorithm is used to sign ephemeral Diffie-Hellman parameters
|
|
Packit |
549fdc |
which are sent to the peer. The certificate must contain DSA
|
|
Packit |
549fdc |
parameters to use this key exchange algorithm. DSA is the algorithm
|
|
Packit |
549fdc |
of the Digital Signature Standard (DSS).
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item ECDHE_@-ECDSA @tab
|
|
Packit |
549fdc |
The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
|
|
Packit |
549fdc |
curve Diffie-Hellman parameters which are sent to the peer. The
|
|
Packit |
549fdc |
certificate must contain ECDSA parameters (i.e., EC and marked for signing)
|
|
Packit |
549fdc |
to use this key exchange algorithm.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
@caption{Supported key exchange algorithms.}
|
|
Packit |
549fdc |
@end float
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@menu
|
|
Packit |
549fdc |
* X.509 certificates::
|
|
Packit |
549fdc |
* OpenPGP certificates::
|
|
Packit |
549fdc |
* Advanced certificate verification::
|
|
Packit |
549fdc |
* Digital signatures::
|
|
Packit |
549fdc |
@end menu
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node X.509 certificates
|
|
Packit |
549fdc |
@subsection @acronym{X.509} certificates
|
|
Packit |
549fdc |
@cindex X.509 certificates
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The @acronym{X.509} protocols rely on a hierarchical trust model. In
|
|
Packit |
549fdc |
this trust model Certification Authorities (CAs) are used to certify
|
|
Packit |
549fdc |
entities. Usually more than one certification authorities exist, and
|
|
Packit |
549fdc |
certification authorities may certify other authorities to issue
|
|
Packit |
549fdc |
certificates as well, following a hierarchical model.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@float Figure,fig-x509
|
|
Packit |
549fdc |
@image{gnutls-x509,7cm}
|
|
Packit |
549fdc |
@caption{An example of the X.509 hierarchical trust model.}
|
|
Packit |
549fdc |
@end float
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
One needs to trust one or more CAs for his secure communications. In
|
|
Packit |
549fdc |
that case only the certificates issued by the trusted authorities are
|
|
Packit |
549fdc |
acceptable. The framework is illustrated on @ref{fig-x509}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@menu
|
|
Packit |
549fdc |
* X.509 certificate structure::
|
|
Packit |
549fdc |
* Importing an X.509 certificate::
|
|
Packit |
549fdc |
* X.509 certificate names::
|
|
Packit |
549fdc |
* X.509 distinguished names::
|
|
Packit |
549fdc |
* X.509 extensions::
|
|
Packit |
549fdc |
* X.509 public and private keys::
|
|
Packit |
549fdc |
* Verifying X.509 certificate paths::
|
|
Packit |
549fdc |
* Verifying a certificate in the context of TLS session::
|
|
Packit |
549fdc |
* Verification using PKCS11::
|
|
Packit |
549fdc |
@end menu
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node X.509 certificate structure
|
|
Packit |
549fdc |
@subsubsection @acronym{X.509} certificate structure
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
An @acronym{X.509} certificate usually contains information about the
|
|
Packit |
549fdc |
certificate holder, the signer, a unique serial number, expiration
|
|
Packit |
549fdc |
dates and some other fields @xcite{PKIX} as shown in @ref{tab:x509}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@float Table,tab:x509
|
|
Packit |
549fdc |
@multitable @columnfractions .2 .7
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@headitem Field @tab Description
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item version @tab
|
|
Packit |
549fdc |
The field that indicates the version of the certificate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item serialNumber @tab
|
|
Packit |
549fdc |
This field holds a unique serial number per certificate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item signature @tab
|
|
Packit |
549fdc |
The issuing authority's signature.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item issuer @tab
|
|
Packit |
549fdc |
Holds the issuer's distinguished name.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item validity @tab
|
|
Packit |
549fdc |
The activation and expiration dates.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item subject @tab
|
|
Packit |
549fdc |
The subject's distinguished name of the certificate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item extensions @tab
|
|
Packit |
549fdc |
The extensions are fields only present in version 3 certificates.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
@caption{X.509 certificate fields.}
|
|
Packit |
549fdc |
@end float
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The certificate's @emph{subject or issuer name} is not just a single
|
|
Packit |
549fdc |
string. It is a Distinguished name and in the @acronym{ASN.1}
|
|
Packit |
549fdc |
notation is a sequence of several object identifiers with their corresponding
|
|
Packit |
549fdc |
values. Some of available OIDs to be used in an @acronym{X.509}
|
|
Packit |
549fdc |
distinguished name are defined in @file{gnutls/x509.h}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The @emph{Version} field in a certificate has values either 1 or 3 for
|
|
Packit |
549fdc |
version 3 certificates. Version 1 certificates do not support the
|
|
Packit |
549fdc |
extensions field so it is not possible to distinguish a CA from a
|
|
Packit |
549fdc |
person, thus their usage should be avoided.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The @emph{validity} dates are there to indicate the date that the
|
|
Packit |
549fdc |
specific certificate was activated and the date the certificate's key
|
|
Packit |
549fdc |
would be considered invalid.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
In @acronym{GnuTLS} the @acronym{X.509} certificate structures are
|
|
Packit |
549fdc |
handled using the @code{gnutls_x509_crt_t} type and the corresponding
|
|
Packit |
549fdc |
private keys with the @code{gnutls_x509_privkey_t} type. All the
|
|
Packit |
549fdc |
available functions for @acronym{X.509} certificate handling have
|
|
Packit |
549fdc |
their prototypes in @file{gnutls/x509.h}. An example program to
|
|
Packit |
549fdc |
demonstrate the @acronym{X.509} parsing capabilities can be found in
|
|
Packit |
549fdc |
@ref{ex-x509-info}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Importing an X.509 certificate
|
|
Packit |
549fdc |
@subsubsection Importing an X.509 certificate
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The certificate structure should be initialized using @funcref{gnutls_x509_crt_init}, and
|
|
Packit |
549fdc |
a certificate structure can be imported using @funcref{gnutls_x509_crt_import}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncC{gnutls_x509_crt_init,gnutls_x509_crt_import,gnutls_x509_crt_deinit}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
In several functions an array of certificates is required. To assist in initialization
|
|
Packit |
549fdc |
and import the following two functions are provided.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncB{gnutls_x509_crt_list_import,gnutls_x509_crt_list_import2}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
In all cases after use a certificate must be deinitialized using @funcref{gnutls_x509_crt_deinit}.
|
|
Packit |
549fdc |
Note that although the functions above apply to @code{gnutls_x509_crt_t} structure, similar functions
|
|
Packit |
549fdc |
exist for the CRL structure @code{gnutls_x509_crl_t}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node X.509 certificate names
|
|
Packit |
549fdc |
@subsubsection X.509 certificate names
|
|
Packit |
549fdc |
@cindex X.509 certificate name
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
X.509 certificates allow for multiple names and types of names to be specified.
|
|
Packit |
549fdc |
CA certificates often rely on X.509 distinguished names (see @ref{X.509 distinguished names})
|
|
Packit |
549fdc |
for unique identification, while end-user and server certificates rely on the
|
|
Packit |
549fdc |
'subject alternative names'. The subject alternative names provide a typed name, e.g.,
|
|
Packit |
549fdc |
a DNS name, or an email address, which identifies the owner of the certificate.
|
|
Packit |
549fdc |
The following functions provide access to that names.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncB{gnutls_x509_crt_get_subject_alt_name2,gnutls_x509_crt_set_subject_alt_name}
|
|
Packit |
549fdc |
@showfuncC{gnutls_subject_alt_names_init,gnutls_subject_alt_names_get,gnutls_subject_alt_names_set}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Note however, that server certificates often used the Common Name (CN), part of the
|
|
Packit |
549fdc |
certificate DistinguishedName to place a single DNS address. That practice is discouraged
|
|
Packit |
549fdc |
(see @xcite{RFC6125}), because only a single address can be specified, and the CN field is
|
|
Packit |
549fdc |
free-form making matching ambiguous.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node X.509 distinguished names
|
|
Packit |
549fdc |
@subsubsection X.509 distinguished names
|
|
Packit |
549fdc |
@cindex X.509 distinguished name
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The ``subject'' of an X.509 certificate is not described by
|
|
Packit |
549fdc |
a single name, but rather with a distinguished name. This in
|
|
Packit |
549fdc |
X.509 terminology is a list of strings each associated an object
|
|
Packit |
549fdc |
identifier. To make things simple GnuTLS provides @funcref{gnutls_x509_crt_get_dn2}
|
|
Packit |
549fdc |
which follows the rules in @xcite{RFC4514} and returns a single
|
|
Packit |
549fdc |
string. Access to each string by individual object identifiers
|
|
Packit |
549fdc |
can be accessed using @funcref{gnutls_x509_crt_get_dn_by_oid}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_crt_get_dn2}
|
|
Packit |
549fdc |
@showfuncC{gnutls_x509_crt_get_dn,gnutls_x509_crt_get_dn_by_oid,gnutls_x509_crt_get_dn_oid}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Similar functions exist to access the distinguished name
|
|
Packit |
549fdc |
of the issuer of the certificate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncE{gnutls_x509_crt_get_issuer_dn,gnutls_x509_crt_get_issuer_dn2,gnutls_x509_crt_get_issuer_dn_by_oid,gnutls_x509_crt_get_issuer_dn_oid,gnutls_x509_crt_get_issuer}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The more powerful @funcref{gnutls_x509_crt_get_subject} and
|
|
Packit |
549fdc |
@funcref{gnutls_x509_dn_get_rdn_ava} provide efficient but low-level access
|
|
Packit |
549fdc |
to the contents of the distinguished name structure.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncB{gnutls_x509_crt_get_subject,gnutls_x509_crt_get_issuer}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_dn_get_rdn_ava}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node X.509 extensions
|
|
Packit |
549fdc |
@subsubsection X.509 extensions
|
|
Packit |
549fdc |
@cindex X.509 extensions
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
X.509 version 3 certificates include a list of extensions that can
|
|
Packit |
549fdc |
be used to obtain additional information on the subject or the issuer
|
|
Packit |
549fdc |
of the certificate. Those may be e-mail addresses, flags that indicate whether the
|
|
Packit |
549fdc |
belongs to a CA etc. All the supported @acronym{X.509} version 3
|
|
Packit |
549fdc |
extensions are shown in @ref{tab:x509-ext}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The certificate extensions access is split into two parts. The first
|
|
Packit |
549fdc |
requires to retrieve the extension, and the second is the parsing part.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
To enumerate and retrieve the DER-encoded extension data available in a certificate the following
|
|
Packit |
549fdc |
two functions are available.
|
|
Packit |
549fdc |
@showfuncC{gnutls_x509_crt_get_extension_info,gnutls_x509_crt_get_extension_data2,gnutls_x509_crt_get_extension_by_oid2}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
After a supported DER-encoded extension is retrieved it can be parsed using the APIs in @code{x509-ext.h}.
|
|
Packit |
549fdc |
Complex extensions may require initializing an intermediate structure that holds the
|
|
Packit |
549fdc |
parsed extension data. Examples of simple parsing functions are shown below.
|
|
Packit |
549fdc |
@showfuncD{gnutls_x509_ext_import_basic_constraints,gnutls_x509_ext_export_basic_constraints,gnutls_x509_ext_import_key_usage,gnutls_x509_ext_export_key_usage}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
More complex extensions, such as Name Constraints, require an intermediate structure, in that
|
|
Packit |
549fdc |
case @code{gnutls_x509_name_constraints_t} to be initialized in order to store the parsed
|
|
Packit |
549fdc |
extension data.
|
|
Packit |
549fdc |
@showfuncB{gnutls_x509_ext_import_name_constraints,gnutls_x509_ext_export_name_constraints}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
After the name constraints are extracted in the structure, the following functions
|
|
Packit |
549fdc |
can be used to access them.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncD{gnutls_x509_name_constraints_get_permitted,gnutls_x509_name_constraints_get_excluded,gnutls_x509_name_constraints_add_permitted,gnutls_x509_name_constraints_add_excluded}
|
|
Packit |
549fdc |
@showfuncB{gnutls_x509_name_constraints_check,gnutls_x509_name_constraints_check_crt}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Other utility functions are listed below.
|
|
Packit |
549fdc |
@showfuncB{gnutls_x509_name_constraints_init,gnutls_x509_name_constraints_deinit}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Similar functions exist for all of the other supported extensions, listed in @ref{tab:x509-ext}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@float Table,tab:x509-ext
|
|
Packit |
549fdc |
@multitable @columnfractions .3 .2 .4
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@headitem Extension @tab OID @tab Description
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Subject key id @tab 2.5.29.14 @tab
|
|
Packit |
549fdc |
An identifier of the key of the subject.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Key usage @tab 2.5.29.15 @tab
|
|
Packit |
549fdc |
Constraints the key's usage of the certificate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Private key usage period @tab 2.5.29.16 @tab
|
|
Packit |
549fdc |
Constraints the validity time of the private key.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Subject alternative name @tab 2.5.29.17 @tab
|
|
Packit |
549fdc |
Alternative names to subject's distinguished name.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Issuer alternative name @tab 2.5.29.18 @tab
|
|
Packit |
549fdc |
Alternative names to the issuer's distinguished name.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Basic constraints @tab 2.5.29.19 @tab
|
|
Packit |
549fdc |
Indicates whether this is a CA certificate or not, and specify the
|
|
Packit |
549fdc |
maximum path lengths of certificate chains.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Name constraints @tab 2.5.29.30 @tab
|
|
Packit |
549fdc |
A field in CA certificates that restricts the scope of the name of
|
|
Packit |
549fdc |
issued certificates.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item CRL distribution points @tab 2.5.29.31 @tab
|
|
Packit |
549fdc |
This extension is set by the CA, in order to inform about the
|
|
Packit |
549fdc |
location of issued Certificate Revocation Lists.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Certificate policy @tab 2.5.29.32 @tab
|
|
Packit |
549fdc |
This extension is set to indicate the certificate policy as object
|
|
Packit |
549fdc |
identifier and may contain a descriptive string or URL.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Extended key usage @tab 2.5.29.54 @tab
|
|
Packit |
549fdc |
Inhibit any policy extension. Constraints the any policy OID
|
|
Packit |
549fdc |
(@code{GNUTLS_X509_OID_POLICY_ANY}) use in the policy extension.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Authority key identifier @tab 2.5.29.35 @tab
|
|
Packit |
549fdc |
An identifier of the key of the issuer of the certificate. That is
|
|
Packit |
549fdc |
used to distinguish between different keys of the same issuer.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Extended key usage @tab 2.5.29.37 @tab
|
|
Packit |
549fdc |
Constraints the purpose of the certificate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Authority information access @tab 1.3.6.1.5.5.7.1.1 @tab
|
|
Packit |
549fdc |
Information on services by the issuer of the certificate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Proxy Certification Information @tab 1.3.6.1.5.5.7.1.14 @tab
|
|
Packit |
549fdc |
Proxy Certificates includes this extension that contains the OID of
|
|
Packit |
549fdc |
the proxy policy language used, and can specify limits on the maximum
|
|
Packit |
549fdc |
lengths of proxy chains. Proxy Certificates are specified in
|
|
Packit |
549fdc |
@xcite{RFC3820}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
@caption{Supported X.509 certificate extensions.}
|
|
Packit |
549fdc |
@end float
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Note, that there are also direct APIs to access extensions that may
|
|
Packit |
549fdc |
be simpler to use for non-complex extensions. They are available
|
|
Packit |
549fdc |
in @code{x509.h} and some examples are listed below.
|
|
Packit |
549fdc |
@showfuncD{gnutls_x509_crt_get_basic_constraints,gnutls_x509_crt_set_basic_constraints,gnutls_x509_crt_get_key_usage,gnutls_x509_crt_set_key_usage}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node X.509 public and private keys
|
|
Packit |
549fdc |
@subsubsection Accessing public and private keys
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Each X.509 certificate contains a public key that corresponds to a private key. To
|
|
Packit |
549fdc |
get a unique identifier of the public key the @funcref{gnutls_x509_crt_get_key_id}
|
|
Packit |
549fdc |
function is provided. To export the public key or its parameters you may need
|
|
Packit |
549fdc |
to convert the X.509 structure to a @code{gnutls_pubkey_t}. See
|
|
Packit |
549fdc |
@ref{Abstract public keys} for more information.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_crt_get_key_id}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The private key parameters may be directly accessed by using one of the following functions.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncE{gnutls_x509_privkey_get_pk_algorithm2,gnutls_x509_privkey_export_rsa_raw2,gnutls_x509_privkey_export_ecc_raw,gnutls_x509_privkey_export_dsa_raw,gnutls_x509_privkey_get_key_id}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Verifying X.509 certificate paths
|
|
Packit |
549fdc |
@subsubsection Verifying @acronym{X.509} certificate paths
|
|
Packit |
549fdc |
@cindex verifying certificate paths
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Verifying certificate paths is important in @acronym{X.509}
|
|
Packit |
549fdc |
authentication. For this purpose the following functions are
|
|
Packit |
549fdc |
provided.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_add_cas}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_add_named_crt}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_add_crls}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_verify_crt}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_verify_crt2}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_verify_named_crt}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_add_trust_file}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_add_trust_mem}
|
|
Packit |
549fdc |
@showfuncdesc{gnutls_x509_trust_list_add_system_trust}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The verification function will verify a given certificate chain against a list of certificate
|
|
Packit |
549fdc |
authorities and certificate revocation lists, and output
|
|
Packit |
549fdc |
a bit-wise OR of elements of the @code{gnutls_@-certificate_@-status_t}
|
|
Packit |
549fdc |
enumeration shown in @ref{gnutls_certificate_status_t}. The @code{GNUTLS_@-CERT_@-INVALID} flag
|
|
Packit |
549fdc |
is always set on a verification error and more detailed flags will also be set when appropriate.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showenumdesc{gnutls_certificate_status_t,The @code{gnutls_@-certificate_@-status_t} enumeration.}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
An example of certificate verification is shown in @ref{ex-verify2}.
|
|
Packit |
549fdc |
It is also possible to have a set of certificates that
|
|
Packit |
549fdc |
are trusted for a particular server but not to authorize other certificates.
|
|
Packit |
549fdc |
This purpose is served by the functions @funcref{gnutls_x509_trust_list_add_named_crt} and @funcref{gnutls_x509_trust_list_verify_named_crt}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Verifying a certificate in the context of TLS session
|
|
Packit |
549fdc |
@subsubsection Verifying a certificate in the context of TLS session
|
|
Packit |
549fdc |
@cindex verifying certificate paths
|
|
Packit |
549fdc |
@tindex gnutls_certificate_verify_flags
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
When operating in the context of a TLS session, the trusted certificate
|
|
Packit |
549fdc |
authority list may also be set using:
|
|
Packit |
549fdc |
@showfuncD{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_trust_dir,gnutls_certificate_set_x509_crl_file,gnutls_certificate_set_x509_system_trust}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
These functions allow the specification of the trusted certificate authorities, either
|
|
Packit |
549fdc |
via a file, a directory or use the system-specified certificate authorities.
|
|
Packit |
549fdc |
Unless the authorities are application specific, it is generally recommended
|
|
Packit |
549fdc |
to use the system trust storage (see @funcref{gnutls_certificate_set_x509_system_trust}).
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Unlike the previous section it is not required to setup a trusted list, and there
|
|
Packit |
549fdc |
are two approaches to verify the peer's certificate and identity.
|
|
Packit |
549fdc |
The recommended in GnuTLS 3.5.0 and later is via the @funcref{gnutls_session_set_verify_cert},
|
|
Packit |
549fdc |
but for older GnuTLS versions you may use an explicit callback set via
|
|
Packit |
549fdc |
@funcref{gnutls_certificate_set_verify_function} and then utilize
|
|
Packit |
549fdc |
@funcref{gnutls_certificate_verify_peers3} for verification.
|
|
Packit |
549fdc |
The reported verification status is identical to the verification functions described
|
|
Packit |
549fdc |
in the previous section.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Note that in certain cases it is required to check the marked purpose of
|
|
Packit |
549fdc |
the end certificate (e.g. @code{GNUTLS_KP_TLS_WWW_SERVER}); in these cases
|
|
Packit |
549fdc |
the more advanced @funcref{gnutls_session_set_verify_cert2} and
|
|
Packit |
549fdc |
@funcref{gnutls_certificate_verify_peers} should be used instead.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
There is also the possibility to pass some input to the verification
|
|
Packit |
549fdc |
functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt2} the
|
|
Packit |
549fdc |
flags are passed directly, but for
|
|
Packit |
549fdc |
@funcref{gnutls_certificate_verify_peers3}, the flags are set using
|
|
Packit |
549fdc |
@funcref{gnutls_certificate_set_verify_flags}. All the available
|
|
Packit |
549fdc |
flags are part of the enumeration
|
|
Packit |
549fdc |
@code{gnutls_@-certificate_@-verify_@-flags} shown in @ref{gnutls_certificate_verify_flags}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@showenumdesc{gnutls_certificate_verify_flags,The @code{gnutls_@-certificate_@-verify_@-flags} enumeration.}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Verification using PKCS11
|
|
Packit |
549fdc |
@subsubsection Verifying a certificate using PKCS #11
|
|
Packit |
549fdc |
@cindex verifying certificate with pkcs11
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Some systems provide a system wide trusted certificate storage accessible using
|
|
Packit |
549fdc |
the PKCS #11 API. That is, the trusted certificates are queried and accessed using the
|
|
Packit |
549fdc |
PKCS #11 API, and trusted certificate properties, such as purpose, are marked using
|
|
Packit |
549fdc |
attached extensions. One example is the p11-kit trust module@footnote{see @url{http://p11-glue.freedesktop.org/trust-module.html}.}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
These special PKCS #11 modules can be used for GnuTLS certificate verification if marked as trust
|
|
Packit |
549fdc |
policy modules, i.e., with @code{trust-policy: yes} in the p11-kit module file.
|
|
Packit |
549fdc |
The way to use them is by specifying to the file verification function (e.g., @funcref{gnutls_certificate_set_x509_trust_file}),
|
|
Packit |
549fdc |
a pkcs11 URL, or simply @code{pkcs11:} to use all the marked with trust policy modules.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The trust modules of p11-kit assign a purpose to trusted authorities using the extended
|
|
Packit |
549fdc |
key usage object identifiers. The common purposes are shown in @ref{tab:purposes}. Note
|
|
Packit |
549fdc |
that typically according to @xcite{RFC5280} the extended key usage object identifiers apply to end certificates. Their
|
|
Packit |
549fdc |
application to CA certificates is an extension used by the trust modules.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@float Table,tab:purposes
|
|
Packit |
549fdc |
@multitable @columnfractions .2 .2 .6
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@headitem Purpose @tab OID @tab Description
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item GNUTLS_KP_TLS_WWW_SERVER @tab
|
|
Packit |
549fdc |
1.3.6.1.5.5.7.3.1 @tab
|
|
Packit |
549fdc |
The certificate is to be used for TLS WWW authentication. When in a CA certificate, it
|
|
Packit |
549fdc |
indicates that the CA is allowed to sign certificates for TLS WWW authentication.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item GNUTLS_KP_TLS_WWW_CLIENT @tab
|
|
Packit |
549fdc |
1.3.6.1.5.5.7.3.2 @tab
|
|
Packit |
549fdc |
The certificate is to be used for TLS WWW client authentication. When in a CA certificate, it
|
|
Packit |
549fdc |
indicates that the CA is allowed to sign certificates for TLS WWW client authentication.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item GNUTLS_KP_CODE_SIGNING @tab
|
|
Packit |
549fdc |
1.3.6.1.5.5.7.3.3 @tab
|
|
Packit |
549fdc |
The certificate is to be used for code signing. When in a CA certificate, it
|
|
Packit |
549fdc |
indicates that the CA is allowed to sign certificates for code signing.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item GNUTLS_KP_EMAIL_PROTECTION @tab
|
|
Packit |
549fdc |
1.3.6.1.5.5.7.3.4 @tab
|
|
Packit |
549fdc |
The certificate is to be used for email protection. When in a CA certificate, it
|
|
Packit |
549fdc |
indicates that the CA is allowed to sign certificates for email users.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item GNUTLS_KP_OCSP_SIGNING @tab
|
|
Packit |
549fdc |
1.3.6.1.5.5.7.3.9 @tab
|
|
Packit |
549fdc |
The certificate is to be used for signing OCSP responses. When in a CA certificate, it
|
|
Packit |
549fdc |
indicates that the CA is allowed to sign certificates which sign OCSP reponses.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item GNUTLS_KP_ANY @tab
|
|
Packit |
549fdc |
2.5.29.37.0 @tab
|
|
Packit |
549fdc |
The certificate is to be used for any purpose. When in a CA certificate, it
|
|
Packit |
549fdc |
indicates that the CA is allowed to sign any kind of certificates.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@end multitable
|
|
Packit |
549fdc |
@caption{Key purpose object identifiers.}
|
|
Packit |
549fdc |
@end float
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
With such modules, it is recommended to use the verification functions @funcref{gnutls_x509_trust_list_verify_crt2},
|
|
Packit |
549fdc |
or @funcref{gnutls_certificate_verify_peers}, which allow to explicitly specify the key purpose. The
|
|
Packit |
549fdc |
other verification functions which do not allow setting a purpose, would operate as if
|
|
Packit |
549fdc |
@code{GNUTLS_KP_TLS_WWW_SERVER} was requested from the trusted authorities.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node OpenPGP certificates
|
|
Packit |
549fdc |
@subsection @acronym{OpenPGP} certificates
|
|
Packit |
549fdc |
@cindex OpenPGP certificates
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Previous versions of GnuTLS supported limited @acronym{OpenPGP} key
|
|
Packit |
549fdc |
authentication. That functionality has been deprecated and is no longer
|
|
Packit |
549fdc |
made available. The reason is that, supporting alternative authentication
|
|
Packit |
549fdc |
methods, when X.509 and PKIX were new on the Internet and not well established, seemed like a
|
|
Packit |
549fdc |
good idea, in today's Internet X.509 is unquestionably the main
|
|
Packit |
549fdc |
container for certificates. As such supporting more options with no clear
|
|
Packit |
549fdc |
use-cases, is a distraction that consumes considerable resources for
|
|
Packit |
549fdc |
improving and testing the library. For that we have decided to drop
|
|
Packit |
549fdc |
this functionality completely in 3.6.0.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Advanced certificate verification
|
|
Packit |
549fdc |
@subsection Advanced certificate verification
|
|
Packit |
549fdc |
@cindex Certificate verification
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The verification of X.509 certificates in the HTTPS and other Internet protocols is typically
|
|
Packit |
549fdc |
done by loading a trusted list of commercial Certificate Authorities
|
|
Packit |
549fdc |
(see @funcref{gnutls_certificate_set_x509_system_trust}), and using them as trusted anchors.
|
|
Packit |
549fdc |
However, there are several examples (eg. the Diginotar incident) where one of these
|
|
Packit |
549fdc |
authorities was compromised. This risk can be mitigated by using in addition to CA certificate verification,
|
|
Packit |
549fdc |
other verification methods. In this section we list the available in GnuTLS methods.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@menu
|
|
Packit |
549fdc |
* Verifying a certificate using trust on first use authentication::
|
|
Packit |
549fdc |
* Verifying a certificate using DANE::
|
|
Packit |
549fdc |
@end menu
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Verifying a certificate using trust on first use authentication
|
|
Packit |
549fdc |
@subsubsection Verifying a certificate using trust on first use authentication
|
|
Packit |
549fdc |
@cindex verifying certificate paths
|
|
Packit |
549fdc |
@cindex SSH-style authentication
|
|
Packit |
549fdc |
@cindex Trust on first use
|
|
Packit |
549fdc |
@cindex Key pinning
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
It is possible to use a trust on first use (TOFU) authentication
|
|
Packit |
549fdc |
method in GnuTLS. That is the concept used by the SSH programs, where the
|
|
Packit |
549fdc |
public key of the peer is not verified, or verified in an out-of-bound way,
|
|
Packit |
549fdc |
but subsequent connections to the same peer require the public key to
|
|
Packit |
549fdc |
remain the same. Such a system in combination with the typical CA
|
|
Packit |
549fdc |
verification of a certificate, and OCSP revocation checks,
|
|
Packit |
549fdc |
can help to provide multiple factor verification, where a single point of
|
|
Packit |
549fdc |
failure is not enough to compromise the system. For example a server compromise
|
|
Packit |
549fdc |
may be detected using OCSP, and a CA compromise can be detected using
|
|
Packit |
549fdc |
the trust on first use method.
|
|
Packit |
549fdc |
Such a hybrid system with X.509 and trust on first use authentication is
|
|
Packit |
549fdc |
shown in @ref{Simple client example with SSH-style certificate verification}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
See @ref{Certificate verification} on how to use the available functionality.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Verifying a certificate using DANE
|
|
Packit |
549fdc |
@subsubsection Verifying a certificate using DANE (DNSSEC)
|
|
Packit |
549fdc |
@cindex verifying certificate paths
|
|
Packit |
549fdc |
@cindex DANE
|
|
Packit |
549fdc |
@cindex DNSSEC
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The DANE protocol is a protocol that can be used to verify TLS certificates
|
|
Packit |
549fdc |
using the DNS (or better DNSSEC) protocols. The DNS security extensions (DNSSEC)
|
|
Packit |
549fdc |
provide an alternative public key infrastructure to the commercial CAs that
|
|
Packit |
549fdc |
are typically used to sign TLS certificates. The DANE protocol takes advantage
|
|
Packit |
549fdc |
of the DNSSEC infrastructure to verify TLS certificates. This can be
|
|
Packit |
549fdc |
in addition to the verification by CA infrastructure or
|
|
Packit |
549fdc |
may even replace it where DNSSEC is fully deployed. Note however, that DNSSEC deployment is
|
|
Packit |
549fdc |
fairly new and it would be better to use it as an additional verification
|
|
Packit |
549fdc |
method rather than the only one.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The DANE functionality is provided by the @code{libgnutls-dane} library that is shipped
|
|
Packit |
549fdc |
with GnuTLS and the function prototypes are in @code{gnutls/dane.h}.
|
|
Packit |
549fdc |
See @ref{Certificate verification} for information on how to use the library.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Note however, that the DANE RFC mandates the verification methods
|
|
Packit |
549fdc |
one should use in addition to the validation via DNSSEC TLSA entries.
|
|
Packit |
549fdc |
GnuTLS doesn't follow that RFC requirement, and the term DANE verification
|
|
Packit |
549fdc |
in this manual refers to the TLSA entry verification. In GnuTLS any
|
|
Packit |
549fdc |
other verification methods can be used (e.g., PKIX or TOFU) on top of
|
|
Packit |
549fdc |
DANE.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Digital signatures
|
|
Packit |
549fdc |
@subsection Digital signatures
|
|
Packit |
549fdc |
@cindex digital signatures
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
In this section we will provide some information about digital
|
|
Packit |
549fdc |
signatures, how they work, and give the rationale for disabling some
|
|
Packit |
549fdc |
of the algorithms used.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Digital signatures work by using somebody's secret key to sign some
|
|
Packit |
549fdc |
arbitrary data. Then anybody else could use the public key of that
|
|
Packit |
549fdc |
person to verify the signature. Since the data may be arbitrary it is
|
|
Packit |
549fdc |
not suitable input to a cryptographic digital signature algorithm. For
|
|
Packit |
549fdc |
this reason and also for performance cryptographic hash algorithms are
|
|
Packit |
549fdc |
used to preprocess the input to the signature algorithm. This works as
|
|
Packit |
549fdc |
long as it is difficult enough to generate two different messages with
|
|
Packit |
549fdc |
the same hash algorithm output. In that case the same signature could
|
|
Packit |
549fdc |
be used as a proof for both messages. Nobody wants to sign an innocent
|
|
Packit |
549fdc |
message of donating 1 euro to Greenpeace and find out that they
|
|
Packit |
549fdc |
donated 1.000.000 euros to Bad Inc.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
For a hash algorithm to be called cryptographic the following three
|
|
Packit |
549fdc |
requirements must hold:
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@enumerate
|
|
Packit |
549fdc |
@item Preimage resistance.
|
|
Packit |
549fdc |
That means the algorithm must be one way and given the output of the
|
|
Packit |
549fdc |
hash function @math{H(x)}, it is impossible to calculate @math{x}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item 2nd preimage resistance.
|
|
Packit |
549fdc |
That means that given a pair @math{x,y} with @math{y=H(x)} it is
|
|
Packit |
549fdc |
impossible to calculate an @math{x'} such that @math{y=H(x')}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@item Collision resistance.
|
|
Packit |
549fdc |
That means that it is impossible to calculate random @math{x} and
|
|
Packit |
549fdc |
@math{x'} such @math{H(x')=H(x)}.
|
|
Packit |
549fdc |
@end enumerate
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The last two requirements in the list are the most important in
|
|
Packit |
549fdc |
digital signatures. These protect against somebody who would like to
|
|
Packit |
549fdc |
generate two messages with the same hash output. When an algorithm is
|
|
Packit |
549fdc |
considered broken usually it means that the Collision resistance of
|
|
Packit |
549fdc |
the algorithm is less than brute force. Using the birthday paradox the
|
|
Packit |
549fdc |
brute force attack takes
|
|
Packit |
549fdc |
@iftex
|
|
Packit |
549fdc |
@math{2^{(\rm{hash\ size}) / 2}}
|
|
Packit |
549fdc |
@end iftex
|
|
Packit |
549fdc |
@ifnottex
|
|
Packit |
549fdc |
@math{2^{((hash size) / 2)}}
|
|
Packit |
549fdc |
@end ifnottex
|
|
Packit |
549fdc |
operations. Today colliding certificates using the MD5 hash algorithm
|
|
Packit |
549fdc |
have been generated as shown in @xcite{WEGER}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
There has been cryptographic results for the SHA-1 hash algorithms as
|
|
Packit |
549fdc |
well, although they are not yet critical. Before 2004, MD5 had a
|
|
Packit |
549fdc |
presumed collision strength of @math{2^{64}}, but it has been showed
|
|
Packit |
549fdc |
to have a collision strength well under @math{2^{50}}. As of November
|
|
Packit |
549fdc |
2005, it is believed that SHA-1's collision strength is around
|
|
Packit |
549fdc |
@math{2^{63}}. We consider this sufficiently hard so that we still
|
|
Packit |
549fdc |
support SHA-1. We anticipate that SHA-256/386/512 will be used in
|
|
Packit |
549fdc |
publicly-distributed certificates in the future. When @math{2^{63}}
|
|
Packit |
549fdc |
can be considered too weak compared to the computer power available
|
|
Packit |
549fdc |
sometime in the future, SHA-1 will be disabled as well. The collision
|
|
Packit |
549fdc |
attacks on SHA-1 may also get better, given the new interest in tools
|
|
Packit |
549fdc |
for creating them.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@subsubsection Trading security for interoperability
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
If you connect to a server and use GnuTLS' functions to verify the
|
|
Packit |
549fdc |
certificate chain, and get a @code{GNUTLS_CERT_INSECURE_ALGORITHM}
|
|
Packit |
549fdc |
validation error (see @ref{Verifying X.509 certificate paths}), it means
|
|
Packit |
549fdc |
that somewhere in the certificate chain there is a certificate signed
|
|
Packit |
549fdc |
using @code{RSA-MD2} or @code{RSA-MD5}. These two digital signature
|
|
Packit |
549fdc |
algorithms are considered broken, so GnuTLS fails verifying
|
|
Packit |
549fdc |
the certificate. In some situations, it may be useful to be
|
|
Packit |
549fdc |
able to verify the certificate chain anyway, assuming an attacker did
|
|
Packit |
549fdc |
not utilize the fact that these signatures algorithms are broken.
|
|
Packit |
549fdc |
This section will give help on how to achieve that.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
It is important to know that you do not have to enable any of
|
|
Packit |
549fdc |
the flags discussed here to be able to use trusted root CA
|
|
Packit |
549fdc |
certificates self-signed using @code{RSA-MD2} or @code{RSA-MD5}. The
|
|
Packit |
549fdc |
certificates in the trusted list are considered trusted irrespective
|
|
Packit |
549fdc |
of the signature.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
If you are using @funcref{gnutls_certificate_verify_peers3} to verify the
|
|
Packit |
549fdc |
certificate chain, you can call
|
|
Packit |
549fdc |
@funcref{gnutls_certificate_set_verify_flags} with the flags:
|
|
Packit |
549fdc |
@itemize
|
|
Packit |
549fdc |
@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2}
|
|
Packit |
549fdc |
@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5}
|
|
Packit |
549fdc |
@item @code{GNUTLS_VERIFY_ALLOW_SIGN_WITH_SHA1}
|
|
Packit |
549fdc |
@item @code{GNUTLS_VERIFY_ALLOW_BROKEN}
|
|
Packit |
549fdc |
@end itemize
|
|
Packit |
549fdc |
as in the following example:
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@example
|
|
Packit |
549fdc |
gnutls_certificate_set_verify_flags (x509cred,
|
|
Packit |
549fdc |
GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
|
|
Packit |
549fdc |
@end example
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This will signal the verifier algorithm to enable @code{RSA-MD5} when
|
|
Packit |
549fdc |
verifying the certificates.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
If you are using @funcref{gnutls_x509_crt_verify} or
|
|
Packit |
549fdc |
@funcref{gnutls_x509_crt_list_verify}, you can pass the
|
|
Packit |
549fdc |
@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the
|
|
Packit |
549fdc |
@code{flags} parameter.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
If you are using these flags, it may also be a good idea to warn the
|
|
Packit |
549fdc |
user when verification failure occur for this reason. The simplest is
|
|
Packit |
549fdc |
to not use the flags by default, and only fall back to using them
|
|
Packit |
549fdc |
after warning the user. If you wish to inspect the certificate chain
|
|
Packit |
549fdc |
yourself, you can use @funcref{gnutls_certificate_get_peers} to extract
|
|
Packit |
549fdc |
the raw server's certificate chain, @funcref{gnutls_x509_crt_list_import} to parse each of the certificates, and
|
|
Packit |
549fdc |
then @funcref{gnutls_x509_crt_get_signature_algorithm} to find out the
|
|
Packit |
549fdc |
signing algorithm used for each certificate. If any of the
|
|
Packit |
549fdc |
intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or
|
|
Packit |
549fdc |
@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning.
|