file2:: (gnutls_certificate_credentials_t RES, const char * CERTFILE, const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE, const char * PASS, unsigned int FLAGS)’
‘INT *note gnutls_certificate_set_x509_key_mem2:: (gnutls_certificate_credentials_t RES, const gnutls_datum_t * CERT, const gnutls_datum_t * KEY, gnutls_x509_crt_fmt_t TYPE, const char * PASS, unsigned int FLAGS)’
‘INT *note gnutls_certificate_set_x509_key:: (gnutls_certificate_credentials_t RES, gnutls_x509_crt_t * CERT_LIST, int CERT_LIST_SIZE, gnutls_x509_privkey_t KEY)’

It is recommended to use the higher level functions such as *note
gnutls_certificate_set_x509_key_file2:: which accept not only file names
but URLs that specify objects stored in token, or system certificates
and keys (see *note Application-specific keys::).  For these cases,
another important function is *note
gnutls_certificate_set_pin_function::, that allows setting a callback
function to retrieve a PIN if the input keys are protected by PIN.

 -- Function: void gnutls_certificate_set_pin_function
          (gnutls_certificate_credentials_t CRED, gnutls_pin_callback_t
          FN, void * USERDATA)
     CRED: is a ‘gnutls_certificate_credentials_t’ type.

     FN: A PIN callback

     USERDATA: Data to be passed in the callback

     This function will set a callback function to be used when required
     to access a protected object.  This function overrides any other
     global PIN functions.

     Note that this function must be called right after initialization
     to have effect.

     *Since:* 3.1.0

If the imported keys and certificates need to be accessed before any TLS
session is established, it is convenient to use *note
gnutls_certificate_set_key:: in combination with *note
gnutls_pcert_import_x509_raw:: and *note
gnutls_privkey_import_x509_raw::.

 -- Function: int gnutls_certificate_set_key
          (gnutls_certificate_credentials_t RES, const char ** NAMES,
          int NAMES_SIZE, gnutls_pcert_st * PCERT_LIST, int
          PCERT_LIST_SIZE, gnutls_privkey_t KEY)
     RES: is a ‘gnutls_certificate_credentials_t’ type.

     NAMES: is an array of DNS names belonging to the public-key (NULL
     if none)

     NAMES_SIZE: holds the size of the names list

     PCERT_LIST: contains a certificate list (chain) or raw public-key

     PCERT_LIST_SIZE: holds the size of the certificate list

     KEY: is a ‘gnutls_privkey_t’ key corresponding to the first
     public-key in pcert_list

     This function sets a public/private key pair in the
     gnutls_certificate_credentials_t type.  The given public key may be
     encapsulated in a certificate or can be given as a raw key.  This
     function may be called more than once, in case multiple key pairs
     exist for the server.  For clients that want to send more than
     their own end- entity certificate (e.g., also an intermediate CA
     cert), the full certificate chain must be provided in ‘pcert_list’
     .

     Note that the ‘key’ will become part of the credentials structure
     and must not be deallocated.  It will be automatically deallocated
     when the ‘res’ structure is deinitialized.

     If this function fails, the ‘res’ structure is at an undefined
     state and it must not be reused to load other keys or certificates.

     Note that, this function by default returns zero on success and a
     negative value on error.  Since 3.5.6, when the flag
     ‘GNUTLS_CERTIFICATE_API_V2’ is set using
     ‘gnutls_certificate_set_flags()’ it returns an index (greater or
     equal to zero).  That index can be used for other functions to
     refer to the added key-pair.

     Since GnuTLS 3.6.6 this function also handles raw public keys.

     *Returns:* On success this functions returns zero, and otherwise a
     negative value on error (see above for modifying that behavior).

     *Since:* 3.0

If multiple certificates are used with the functions above each client's
request will be served with the certificate that matches the requested
name (see *note Server name indication::).

As an alternative to loading from files or buffers, a callback may be
used for the server or the client to specify the certificate and the key
at the handshake time.  In that case a certificate should be selected
according the peer's signature algorithm preferences.  To get those
preferences use *note gnutls_sign_algorithm_get_requested::.  Both
functions are shown below.

‘VOID *note gnutls_certificate_set_retrieve_function:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function * FUNC)’
‘VOID *note gnutls_certificate_set_retrieve_function2:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function2 * FUNC)’
‘VOID *note gnutls_certificate_set_retrieve_function3:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function3 * FUNC)’
‘INT *note gnutls_sign_algorithm_get_requested:: (gnutls_session_t SESSION, size_t INDX, gnutls_sign_algorithm_t * ALGO)’

The functions above do not handle the requested server name
automatically.  A server would need to check the name requested by the
client using *note gnutls_server_name_get::, and serve the appropriate
certificate.  Note that some of these functions require the
‘gnutls_pcert_st’ structure to be filled in.  Helper functions to fill
in the structure are listed below.

typedef struct gnutls_pcert_st
{
  gnutls_pubkey_t pubkey;
  gnutls_datum_t cert;
  gnutls_certificate_type_t type;
} gnutls_pcert_st;

‘INT *note gnutls_pcert_import_x509:: (gnutls_pcert_st * PCERT, gnutls_x509_crt_t CRT, unsigned int FLAGS)’
‘INT *note gnutls_pcert_import_x509_raw:: (gnutls_pcert_st * PCERT, const gnutls_datum_t * CERT, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS)’
‘VOID *note gnutls_pcert_deinit:: (gnutls_pcert_st * PCERT)’

In a handshake, the negotiated cipher suite depends on the certificate's
parameters, so some key exchange methods might not be available with all
certificates.  GnuTLS will disable ciphersuites that are not compatible
with the key, or the enabled authentication methods.  For example keys
marked as sign-only, will not be able to access the plain RSA
ciphersuites, that require decryption.  It is not recommended to use RSA
keys for both signing and encryption.  If possible use a different key
for the ‘DHE-RSA’ which uses signing and ‘RSA’ that requires decryption.
All the key exchange methods shown in *note Table 4.1: tab:key-exchange.
are available in certificate authentication.

Client certificate authentication
.................................

If a certificate is to be requested from the client during the
handshake, the server will send a certificate request message.  This
behavior is controlled by *note gnutls_certificate_server_set_request::.
The request contains a list of the by the server accepted certificate
signers.  This list is constructed using the trusted certificate
authorities of the server.  In cases where the server supports a large
number of certificate authorities it makes sense not to advertise all of
the names to save bandwidth.  That can be controlled using the function
*note gnutls_certificate_send_x509_rdn_sequence::.  This however will
have the side-effect of not restricting the client to certificates
signed by server's acceptable signers.

 -- Function: void gnutls_certificate_server_set_request
          (gnutls_session_t SESSION, gnutls_certificate_request_t REQ)
     SESSION: is a ‘gnutls_session_t’ type.

     REQ: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE,
     GNUTLS_CERT_IGNORE

     This function specifies if we (in case of a server) are going to
     send a certificate request message to the client.  If ‘req’ is
     GNUTLS_CERT_REQUIRE then the server will return the
     ‘GNUTLS_E_NO_CERTIFICATE_FOUND’ error if the peer does not provide
     a certificate.  If you do not call this function then the client
     will not be asked to send a certificate.  Invoking the function
     with ‘req’ GNUTLS_CERT_IGNORE has the same effect.

 -- Function: void gnutls_certificate_send_x509_rdn_sequence
          (gnutls_session_t SESSION, int STATUS)
     SESSION: a ‘gnutls_session_t’ type.

     STATUS: is 0 or 1

     If status is non zero, this function will order gnutls not to send
     the rdnSequence in the certificate request message.  That is the
     server will not advertise its trusted CAs to the peer.  If status
     is zero then the default behaviour will take effect, which is to
     advertise the server's trusted CAs.

     This function has no effect in clients, and in authentication
     methods other than certificate with X.509 certificates.

On the client side, it needs to set its certificates on the credentials
structure, similarly to server side from a file, or via a callback.
Once the certificates are available in the credentials structure, the
client will send them if during the handshake the server requests a
certificate signed by the issuer of its CA.

In the case a single certificate is available and the server does not
specify a signer's list, then that certificate is always sent.  It is,
however possible, to send a certificate even when the advertised CA list
by the server contains CAs other than its signer.  That can be achieved
using the ‘GNUTLS_FORCE_CLIENT_CERT’ flag in *note gnutls_init::.

‘INT *note gnutls_certificate_set_x509_key_file:: (gnutls_certificate_credentials_t RES, const char * CERTFILE, const char * KEYFILE, gnutls_x509_crt_fmt_t TYPE)’
‘INT *note gnutls_certificate_set_x509_simple_pkcs12_file:: (gnutls_certificate_credentials_t RES, const char * PKCS12FILE, gnutls_x509_crt_fmt_t TYPE, const char * PASSWORD)’
‘VOID *note gnutls_certificate_set_retrieve_function2:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function2 * FUNC)’

Client or server certificate verification
.........................................

Certificate verification is possible by loading the trusted authorities
into the credentials structure by using the following functions,
applicable to X.509 certificates.  In modern systems it is recommended
to utilize *note gnutls_certificate_set_x509_system_trust:: which will
load the trusted authorities from the system store.

 -- Function: int gnutls_certificate_set_x509_system_trust
          (gnutls_certificate_credentials_t CRED)
     CRED: is a ‘gnutls_certificate_credentials_t’ type.

     This function adds the system's default trusted CAs in order to
     verify client or server certificates.

     In the case the system is currently unsupported
     ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ is returned.

     *Returns:* the number of certificates processed or a negative error
     code on error.

     *Since:* 3.0.20
‘INT *note gnutls_certificate_set_x509_trust_file:: (gnutls_certificate_credentials_t CRED, const char * CAFILE, gnutls_x509_crt_fmt_t TYPE)’
‘INT *note gnutls_certificate_set_x509_trust_dir:: (gnutls_certificate_credentials_t CRED, const char * CA_DIR, gnutls_x509_crt_fmt_t TYPE)’

The peer's certificate will be automatically verified if *note
gnutls_session_set_verify_cert:: is called prior to handshake.

Alternatively, one must set a callback function during the handshake
using *note gnutls_certificate_set_verify_function::, which will verify
the peer's certificate once received.  The verification should happen
using *note gnutls_certificate_verify_peers3:: within the callback.  It
will verify the certificate's signature and the owner of the
certificate.  That will provide a brief verification output.  If a
detailed output is required one should call *note
gnutls_certificate_get_peers:: to obtain the raw certificate of the peer
and verify it using the functions discussed in *note X.509
certificates::.

In both the automatic and the manual cases, the verification status
returned can be printed using *note
gnutls_certificate_verification_status_print::.

 -- Function: void gnutls_session_set_verify_cert (gnutls_session_t
          SESSION, const char * HOSTNAME, unsigned FLAGS)
     SESSION: is a gnutls session

     HOSTNAME: is the expected name of the peer; may be ‘NULL’

     FLAGS: flags for certificate verification -
     ‘gnutls_certificate_verify_flags’

     This function instructs GnuTLS to verify the peer's certificate
     using the provided hostname.  If the verification fails the
     handshake will also fail with
     ‘GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR’ .  In that case the
     verification result can be obtained using
     ‘gnutls_session_get_verify_cert_status()’ .

     The ‘hostname’ pointer provided must remain valid for the lifetime
     of the session.  More precisely it should be available during any
     subsequent handshakes.  If no hostname is provided, no hostname
     verification will be performed.  For a more advanced verification
     function check ‘gnutls_session_set_verify_cert2()’ .

     If ‘flags’ is provided which contain a profile, this function
     should be called after any session priority setting functions.

     The ‘gnutls_session_set_verify_cert()’ function is intended to be
     used by TLS clients to verify the server's certificate.

     *Since:* 3.4.6

‘INT *note gnutls_certificate_verify_peers3:: (gnutls_session_t SESSION, const char * HOSTNAME, unsigned int * STATUS)’
‘VOID *note gnutls_certificate_set_verify_function:: (gnutls_certificate_credentials_t CRED, gnutls_certificate_verify_function * FUNC)’

Note that when using raw public-keys verification will not work because
there is no corresponding certificate body belonging to the raw key that
can be verified.  In that case the *note
gnutls_certificate_verify_peers:: family of functions will return a
GNUTLS_E_INVALID_REQUEST error code.  For authenticating raw public-keys
one must use an out-of-band mechanism, e.g.  by comparing hashes or
using trust on first use (see *note Verifying a certificate using trust
on first use authentication::).