path: root/doc/abstract-api.texi

@subheading gnutls_certificate_set_key
@anchor{gnutls_certificate_set_key}
@deftypefun {int} {gnutls_certificate_set_key} (gnutls_certificate_credentials_t @var{res}, const char ** @var{names}, int @var{names_size}, gnutls_pcert_st * @var{pcert_list}, int @var{pcert_list_size}, gnutls_privkey_t @var{key})
@var{res}: is a @code{gnutls_certificate_credentials_t}  type.

@var{names}: is an array of DNS names belonging to the public-key (NULL if none)

@var{names_size}: holds the size of the names list

@var{pcert_list}: contains a certificate list (chain) or raw public-key

@var{pcert_list_size}: holds the size of the certificate list

@var{key}: is a @code{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  @code{pcert_list} .

Note that the  @code{key} will become part of the credentials structure and must
not be deallocated. It will be automatically deallocated when the  @code{res} structure
is deinitialized.

If this function fails, the  @code{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 @code{GNUTLS_CERTIFICATE_API_V2}  is set using @code{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.

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

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_certificate_set_retrieve_function2
@anchor{gnutls_certificate_set_retrieve_function2}
@deftypefun {void} {gnutls_certificate_set_retrieve_function2} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_retrieve_function2 * @var{func})
@var{cred}: is a @code{gnutls_certificate_credentials_t}  type.

@var{func}: is the callback function

This function sets a callback to be called in order to retrieve the
certificate to be used in the handshake. The callback will take control
only if a certificate is requested by the peer.

The callback's function prototype is:
int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs,
const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_pcert_st** pcert,
unsigned int *pcert_length, gnutls_privkey_t * pkey);

 @code{req_ca_dn} is only used in X.509 certificates.
Contains a list with the CA names that the server considers trusted.
This is a hint and typically the client should send a certificate that is signed
by one of these CAs. These names, when available, are DER encoded. To get a more
meaningful value use the function @code{gnutls_x509_rdn_get()} .

 @code{pk_algos} contains a list with server's acceptable public key algorithms.
The certificate returned should support the server's given algorithms.

 @code{pcert} should contain a single certificate and public key or a list of them.

 @code{pcert_length} is the size of the previous list.

 @code{pkey} is the private key.

If the callback function is provided then gnutls will call it, in the
handshake, after the certificate request message has been received.
All the provided by the callback values will not be released or
modified by gnutls.

In server side pk_algos and req_ca_dn are NULL.

The callback function should set the certificate list to be sent,
and return 0 on success. If no certificate was selected then the
number of certificates should be set to zero. The value (-1)
indicates error and the handshake will be terminated. If both certificates
are set in the credentials and a callback is available, the callback
takes predence.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_certificate_set_retrieve_function3
@anchor{gnutls_certificate_set_retrieve_function3}
@deftypefun {void} {gnutls_certificate_set_retrieve_function3} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_retrieve_function3 * @var{func})
@var{cred}: is a @code{gnutls_certificate_credentials_t}  type.

@var{func}: is the callback function

This function sets a callback to be called in order to retrieve the
certificate and OCSP responses to be used in the handshake.  @code{func} will
be called only if the peer requests a certificate either during handshake
or during post-handshake authentication.

The callback's function prototype is defined in `abstract.h':

int gnutls_certificate_retrieve_function3(
gnutls_session_t,
const struct gnutls_cert_retr_st *info,
gnutls_pcert_st **certs,
unsigned int *certs_length,
gnutls_ocsp_data_st **ocsp,
unsigned int *ocsp_length,
gnutls_privkey_t *privkey,
unsigned int *flags);

The info field of the callback contains:
 @code{req_ca_dn} which is a list with the CA names that the server considers trusted.
This is a hint and typically the client should send a certificate that is signed
by one of these CAs. These names, when available, are DER encoded. To get a more
meaningful value use the function @code{gnutls_x509_rdn_get()} .
 @code{pk_algos} contains a list with server's acceptable public key algorithms.
The certificate returned should support the server's given algorithms.

The callback should fill-in the following values:

 @code{certs} should contain an allocated list of certificates and public keys.
 @code{certs_length} is the size of the previous list.
 @code{ocsp} should contain an allocated list of OCSP responses.
 @code{ocsp_length} is the size of the previous list.
 @code{privkey} is the private key.

If flags in the callback are set to @code{GNUTLS_CERT_RETR_DEINIT_ALL}  then
all provided values must be allocated using @code{gnutls_malloc()} , and will
be released by gnutls; otherwise they will not be touched by gnutls.

The callback function should set the certificate and OCSP response
list to be sent, and return 0 on success. If no certificates are available,
the  @code{certs_length} and  @code{ocsp_length} should be set to zero. The return
value (-1) indicates error and the handshake will be terminated. If both
certificates are set in the credentials and a callback is available, the
callback takes predence.

Raw public-keys:
In case raw public-keys are negotiated as certificate type, certificates
that would normally hold the public-key material are not available. In that case,
 @code{certs} contains an allocated list with only the public key. Since there is no
certificate, there is also no certificate status. Therefore, OCSP information
should not be set.

@strong{Since:} 3.6.3
@end deftypefun

@subheading gnutls_pcert_deinit
@anchor{gnutls_pcert_deinit}
@deftypefun {void} {gnutls_pcert_deinit} (gnutls_pcert_st * @var{pcert})
@var{pcert}: The structure to be deinitialized

This function will deinitialize a pcert structure.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pcert_export_openpgp
@anchor{gnutls_pcert_export_openpgp}
@deftypefun {int} {gnutls_pcert_export_openpgp} (gnutls_pcert_st * @var{pcert}, gnutls_openpgp_crt_t * @var{crt})
@var{pcert}: The pcert structure.

@var{crt}: An initialized @code{gnutls_openpgp_crt_t} .

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_pcert_export_x509
@anchor{gnutls_pcert_export_x509}
@deftypefun {int} {gnutls_pcert_export_x509} (gnutls_pcert_st * @var{pcert}, gnutls_x509_crt_t * @var{crt})
@var{pcert}: The pcert structure.

@var{crt}: An initialized @code{gnutls_x509_crt_t} .

Converts the given @code{gnutls_pcert_t}  type into a @code{gnutls_x509_crt_t} .
This function only works if the type of  @code{pcert} is @code{GNUTLS_CRT_X509} .
When successful, the value written to  @code{crt} must be freed with
@code{gnutls_x509_crt_deinit()}  when no longer needed.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_pcert_import_openpgp
@anchor{gnutls_pcert_import_openpgp}
@deftypefun {int} {gnutls_pcert_import_openpgp} (gnutls_pcert_st * @var{pcert}, gnutls_openpgp_crt_t @var{crt}, unsigned int @var{flags})
@var{pcert}: The pcert structure

@var{crt}: The raw certificate to be imported

@var{flags}: zero for now

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pcert_import_openpgp_raw
@anchor{gnutls_pcert_import_openpgp_raw}
@deftypefun {int} {gnutls_pcert_import_openpgp_raw} (gnutls_pcert_st * @var{pcert}, const gnutls_datum_t * @var{cert}, gnutls_openpgp_crt_fmt_t         @var{format}, gnutls_openpgp_keyid_t @var{keyid}, unsigned int @var{flags})
@var{pcert}: The pcert structure

@var{cert}: The raw certificate to be imported

@var{format}: The format of the certificate

@var{keyid}: The key ID to use (NULL for the master key)

@var{flags}: zero for now

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pcert_import_rawpk
@anchor{gnutls_pcert_import_rawpk}
@deftypefun {int} {gnutls_pcert_import_rawpk} (gnutls_pcert_st* @var{pcert}, gnutls_pubkey_t @var{pubkey}, unsigned int @var{flags})
@var{pcert}: The pcert structure to import the data into.

@var{pubkey}: The raw public-key in @code{gnutls_pubkey_t}  format to be imported

@var{flags}: zero for now

This convenience function will import (i.e. convert) the given raw
public key  @code{pubkey} into a @code{gnutls_pcert_st}  structure. The structure
must be deinitialized afterwards using @code{gnutls_pcert_deinit()} . The
given  @code{pubkey} must not be deinitialized because it will be associated
with the given  @code{pcert} structure and will be deinitialized with it.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.6
@end deftypefun

@subheading gnutls_pcert_import_rawpk_raw
@anchor{gnutls_pcert_import_rawpk_raw}
@deftypefun {int} {gnutls_pcert_import_rawpk_raw} (gnutls_pcert_st* @var{pcert}, const gnutls_datum_t* @var{rawpubkey}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{key_usage}, unsigned int @var{flags})
@var{pcert}: The pcert structure to import the data into.

@var{rawpubkey}: The raw public-key in @code{gnutls_datum_t}  format to be imported.

@var{format}: The format of the raw public-key. DER or PEM.

@var{key_usage}: An ORed sequence of @code{GNUTLS_KEY_} * flags.

@var{flags}: zero for now

This convenience function will import (i.e. convert) the given raw
public key  @code{rawpubkey} into a @code{gnutls_pcert_st}  structure. The structure
must be deinitialized afterwards using @code{gnutls_pcert_deinit()} .
Note that the caller is responsible for freeing  @code{rawpubkey} . All necessary
values will be copied into  @code{pcert} .

Key usage (as defined by X.509 extension (2.5.29.15)) can be explicitly
set because there is no certificate structure around the key to define
this value. See for more info @code{gnutls_x509_crt_get_key_usage()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.6
@end deftypefun

@subheading gnutls_pcert_import_x509
@anchor{gnutls_pcert_import_x509}
@deftypefun {int} {gnutls_pcert_import_x509} (gnutls_pcert_st * @var{pcert}, gnutls_x509_crt_t @var{crt}, unsigned int @var{flags})
@var{pcert}: The pcert structure

@var{crt}: The certificate to be imported

@var{flags}: zero for now

This convenience function will import the given certificate to a
@code{gnutls_pcert_st}  structure. The structure must be deinitialized
afterwards using @code{gnutls_pcert_deinit()} ;

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pcert_import_x509_list
@anchor{gnutls_pcert_import_x509_list}
@deftypefun {int} {gnutls_pcert_import_x509_list} (gnutls_pcert_st * @var{pcert_list}, gnutls_x509_crt_t * @var{crt}, unsigned * @var{ncrt}, unsigned int @var{flags})
@var{pcert_list}: The structures to store the certificates; must not contain initialized @code{gnutls_pcert_st}  structures.

@var{crt}: The certificates to be imported

@var{ncrt}: The number of certificates in  @code{crt} ; will be updated if necessary

@var{flags}: zero or @code{GNUTLS_X509_CRT_LIST_SORT} 

This convenience function will import the given certificates to an
already allocated set of @code{gnutls_pcert_st}  structures. The structures must
be deinitialized afterwards using @code{gnutls_pcert_deinit()} .  @code{pcert_list} should contain space for at least  @code{ncrt} elements.

In the case @code{GNUTLS_X509_CRT_LIST_SORT}  is specified and that
function cannot sort the list, @code{GNUTLS_E_CERTIFICATE_LIST_UNSORTED} 
will be returned. Currently sorting can fail if the list size
exceeds an internal constraint (16).

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_pcert_import_x509_raw
@anchor{gnutls_pcert_import_x509_raw}
@deftypefun {int} {gnutls_pcert_import_x509_raw} (gnutls_pcert_st * @var{pcert}, const gnutls_datum_t * @var{cert}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags})
@var{pcert}: The pcert structure

@var{cert}: The raw certificate to be imported

@var{format}: The format of the certificate

@var{flags}: zero for now

This convenience function will import the given certificate to a
@code{gnutls_pcert_st}  structure. The structure must be deinitialized
afterwards using @code{gnutls_pcert_deinit()} ;

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pcert_list_import_x509_file
@anchor{gnutls_pcert_list_import_x509_file}
@deftypefun {int} {gnutls_pcert_list_import_x509_file} (gnutls_pcert_st * @var{pcert_list}, unsigned * @var{pcert_list_size}, const char * @var{file}, gnutls_x509_crt_fmt_t @var{format}, gnutls_pin_callback_t @var{pin_fn}, void * @var{pin_fn_userdata}, unsigned int @var{flags})
@var{pcert_list}: The structures to store the certificates; must not contain initialized @code{gnutls_pcert_st}  structures.

@var{pcert_list_size}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.

@var{file}: A file or supported URI with the certificates to load

@var{format}: @code{GNUTLS_X509_FMT_DER}  or @code{GNUTLS_X509_FMT_PEM}  if a file is given

@var{pin_fn}: a PIN callback if not globally set

@var{pin_fn_userdata}: parameter for the PIN callback

@var{flags}: zero or flags from @code{gnutls_certificate_import_flags} 

This convenience function will import a certificate chain from the given
file or supported URI to @code{gnutls_pcert_st}  structures. The structures
must be deinitialized afterwards using @code{gnutls_pcert_deinit()} .

This function will always return a sorted certificate chain.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value; if the  @code{pcert} list doesn't have enough space
@code{GNUTLS_E_SHORT_MEMORY_BUFFER}  will be returned.

@strong{Since:} 3.6.3
@end deftypefun

@subheading gnutls_pcert_list_import_x509_raw
@anchor{gnutls_pcert_list_import_x509_raw}
@deftypefun {int} {gnutls_pcert_list_import_x509_raw} (gnutls_pcert_st * @var{pcert_list}, unsigned int * @var{pcert_list_size}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags})
@var{pcert_list}: The structures to store the certificates; must not contain initialized @code{gnutls_pcert_st}  structures.

@var{pcert_list_size}: Initially must hold the maximum number of certs. It will be updated with the number of certs available.

@var{data}: The certificates.

@var{format}: One of DER or PEM.

@var{flags}: must be (0) or an OR'd sequence of gnutls_certificate_import_flags.

This function will import the provided DER or PEM encoded certificates to an
already allocated set of @code{gnutls_pcert_st}  structures. The structures must
be deinitialized afterwards using @code{gnutls_pcert_deinit()} .  @code{pcert_list} should contain space for at least  @code{pcert_list_size} elements.

If the Certificate is PEM encoded it should have a header of "X509
CERTIFICATE", or "CERTIFICATE".

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value; if the  @code{pcert} list doesn't have enough space
@code{GNUTLS_E_SHORT_MEMORY_BUFFER}  will be returned.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_privkey_decrypt_data
@anchor{gnutls_privkey_decrypt_data}
@deftypefun {int} {gnutls_privkey_decrypt_data} (gnutls_privkey_t @var{key}, unsigned int @var{flags}, const gnutls_datum_t * @var{ciphertext}, gnutls_datum_t * @var{plaintext})
@var{key}: Holds the key

@var{flags}: zero for now

@var{ciphertext}: holds the data to be decrypted

@var{plaintext}: will contain the decrypted data, allocated with @code{gnutls_malloc()} 

This function will decrypt the given data using the algorithm
supported by the private key.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_decrypt_data2
@anchor{gnutls_privkey_decrypt_data2}
@deftypefun {int} {gnutls_privkey_decrypt_data2} (gnutls_privkey_t @var{key}, unsigned int @var{flags}, const gnutls_datum_t * @var{ciphertext}, unsigned char * @var{plaintext}, size_t @var{plaintext_size})
@var{key}: Holds the key

@var{flags}: zero for now

@var{ciphertext}: holds the data to be decrypted

@var{plaintext}: a preallocated buffer that will be filled with the plaintext

@var{plaintext_size}: in/out size of the plaintext

This function will decrypt the given data using the algorithm
supported by the private key. Unlike with @code{gnutls_privkey_decrypt_data()} 
this function operates in constant time and constant memory access.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.5
@end deftypefun

@subheading gnutls_privkey_deinit
@anchor{gnutls_privkey_deinit}
@deftypefun {void} {gnutls_privkey_deinit} (gnutls_privkey_t @var{key})
@var{key}: The key to be deinitialized

This function will deinitialize a private key structure.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_export_dsa_raw
@anchor{gnutls_privkey_export_dsa_raw}
@deftypefun {int} {gnutls_privkey_export_dsa_raw} (gnutls_privkey_t @var{key}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{x})
@var{key}: Holds the public key

@var{p}: will hold the p

@var{q}: will hold the q

@var{g}: will hold the g

@var{y}: will hold the y

@var{x}: will hold the x

This function will export the DSA private key's parameters found
in the given structure. The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_privkey_export_dsa_raw2
@anchor{gnutls_privkey_export_dsa_raw2}
@deftypefun {int} {gnutls_privkey_export_dsa_raw2} (gnutls_privkey_t @var{key}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{x}, unsigned int @var{flags})
@var{key}: Holds the public key

@var{p}: will hold the p

@var{q}: will hold the q

@var{g}: will hold the g

@var{y}: will hold the y

@var{x}: will hold the x

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the DSA private key's parameters found
in the given structure. The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_export_ecc_raw
@anchor{gnutls_privkey_export_ecc_raw}
@deftypefun {int} {gnutls_privkey_export_ecc_raw} (gnutls_privkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{k})
@var{key}: Holds the public key

@var{curve}: will hold the curve

@var{x}: will hold the x-coordinate

@var{y}: will hold the y-coordinate

@var{k}: will hold the private key

This function will export the ECC private key's parameters found
in the given structure. The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

In EdDSA curves the  @code{y} parameter will be @code{NULL}  and the other parameters
will be in the native format for the curve.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_privkey_export_ecc_raw2
@anchor{gnutls_privkey_export_ecc_raw2}
@deftypefun {int} {gnutls_privkey_export_ecc_raw2} (gnutls_privkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{k}, unsigned int @var{flags})
@var{key}: Holds the public key

@var{curve}: will hold the curve

@var{x}: will hold the x-coordinate

@var{y}: will hold the y-coordinate

@var{k}: will hold the private key

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the ECC private key's parameters found
in the given structure. The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

In EdDSA curves the  @code{y} parameter will be @code{NULL}  and the other parameters
will be in the native format for the curve.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_export_gost_raw2
@anchor{gnutls_privkey_export_gost_raw2}
@deftypefun {int} {gnutls_privkey_export_gost_raw2} (gnutls_privkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_digest_algorithm_t * @var{digest}, gnutls_gost_paramset_t * @var{paramset}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, gnutls_datum_t * @var{k}, unsigned int @var{flags})
@var{key}: Holds the public key

@var{curve}: will hold the curve

@var{digest}: will hold the digest

@var{paramset}: will hold the GOST parameter set ID

@var{x}: will hold the x-coordinate

@var{y}: will hold the y-coordinate

@var{k}: will hold the private key

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the GOST private key's parameters found
in the given structure. The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

@strong{Note:} parameters will be stored with least significant byte first. On
version 3.6.3 this was incorrectly returned in big-endian format.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.3
@end deftypefun

@subheading gnutls_privkey_export_openpgp
@anchor{gnutls_privkey_export_openpgp}
@deftypefun {int} {gnutls_privkey_export_openpgp} (gnutls_privkey_t @var{pkey}, gnutls_openpgp_privkey_t * @var{key})
@var{pkey}: The private key

@var{key}: Location for the key to be exported.

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_privkey_export_pkcs11
@anchor{gnutls_privkey_export_pkcs11}
@deftypefun {int} {gnutls_privkey_export_pkcs11} (gnutls_privkey_t @var{pkey}, gnutls_pkcs11_privkey_t * @var{key})
@var{pkey}: The private key

@var{key}: Location for the key to be exported.

Converts the given abstract private key to a @code{gnutls_pkcs11_privkey_t} 
type. The key must be of type @code{GNUTLS_PRIVKEY_PKCS11} . The key
returned in  @code{key} must be deinitialized with
@code{gnutls_pkcs11_privkey_deinit()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_privkey_export_rsa_raw
@anchor{gnutls_privkey_export_rsa_raw}
@deftypefun {int} {gnutls_privkey_export_rsa_raw} (gnutls_privkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u}, gnutls_datum_t * @var{e1}, gnutls_datum_t * @var{e2})
@var{key}: Holds the certificate

@var{m}: will hold the modulus

@var{e}: will hold the public exponent

@var{d}: will hold the private exponent

@var{p}: will hold the first prime (p)

@var{q}: will hold the second prime (q)

@var{u}: will hold the coefficient

@var{e1}: will hold e1 = d mod (p-1)

@var{e2}: will hold e2 = d mod (q-1)

This function will export the RSA private key's parameters found
in the given structure. The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum. For
EdDSA keys, the  @code{y} value should be @code{NULL} .

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_privkey_export_rsa_raw2
@anchor{gnutls_privkey_export_rsa_raw2}
@deftypefun {int} {gnutls_privkey_export_rsa_raw2} (gnutls_privkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, gnutls_datum_t * @var{d}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{u}, gnutls_datum_t * @var{e1}, gnutls_datum_t * @var{e2}, unsigned int @var{flags})
@var{key}: Holds the certificate

@var{m}: will hold the modulus

@var{e}: will hold the public exponent

@var{d}: will hold the private exponent

@var{p}: will hold the first prime (p)

@var{q}: will hold the second prime (q)

@var{u}: will hold the coefficient

@var{e1}: will hold e1 = d mod (p-1)

@var{e2}: will hold e2 = d mod (q-1)

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the RSA private key's parameters found
in the given structure. The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_export_x509
@anchor{gnutls_privkey_export_x509}
@deftypefun {int} {gnutls_privkey_export_x509} (gnutls_privkey_t @var{pkey}, gnutls_x509_privkey_t * @var{key})
@var{pkey}: The private key

@var{key}: Location for the key to be exported.

Converts the given abstract private key to a @code{gnutls_x509_privkey_t} 
type. The abstract key must be of type @code{GNUTLS_PRIVKEY_X509} . The input
 @code{key} must not be initialized. The key returned in  @code{key} should be deinitialized
using @code{gnutls_x509_privkey_deinit()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_privkey_generate
@anchor{gnutls_privkey_generate}
@deftypefun {int} {gnutls_privkey_generate} (gnutls_privkey_t @var{pkey}, gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}, unsigned int @var{flags})
@var{pkey}: An initialized private key

@var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} .

@var{bits}: the size of the parameters to generate

@var{flags}: Must be zero or flags from @code{gnutls_privkey_flags_t} .

This function will generate a random private key. Note that this
function must be called on an initialized private key.

The flag @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} 
instructs the key generation process to use algorithms like Shawe-Taylor
(from FIPS PUB186-4) which generate provable parameters out of a seed
for RSA and DSA keys. See @code{gnutls_privkey_generate2()}  for more
information.

Note that when generating an elliptic curve key, the curve
can be substituted in the place of the bits parameter using the
@code{GNUTLS_CURVE_TO_BITS()}  macro. The input to the macro is any curve from
@code{gnutls_ecc_curve_t} .

For DSA keys, if the subgroup size needs to be specified check
the @code{GNUTLS_SUBGROUP_TO_BITS()}  macro.

It is recommended to do not set the number of  @code{bits} directly, use @code{gnutls_sec_param_to_pk_bits()}  instead .

See also @code{gnutls_privkey_generate2()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_privkey_generate2
@anchor{gnutls_privkey_generate2}
@deftypefun {int} {gnutls_privkey_generate2} (gnutls_privkey_t @var{pkey}, gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}, unsigned int @var{flags}, const gnutls_keygen_data_st * @var{data}, unsigned @var{data_size})
@var{pkey}: The private key

@var{algo}: is one of the algorithms in @code{gnutls_pk_algorithm_t} .

@var{bits}: the size of the modulus

@var{flags}: Must be zero or flags from @code{gnutls_privkey_flags_t} .

@var{data}: Allow specifying @code{gnutls_keygen_data_st}  types such as the seed to be used.

@var{data_size}: The number of  @code{data} available.

This function will generate a random private key. Note that this
function must be called on an initialized private key.

The flag @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} 
instructs the key generation process to use algorithms like Shawe-Taylor
(from FIPS PUB186-4) which generate provable parameters out of a seed
for RSA and DSA keys. On DSA keys the PQG parameters are generated using the
seed, while on RSA the two primes. To specify an explicit seed
(by default a random seed is used), use the  @code{data} with a @code{GNUTLS_KEYGEN_SEED} 
type.

Note that when generating an elliptic curve key, the curve
can be substituted in the place of the bits parameter using the
@code{GNUTLS_CURVE_TO_BITS()}  macro.

To export the generated keys in memory or in files it is recommended to use the
PKCS@code{8}  form as it can handle all key types, and can store additional parameters
such as the seed, in case of provable RSA or DSA keys.
Generated keys can be exported in memory using @code{gnutls_privkey_export_x509()} ,
and then with @code{gnutls_x509_privkey_export2_pkcs8()} .

If key generation is part of your application, avoid setting the number
of bits directly, and instead use @code{gnutls_sec_param_to_pk_bits()} .
That way the generated keys will adapt to the security levels
of the underlying GnuTLS library.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.5.0
@end deftypefun

@subheading gnutls_privkey_get_pk_algorithm
@anchor{gnutls_privkey_get_pk_algorithm}
@deftypefun {int} {gnutls_privkey_get_pk_algorithm} (gnutls_privkey_t @var{key}, unsigned int * @var{bits})
@var{key}: should contain a @code{gnutls_privkey_t}  type

@var{bits}: If set will return the number of bits of the parameters (may be NULL)

This function will return the public key algorithm of a private
key and if possible will return a number of bits that indicates
the security parameter of the key.

@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t}  enumeration on
success, or a negative error code on error.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_get_seed
@anchor{gnutls_privkey_get_seed}
@deftypefun {int} {gnutls_privkey_get_seed} (gnutls_privkey_t @var{key}, gnutls_digest_algorithm_t * @var{digest}, void * @var{seed}, size_t * @var{seed_size})
@var{key}: should contain a @code{gnutls_privkey_t}  type

@var{digest}: if non-NULL it will contain the digest algorithm used for key generation (if applicable)

@var{seed}: where seed will be copied to

@var{seed_size}: originally holds the size of  @code{seed} , will be updated with actual size

This function will return the seed that was used to generate the
given private key. That function will succeed only if the key was generated
as a provable key.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.5.0
@end deftypefun

@subheading gnutls_privkey_get_spki
@anchor{gnutls_privkey_get_spki}
@deftypefun {int} {gnutls_privkey_get_spki} (gnutls_privkey_t @var{privkey}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags})
@var{privkey}: a public key of type @code{gnutls_privkey_t} 

@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_privkey_spki_t} 

@var{flags}: must be zero

This function will return the public key information if available.
The provided  @code{spki} must be initialized.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_get_type
@anchor{gnutls_privkey_get_type}
@deftypefun {gnutls_privkey_type_t} {gnutls_privkey_get_type} (gnutls_privkey_t @var{key})
@var{key}: should contain a @code{gnutls_privkey_t}  type

This function will return the type of the private key. This is
actually the type of the subsystem used to set this private key.

@strong{Returns:} a member of the @code{gnutls_privkey_type_t}  enumeration on
success, or a negative error code on error.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_import_dsa_raw
@anchor{gnutls_privkey_import_dsa_raw}
@deftypefun {int} {gnutls_privkey_import_dsa_raw} (gnutls_privkey_t @var{key}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{g}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{x})
@var{key}: The structure to store the parsed key

@var{p}: holds the p

@var{q}: holds the q

@var{g}: holds the g

@var{y}: holds the y (optional)

@var{x}: holds the x

This function will convert the given DSA raw parameters to the
native @code{gnutls_privkey_t}  format.  The output will be stored
in  @code{key} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_privkey_import_ecc_raw
@anchor{gnutls_privkey_import_ecc_raw}
@deftypefun {int} {gnutls_privkey_import_ecc_raw} (gnutls_privkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{k})
@var{key}: The key

@var{curve}: holds the curve

@var{x}: holds the x-coordinate

@var{y}: holds the y-coordinate

@var{k}: holds the k (private key)

This function will convert the given elliptic curve parameters to the
native @code{gnutls_privkey_t}  format.  The output will be stored
in  @code{key} .

In EdDSA curves the  @code{y} parameter should be @code{NULL}  and the  @code{x} and  @code{k} parameters
must be in the native format for the curve.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_privkey_import_ext
@anchor{gnutls_privkey_import_ext}
@deftypefun {int} {gnutls_privkey_import_ext} (gnutls_privkey_t @var{pkey}, gnutls_pk_algorithm_t @var{pk}, void * @var{userdata}, gnutls_privkey_sign_func @var{sign_func}, gnutls_privkey_decrypt_func @var{decrypt_func}, unsigned int @var{flags})
@var{pkey}: The private key

@var{pk}: The public key algorithm

@var{userdata}: private data to be provided to the callbacks

@var{sign_func}: callback for signature operations

@var{decrypt_func}: callback for decryption operations

@var{flags}: Flags for the import

This function will associate the given callbacks with the
@code{gnutls_privkey_t}  type. At least one of the two callbacks
must be non-null.

Note that the signing function is supposed to "raw" sign data, i.e.,
without any hashing or preprocessing. In case of RSA the DigestInfo
will be provided, and the signing function is expected to do the PKCS @code{1} 
1.5 padding and the exponentiation.

See also @code{gnutls_privkey_import_ext3()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_privkey_import_ext2
@anchor{gnutls_privkey_import_ext2}
@deftypefun {int} {gnutls_privkey_import_ext2} (gnutls_privkey_t @var{pkey}, gnutls_pk_algorithm_t @var{pk}, void * @var{userdata}, gnutls_privkey_sign_func @var{sign_fn}, gnutls_privkey_decrypt_func @var{decrypt_fn}, gnutls_privkey_deinit_func @var{deinit_fn}, unsigned int @var{flags})
@var{pkey}: The private key

@var{pk}: The public key algorithm

@var{userdata}: private data to be provided to the callbacks

@var{sign_fn}: callback for signature operations

@var{decrypt_fn}: callback for decryption operations

@var{deinit_fn}: a deinitialization function

@var{flags}: Flags for the import

This function will associate the given callbacks with the
@code{gnutls_privkey_t}  type. At least one of the two callbacks
must be non-null. If a deinitialization function is provided
then flags is assumed to contain @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE} .

Note that the signing function is supposed to "raw" sign data, i.e.,
without any hashing or preprocessing. In case of RSA the DigestInfo
will be provided, and the signing function is expected to do the PKCS @code{1} 
1.5 padding and the exponentiation.

See also @code{gnutls_privkey_import_ext3()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1
@end deftypefun

@subheading gnutls_privkey_import_ext3
@anchor{gnutls_privkey_import_ext3}
@deftypefun {int} {gnutls_privkey_import_ext3} (gnutls_privkey_t @var{pkey}, void * @var{userdata}, gnutls_privkey_sign_func @var{sign_fn}, gnutls_privkey_decrypt_func @var{decrypt_fn}, gnutls_privkey_deinit_func @var{deinit_fn}, gnutls_privkey_info_func @var{info_fn}, unsigned int @var{flags})
@var{pkey}: The private key

@var{userdata}: private data to be provided to the callbacks

@var{sign_fn}: callback for signature operations

@var{decrypt_fn}: callback for decryption operations

@var{deinit_fn}: a deinitialization function

@var{info_fn}: returns info about the public key algorithm (should not be @code{NULL} )

@var{flags}: Flags for the import

This function will associate the given callbacks with the
@code{gnutls_privkey_t}  type. At least one of the two callbacks
must be non-null. If a deinitialization function is provided
then flags is assumed to contain @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE} .

Note that the signing function is supposed to "raw" sign data, i.e.,
without any hashing or preprocessing. In case of RSA the DigestInfo
will be provided, and the signing function is expected to do the PKCS @code{1} 
1.5 padding and the exponentiation.

The  @code{info_fn} must provide information on the algorithms supported by
this private key, and should support the flags @code{GNUTLS_PRIVKEY_INFO_PK_ALGO}  and
@code{GNUTLS_PRIVKEY_INFO_SIGN_ALGO} . It must return -1 on unknown flags.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_privkey_import_ext4
@anchor{gnutls_privkey_import_ext4}
@deftypefun {int} {gnutls_privkey_import_ext4} (gnutls_privkey_t @var{pkey}, void * @var{userdata}, gnutls_privkey_sign_data_func @var{sign_data_fn}, gnutls_privkey_sign_hash_func @var{sign_hash_fn}, gnutls_privkey_decrypt_func @var{decrypt_fn}, gnutls_privkey_deinit_func @var{deinit_fn}, gnutls_privkey_info_func @var{info_fn}, unsigned int @var{flags})
@var{pkey}: The private key

@var{userdata}: private data to be provided to the callbacks

@var{sign_data_fn}: callback for signature operations (may be @code{NULL} )

@var{sign_hash_fn}: callback for signature operations (may be @code{NULL} )

@var{decrypt_fn}: callback for decryption operations (may be @code{NULL} )

@var{deinit_fn}: a deinitialization function

@var{info_fn}: returns info about the public key algorithm (should not be @code{NULL} )

@var{flags}: Flags for the import

This function will associate the given callbacks with the
@code{gnutls_privkey_t}  type. At least one of the callbacks
must be non-null. If a deinitialization function is provided
then flags is assumed to contain @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE} .

Note that in contrast with the signing function of
@code{gnutls_privkey_import_ext3()} , the signing functions provided to this
function take explicitly the signature algorithm as parameter and
different functions are provided to sign the data and hashes.

The  @code{sign_hash_fn} is to be called to sign pre-hashed data. The input
to the callback is the output of the hash (such as SHA256) corresponding
to the signature algorithm. For RSA PKCS@code{1}  signatures, the signature
algorithm can be set to @code{GNUTLS_SIGN_RSA_RAW} , and in that case the data
should be handled as if they were an RSA PKCS@code{1}  DigestInfo structure.

The  @code{sign_data_fn} is to be called to sign data. The input data will be
he data to be signed (and hashed), with the provided signature
algorithm. This function is to be used for signature algorithms like
Ed25519 which cannot take pre-hashed data as input.

When both  @code{sign_data_fn} and  @code{sign_hash_fn} functions are provided they
must be able to operate on all the supported signature algorithms,
unless prohibited by the type of the algorithm (e.g., as with Ed25519).

The  @code{info_fn} must provide information on the signature algorithms supported by
this private key, and should support the flags @code{GNUTLS_PRIVKEY_INFO_PK_ALGO} ,
@code{GNUTLS_PRIVKEY_INFO_HAVE_SIGN_ALGO}  and @code{GNUTLS_PRIVKEY_INFO_PK_ALGO_BITS} .
It must return -1 on unknown flags.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_import_gost_raw
@anchor{gnutls_privkey_import_gost_raw}
@deftypefun {int} {gnutls_privkey_import_gost_raw} (gnutls_privkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, gnutls_digest_algorithm_t @var{digest}, gnutls_gost_paramset_t @var{paramset}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y}, const gnutls_datum_t * @var{k})
@var{key}: The key

@var{curve}: holds the curve

@var{digest}: holds the digest

@var{paramset}: holds the GOST parameter set ID

@var{x}: holds the x-coordinate

@var{y}: holds the y-coordinate

@var{k}: holds the k (private key)

This function will convert the given GOST private key's parameters to the
native @code{gnutls_privkey_t}  format.  The output will be stored
in  @code{key} .   @code{digest} should be one of GNUTLS_DIG_GOSR_94,
GNUTLS_DIG_STREEBOG_256 or GNUTLS_DIG_STREEBOG_512.  If  @code{paramset} is set to
GNUTLS_GOST_PARAMSET_UNKNOWN default one will be selected depending on
 @code{digest} .

@strong{Note:} parameters should be stored with least significant byte first. On
version 3.6.3 big-endian format was used incorrectly.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.3
@end deftypefun

@subheading gnutls_privkey_import_openpgp
@anchor{gnutls_privkey_import_openpgp}
@deftypefun {int} {gnutls_privkey_import_openpgp} (gnutls_privkey_t @var{pkey}, gnutls_openpgp_privkey_t @var{key}, unsigned int @var{flags})
@var{pkey}: The private key

@var{key}: The private key to be imported

@var{flags}: Flags for the import

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_import_openpgp_raw
@anchor{gnutls_privkey_import_openpgp_raw}
@deftypefun {int} {gnutls_privkey_import_openpgp_raw} (gnutls_privkey_t @var{pkey}, const gnutls_datum_t * @var{data}, gnutls_openpgp_crt_fmt_t           @var{format}, const gnutls_openpgp_keyid_t           @var{keyid}, const char * @var{password})
@var{pkey}: The private key

@var{data}: The private key data to be imported

@var{format}: The format of the private key

@var{keyid}: The key id to use (optional)

@var{password}: A password (optional)

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_privkey_import_pkcs11
@anchor{gnutls_privkey_import_pkcs11}
@deftypefun {int} {gnutls_privkey_import_pkcs11} (gnutls_privkey_t @var{pkey}, gnutls_pkcs11_privkey_t @var{key}, unsigned int @var{flags})
@var{pkey}: The private key

@var{key}: The private key to be imported

@var{flags}: Flags for the import

This function will import the given private key to the abstract
@code{gnutls_privkey_t}  type.

The @code{gnutls_pkcs11_privkey_t}  object must not be deallocated
during the lifetime of this structure.

 @code{flags} might be zero or one of @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE} 
and @code{GNUTLS_PRIVKEY_IMPORT_COPY} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_import_pkcs11_url
@anchor{gnutls_privkey_import_pkcs11_url}
@deftypefun {int} {gnutls_privkey_import_pkcs11_url} (gnutls_privkey_t @var{key}, const char * @var{url})
@var{key}: A key of type @code{gnutls_pubkey_t} 

@var{url}: A PKCS 11 url

This function will import a PKCS 11 private key to a @code{gnutls_private_key_t} 
type.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_privkey_import_rsa_raw
@anchor{gnutls_privkey_import_rsa_raw}
@deftypefun {int} {gnutls_privkey_import_rsa_raw} (gnutls_privkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e}, const gnutls_datum_t * @var{d}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{u}, const gnutls_datum_t * @var{e1}, const gnutls_datum_t * @var{e2})
@var{key}: The structure to store the parsed key

@var{m}: holds the modulus

@var{e}: holds the public exponent

@var{d}: holds the private exponent (optional)

@var{p}: holds the first prime (p)

@var{q}: holds the second prime (q)

@var{u}: holds the coefficient (optional)

@var{e1}: holds e1 = d mod (p-1) (optional)

@var{e2}: holds e2 = d mod (q-1) (optional)

This function will convert the given RSA raw parameters to the
native @code{gnutls_privkey_t}  format.  The output will be stored in
 @code{key} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_privkey_import_tpm_raw
@anchor{gnutls_privkey_import_tpm_raw}
@deftypefun {int} {gnutls_privkey_import_tpm_raw} (gnutls_privkey_t @var{pkey}, const gnutls_datum_t * @var{fdata}, gnutls_tpmkey_fmt_t @var{format}, const char * @var{srk_password}, const char * @var{key_password}, unsigned int @var{flags})
@var{pkey}: The private key

@var{fdata}: The TPM key to be imported

@var{format}: The format of the private key

@var{srk_password}: The password for the SRK key (optional)

@var{key_password}: A password for the key (optional)

@var{flags}: should be zero

This function will import the given private key to the abstract
@code{gnutls_privkey_t}  type. 

With respect to passwords the same as in @code{gnutls_privkey_import_tpm_url()}  apply.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_privkey_import_tpm_url
@anchor{gnutls_privkey_import_tpm_url}
@deftypefun {int} {gnutls_privkey_import_tpm_url} (gnutls_privkey_t @var{pkey}, const char * @var{url}, const char * @var{srk_password}, const char * @var{key_password}, unsigned int @var{flags})
@var{pkey}: The private key

@var{url}: The URL of the TPM key to be imported

@var{srk_password}: The password for the SRK key (optional)

@var{key_password}: A password for the key (optional)

@var{flags}: One of the GNUTLS_PRIVKEY_* flags

This function will import the given private key to the abstract
@code{gnutls_privkey_t}  type.

Note that unless @code{GNUTLS_PRIVKEY_DISABLE_CALLBACKS} 
is specified, if incorrect (or NULL) passwords are given
the PKCS11 callback functions will be used to obtain the
correct passwords. Otherwise if the SRK password is wrong
@code{GNUTLS_E_TPM_SRK_PASSWORD_ERROR}  is returned and if the key password
is wrong or not provided then @code{GNUTLS_E_TPM_KEY_PASSWORD_ERROR} 
is returned. 

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_privkey_import_url
@anchor{gnutls_privkey_import_url}
@deftypefun {int} {gnutls_privkey_import_url} (gnutls_privkey_t @var{key}, const char * @var{url}, unsigned int @var{flags})
@var{key}: A key of type @code{gnutls_privkey_t} 

@var{url}: A PKCS 11 url

@var{flags}: should be zero

This function will import a PKCS11 or TPM URL as a
private key. The supported URL types can be checked
using @code{gnutls_url_is_supported()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_privkey_import_x509
@anchor{gnutls_privkey_import_x509}
@deftypefun {int} {gnutls_privkey_import_x509} (gnutls_privkey_t @var{pkey}, gnutls_x509_privkey_t @var{key}, unsigned int @var{flags})
@var{pkey}: The private key

@var{key}: The private key to be imported

@var{flags}: Flags for the import

This function will import the given private key to the abstract
@code{gnutls_privkey_t}  type.

The @code{gnutls_x509_privkey_t}  object must not be deallocated
during the lifetime of this structure.

 @code{flags} might be zero or one of @code{GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE} 
and @code{GNUTLS_PRIVKEY_IMPORT_COPY} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_import_x509_raw
@anchor{gnutls_privkey_import_x509_raw}
@deftypefun {int} {gnutls_privkey_import_x509_raw} (gnutls_privkey_t @var{pkey}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{password}, unsigned int @var{flags})
@var{pkey}: The private key

@var{data}: The private key data to be imported

@var{format}: The format of the private key

@var{password}: A password (optional)

@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t

This function will import the given private key to the abstract
@code{gnutls_privkey_t}  type. 

The supported formats are basic unencrypted key, PKCS8, PKCS12, 
TSS2, and the openssl format.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_privkey_init
@anchor{gnutls_privkey_init}
@deftypefun {int} {gnutls_privkey_init} (gnutls_privkey_t * @var{key})
@var{key}: A pointer to the type to be initialized

This function will initialize a private key object. The object can
be used to generate, import, and perform cryptographic operations
on the associated private key.

Note that when the underlying private key is a PKCS@code{11}  key (i.e.,
when imported with a PKCS@code{11}  URI), the limitations of @code{gnutls_pkcs11_privkey_init()} 
apply to this object as well. In versions of GnuTLS later than 3.5.11 the object
is protected using locks and a single @code{gnutls_privkey_t}  can be re-used
by many threads. However, for performance it is recommended to utilize
one object per key per thread.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_set_flags
@anchor{gnutls_privkey_set_flags}
@deftypefun {void} {gnutls_privkey_set_flags} (gnutls_privkey_t @var{key}, unsigned int @var{flags})
@var{key}: A key of type @code{gnutls_privkey_t} 

@var{flags}: flags from the @code{gnutls_privkey_flags} 

This function will set flags for the specified private key, after
it is generated. Currently this is useful for the @code{GNUTLS_PRIVKEY_FLAG_EXPORT_COMPAT} 
to allow exporting a "provable" private key in backwards compatible way.

@strong{Since:} 3.5.0
@end deftypefun

@subheading gnutls_privkey_set_pin_function
@anchor{gnutls_privkey_set_pin_function}
@deftypefun {void} {gnutls_privkey_set_pin_function} (gnutls_privkey_t @var{key}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
@var{key}: A key of type @code{gnutls_privkey_t} 

@var{fn}: the callback

@var{userdata}: data associated with the callback

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

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

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_privkey_set_spki
@anchor{gnutls_privkey_set_spki}
@deftypefun {int} {gnutls_privkey_set_spki} (gnutls_privkey_t @var{privkey}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags})
@var{privkey}: a public key of type @code{gnutls_privkey_t} 

@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_privkey_spki_t} 

@var{flags}: must be zero

This function will set the public key information.
The provided  @code{spki} must be initialized.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_sign_data
@anchor{gnutls_privkey_sign_data}
@deftypefun {int} {gnutls_privkey_sign_data} (gnutls_privkey_t @var{signer}, gnutls_digest_algorithm_t @var{hash}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{signature})
@var{signer}: Holds the key

@var{hash}: should be a digest algorithm

@var{flags}: Zero or one of @code{gnutls_privkey_flags_t} 

@var{data}: holds the data to be signed

@var{signature}: will contain the signature allocated with @code{gnutls_malloc()} 

This function will sign the given data using a signature algorithm
supported by the private key. Signature algorithms are always used
together with a hash functions.  Different hash functions may be
used for the RSA algorithm, but only the SHA family for the DSA keys.

You may use @code{gnutls_pubkey_get_preferred_hash_algorithm()}  to determine
the hash algorithm.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_sign_data2
@anchor{gnutls_privkey_sign_data2}
@deftypefun {int} {gnutls_privkey_sign_data2} (gnutls_privkey_t @var{signer}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{signature})
@var{signer}: Holds the key

@var{algo}: The signature algorithm used

@var{flags}: Zero or one of @code{gnutls_privkey_flags_t} 

@var{data}: holds the data to be signed

@var{signature}: will contain the signature allocated with @code{gnutls_malloc()} 

This function will sign the given data using the specified signature
algorithm. This function is an enhancement of @code{gnutls_privkey_sign_data()} ,
as it allows utilizing a alternative signature algorithm where possible
(e.g, use an RSA key with RSA-PSS).

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_sign_hash
@anchor{gnutls_privkey_sign_hash}
@deftypefun {int} {gnutls_privkey_sign_hash} (gnutls_privkey_t @var{signer}, gnutls_digest_algorithm_t @var{hash_algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{hash_data}, gnutls_datum_t * @var{signature})
@var{signer}: Holds the signer's key

@var{hash_algo}: The hash algorithm used

@var{flags}: Zero or one of @code{gnutls_privkey_flags_t} 

@var{hash_data}: holds the data to be signed

@var{signature}: will contain newly allocated signature

This function will sign the given hashed data using a signature algorithm
supported by the private key. Signature algorithms are always used
together with a hash functions.  Different hash functions may be
used for the RSA algorithm, but only SHA-XXX for the DSA keys.

You may use @code{gnutls_pubkey_get_preferred_hash_algorithm()}  to determine
the hash algorithm.

The flags may be @code{GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA}  or @code{GNUTLS_PRIVKEY_SIGN_FLAG_RSA_PSS} .
In the former case this function will ignore  @code{hash_algo} and perform a raw PKCS1 signature,
and in the latter an RSA-PSS signature will be generated.

Note that, not all algorithm support signing already hashed data. When
signing with Ed25519, @code{gnutls_privkey_sign_data()}  should be used.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_privkey_sign_hash2
@anchor{gnutls_privkey_sign_hash2}
@deftypefun {int} {gnutls_privkey_sign_hash2} (gnutls_privkey_t @var{signer}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{hash_data}, gnutls_datum_t * @var{signature})
@var{signer}: Holds the signer's key

@var{algo}: The signature algorithm used

@var{flags}: Zero or one of @code{gnutls_privkey_flags_t} 

@var{hash_data}: holds the data to be signed

@var{signature}: will contain newly allocated signature

This function will sign the given hashed data using the specified signature
algorithm. This function is an enhancement of @code{gnutls_privkey_sign_hash()} ,
as it allows utilizing a alternative signature algorithm where possible
(e.g, use an RSA key with RSA-PSS).

The flags may be @code{GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA} .
In that case this function will ignore  @code{hash_algo} and perform a raw PKCS1 signature.
Note that this flag is supported since 3.6.9.

Note also that, not all algorithm support signing already hashed data. When
signing with Ed25519, @code{gnutls_privkey_sign_data2()}  should be used instead.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_privkey_status
@anchor{gnutls_privkey_status}
@deftypefun {int} {gnutls_privkey_status} (gnutls_privkey_t @var{key})
@var{key}: Holds the key

Checks the status of the private key token. This function
is an actual wrapper over @code{gnutls_pkcs11_privkey_status()} , and
if the private key is a PKCS @code{11}  token it will check whether
it is inserted or not.

@strong{Returns:} this function will return non-zero if the token 
holding the private key is still available (inserted), and zero otherwise.

@strong{Since:} 3.1.10
@end deftypefun

@subheading gnutls_privkey_verify_params
@anchor{gnutls_privkey_verify_params}
@deftypefun {int} {gnutls_privkey_verify_params} (gnutls_privkey_t @var{key})
@var{key}: should contain a @code{gnutls_privkey_t}  type

This function will verify the private key parameters.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_privkey_verify_seed
@anchor{gnutls_privkey_verify_seed}
@deftypefun {int} {gnutls_privkey_verify_seed} (gnutls_privkey_t @var{key}, gnutls_digest_algorithm_t @var{digest}, const void * @var{seed}, size_t @var{seed_size})
@var{key}: should contain a @code{gnutls_privkey_t}  type

@var{digest}: it contains the digest algorithm used for key generation (if applicable)

@var{seed}: the seed of the key to be checked with

@var{seed_size}: holds the size of  @code{seed} 

This function will verify that the given private key was generated from
the provided seed.

@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PRIVKEY_VERIFICATION_ERROR} 
is returned, and zero or positive code on success.

@strong{Since:} 3.5.0
@end deftypefun

@subheading gnutls_pubkey_deinit
@anchor{gnutls_pubkey_deinit}
@deftypefun {void} {gnutls_pubkey_deinit} (gnutls_pubkey_t @var{key})
@var{key}: The key to be deinitialized

This function will deinitialize a public key structure.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_encrypt_data
@anchor{gnutls_pubkey_encrypt_data}
@deftypefun {int} {gnutls_pubkey_encrypt_data} (gnutls_pubkey_t @var{key}, unsigned int @var{flags}, const gnutls_datum_t * @var{plaintext}, gnutls_datum_t * @var{ciphertext})
@var{key}: Holds the public key

@var{flags}: should be 0 for now

@var{plaintext}: The data to be encrypted

@var{ciphertext}: contains the encrypted data

This function will encrypt the given data, using the public
key. On success the  @code{ciphertext} will be allocated using @code{gnutls_malloc()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pubkey_export
@anchor{gnutls_pubkey_export}
@deftypefun {int} {gnutls_pubkey_export} (gnutls_pubkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, void * @var{output_data}, size_t * @var{output_data_size})
@var{key}: Holds the certificate

@var{format}: the format of output params. One of PEM or DER.

@var{output_data}: will contain a certificate PEM or DER encoded

@var{output_data_size}: holds the size of output_data (and will be
replaced by the actual size of parameters)

This function will export the public key to DER or PEM format.
The contents of the exported data is the SubjectPublicKeyInfo
X.509 structure.

If the buffer provided is not long enough to hold the output, then
*output_data_size is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}  will
be returned.

If the structure is PEM encoded, it will have a header
of "BEGIN CERTIFICATE".

@strong{Returns:} In case of failure a negative error code will be
returned, and 0 on success.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_export2
@anchor{gnutls_pubkey_export2}
@deftypefun {int} {gnutls_pubkey_export2} (gnutls_pubkey_t @var{key}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out})
@var{key}: Holds the certificate

@var{format}: the format of output params. One of PEM or DER.

@var{out}: will contain a certificate PEM or DER encoded

This function will export the public key to DER or PEM format.
The contents of the exported data is the SubjectPublicKeyInfo
X.509 structure.

The output buffer will be allocated using @code{gnutls_malloc()} .

If the structure is PEM encoded, it will have a header
of "BEGIN CERTIFICATE".

@strong{Returns:} In case of failure a negative error code will be
returned, and 0 on success.

@strong{Since:} 3.1.3
@end deftypefun

@subheading gnutls_pubkey_export_dsa_raw
@anchor{gnutls_pubkey_export_dsa_raw}
@deftypefun {int} {gnutls_pubkey_export_dsa_raw} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y})
@var{key}: Holds the public key

@var{p}: will hold the p (may be @code{NULL} )

@var{q}: will hold the q (may be @code{NULL} )

@var{g}: will hold the g (may be @code{NULL} )

@var{y}: will hold the y (may be @code{NULL} )

This function will export the DSA public key's parameters found in
the given certificate.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

This function allows for @code{NULL}  parameters since 3.4.1.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_pubkey_export_dsa_raw2
@anchor{gnutls_pubkey_export_dsa_raw2}
@deftypefun {int} {gnutls_pubkey_export_dsa_raw2} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{p}, gnutls_datum_t * @var{q}, gnutls_datum_t * @var{g}, gnutls_datum_t * @var{y}, unsigned @var{flags})
@var{key}: Holds the public key

@var{p}: will hold the p (may be @code{NULL} )

@var{q}: will hold the q (may be @code{NULL} )

@var{g}: will hold the g (may be @code{NULL} )

@var{y}: will hold the y (may be @code{NULL} )

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the DSA public key's parameters found in
the given certificate.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

This function allows for @code{NULL}  parameters since 3.4.1.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_pubkey_export_ecc_raw
@anchor{gnutls_pubkey_export_ecc_raw}
@deftypefun {int} {gnutls_pubkey_export_ecc_raw} (gnutls_pubkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y})
@var{key}: Holds the public key

@var{curve}: will hold the curve (may be @code{NULL} )

@var{x}: will hold x-coordinate (may be @code{NULL} )

@var{y}: will hold y-coordinate (may be @code{NULL} )

This function will export the ECC public key's parameters found in
the given key.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

In EdDSA curves the  @code{y} parameter will be @code{NULL}  and the other parameters
will be in the native format for the curve.

This function allows for @code{NULL}  parameters since 3.4.1.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pubkey_export_ecc_raw2
@anchor{gnutls_pubkey_export_ecc_raw2}
@deftypefun {int} {gnutls_pubkey_export_ecc_raw2} (gnutls_pubkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, unsigned int @var{flags})
@var{key}: Holds the public key

@var{curve}: will hold the curve (may be @code{NULL} )

@var{x}: will hold x-coordinate (may be @code{NULL} )

@var{y}: will hold y-coordinate (may be @code{NULL} )

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the ECC public key's parameters found in
the given key.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

In EdDSA curves the  @code{y} parameter will be @code{NULL}  and the other parameters
will be in the native format for the curve.

This function allows for @code{NULL}  parameters since 3.4.1.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_pubkey_export_ecc_x962
@anchor{gnutls_pubkey_export_ecc_x962}
@deftypefun {int} {gnutls_pubkey_export_ecc_x962} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{parameters}, gnutls_datum_t * @var{ecpoint})
@var{key}: Holds the public key

@var{parameters}: DER encoding of an ANSI X9.62 parameters

@var{ecpoint}: DER encoding of ANSI X9.62 ECPoint

This function will export the ECC public key's parameters found in
the given certificate.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_pubkey_export_gost_raw2
@anchor{gnutls_pubkey_export_gost_raw2}
@deftypefun {int} {gnutls_pubkey_export_gost_raw2} (gnutls_pubkey_t @var{key}, gnutls_ecc_curve_t * @var{curve}, gnutls_digest_algorithm_t * @var{digest}, gnutls_gost_paramset_t * @var{paramset}, gnutls_datum_t * @var{x}, gnutls_datum_t * @var{y}, unsigned int @var{flags})
@var{key}: Holds the public key

@var{curve}: will hold the curve (may be @code{NULL} )

@var{digest}: will hold the curve (may be @code{NULL} )

@var{paramset}: will hold the parameters id (may be @code{NULL} )

@var{x}: will hold the x-coordinate (may be @code{NULL} )

@var{y}: will hold the y-coordinate (may be @code{NULL} )

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the GOST public key's parameters found in
the given key.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

@strong{Note:} parameters will be stored with least significant byte first. On
version 3.6.3 this was incorrectly returned in big-endian format.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.3
@end deftypefun

@subheading gnutls_pubkey_export_rsa_raw
@anchor{gnutls_pubkey_export_rsa_raw}
@deftypefun {int} {gnutls_pubkey_export_rsa_raw} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e})
@var{key}: Holds the certificate

@var{m}: will hold the modulus (may be @code{NULL} )

@var{e}: will hold the public exponent (may be @code{NULL} )

This function will export the RSA public key's parameters found in
the given structure.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

This function allows for @code{NULL}  parameters since 3.4.1.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_pubkey_export_rsa_raw2
@anchor{gnutls_pubkey_export_rsa_raw2}
@deftypefun {int} {gnutls_pubkey_export_rsa_raw2} (gnutls_pubkey_t @var{key}, gnutls_datum_t * @var{m}, gnutls_datum_t * @var{e}, unsigned @var{flags})
@var{key}: Holds the certificate

@var{m}: will hold the modulus (may be @code{NULL} )

@var{e}: will hold the public exponent (may be @code{NULL} )

@var{flags}: flags from @code{gnutls_abstract_export_flags_t} 

This function will export the RSA public key's parameters found in
the given structure.  The new parameters will be allocated using
@code{gnutls_malloc()}  and will be stored in the appropriate datum.

This function allows for @code{NULL}  parameters since 3.4.1.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_pubkey_get_key_id
@anchor{gnutls_pubkey_get_key_id}
@deftypefun {int} {gnutls_pubkey_get_key_id} (gnutls_pubkey_t @var{key}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size})
@var{key}: Holds the public key

@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} 

@var{output_data}: will contain the key ID

@var{output_data_size}: holds the size of output_data (and will be
replaced by the actual size of parameters)

This function will return a unique ID that depends on the public
key parameters. This ID can be used in checking whether a
certificate corresponds to the given public key.

If the buffer provided is not long enough to hold the output, then
*output_data_size is updated and @code{GNUTLS_E_SHORT_MEMORY_BUFFER}  will
be returned.  The output will normally be a SHA-1 hash output,
which is 20 bytes.

@strong{Returns:} In case of failure a negative error code will be
returned, and 0 on success.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_get_key_usage
@anchor{gnutls_pubkey_get_key_usage}
@deftypefun {int} {gnutls_pubkey_get_key_usage} (gnutls_pubkey_t @var{key}, unsigned int * @var{usage})
@var{key}: should contain a @code{gnutls_pubkey_t}  type

@var{usage}: If set will return the number of bits of the parameters (may be NULL)

This function will return the key usage of the public key.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_get_openpgp_key_id
@anchor{gnutls_pubkey_get_openpgp_key_id}
@deftypefun {int} {gnutls_pubkey_get_openpgp_key_id} (gnutls_pubkey_t @var{key}, unsigned int @var{flags}, unsigned char * @var{output_data}, size_t * @var{output_data_size}, unsigned int * @var{subkey})
@var{key}: Holds the public key

@var{flags}: should be one of the flags from @code{gnutls_keyid_flags_t} 

@var{output_data}: will contain the key ID

@var{output_data_size}: holds the size of output_data (and will be
replaced by the actual size of parameters)

@var{subkey}: ignored

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_get_pk_algorithm
@anchor{gnutls_pubkey_get_pk_algorithm}
@deftypefun {int} {gnutls_pubkey_get_pk_algorithm} (gnutls_pubkey_t @var{key}, unsigned int * @var{bits})
@var{key}: should contain a @code{gnutls_pubkey_t}  type

@var{bits}: If set will return the number of bits of the parameters (may be NULL)

This function will return the public key algorithm of a public
key and if possible will return a number of bits that indicates
the security parameter of the key.

@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t}  enumeration on
success, or a negative error code on error.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_get_preferred_hash_algorithm
@anchor{gnutls_pubkey_get_preferred_hash_algorithm}
@deftypefun {int} {gnutls_pubkey_get_preferred_hash_algorithm} (gnutls_pubkey_t @var{key}, gnutls_digest_algorithm_t *         @var{hash}, unsigned int * @var{mand})
@var{key}: Holds the certificate

@var{hash}: The result of the call with the hash algorithm used for signature

@var{mand}: If non zero it means that the algorithm MUST use this hash. May be NULL.

This function will read the certificate and return the appropriate digest
algorithm to use for signing with this certificate. Some certificates (i.e.
DSA might not be able to sign without the preferred algorithm).

To get the signature algorithm instead of just the hash use @code{gnutls_pk_to_sign()} 
with the algorithm of the certificate/key and the provided  @code{hash} .

@strong{Returns:} the 0 if the hash algorithm is found. A negative error code is
returned on error.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_get_spki
@anchor{gnutls_pubkey_get_spki}
@deftypefun {int} {gnutls_pubkey_get_spki} (gnutls_pubkey_t @var{pubkey}, gnutls_x509_spki_t @var{spki}, unsigned int @var{flags})
@var{pubkey}: a public key of type @code{gnutls_pubkey_t} 

@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_pubkey_spki_t} 

@var{flags}: must be zero

This function will return the public key information if available.
The provided  @code{spki} must be initialized.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_pubkey_import
@anchor{gnutls_pubkey_import}
@deftypefun {int} {gnutls_pubkey_import} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format})
@var{key}: The public key. 

@var{data}: The DER or PEM encoded certificate. 

@var{format}: One of DER or PEM 

This function will import the provided public key in
a SubjectPublicKeyInfo X.509 structure to a native
@code{gnutls_pubkey_t}  type. The output will be stored 
in  @code{key} . If the public key is PEM encoded it should have a header 
of "PUBLIC KEY". 

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_import_dsa_raw
@anchor{gnutls_pubkey_import_dsa_raw}
@deftypefun {int} {gnutls_pubkey_import_dsa_raw} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{p}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{g}, const gnutls_datum_t * @var{y})
@var{key}: The structure to store the parsed key

@var{p}: holds the p

@var{q}: holds the q

@var{g}: holds the g

@var{y}: holds the y

This function will convert the given DSA raw parameters to the
native @code{gnutls_pubkey_t}  format.  The output will be stored
in  @code{key} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_import_ecc_raw
@anchor{gnutls_pubkey_import_ecc_raw}
@deftypefun {int} {gnutls_pubkey_import_ecc_raw} (gnutls_pubkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y})
@var{key}: The structure to store the parsed key

@var{curve}: holds the curve

@var{x}: holds the x-coordinate

@var{y}: holds the y-coordinate

This function will convert the given elliptic curve parameters to a
@code{gnutls_pubkey_t} .  The output will be stored in  @code{key} .

In EdDSA curves the  @code{y} parameter should be @code{NULL}  and the  @code{x} parameter must
be the value in the native format for the curve.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pubkey_import_ecc_x962
@anchor{gnutls_pubkey_import_ecc_x962}
@deftypefun {int} {gnutls_pubkey_import_ecc_x962} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{parameters}, const gnutls_datum_t * @var{ecpoint})
@var{key}: The structure to store the parsed key

@var{parameters}: DER encoding of an ANSI X9.62 parameters

@var{ecpoint}: DER encoding of ANSI X9.62 ECPoint

This function will convert the given elliptic curve parameters to a
@code{gnutls_pubkey_t} .  The output will be stored in  @code{key} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pubkey_import_gost_raw
@anchor{gnutls_pubkey_import_gost_raw}
@deftypefun {int} {gnutls_pubkey_import_gost_raw} (gnutls_pubkey_t @var{key}, gnutls_ecc_curve_t @var{curve}, gnutls_digest_algorithm_t @var{digest}, gnutls_gost_paramset_t @var{paramset}, const gnutls_datum_t * @var{x}, const gnutls_datum_t * @var{y})
@var{key}: The structure to store the parsed key

@var{curve}: holds the curve

@var{digest}: holds the digest

@var{paramset}: holds the parameters id

@var{x}: holds the x-coordinate

@var{y}: holds the y-coordinate

This function will convert the given GOST public key's parameters to a
@code{gnutls_pubkey_t} .  The output will be stored in  @code{key} .   @code{digest} should be
one of GNUTLS_DIG_GOSR_94, GNUTLS_DIG_STREEBOG_256 or
GNUTLS_DIG_STREEBOG_512.  If  @code{paramset} is set to GNUTLS_GOST_PARAMSET_UNKNOWN
default one will be selected depending on  @code{digest} .

@strong{Note:} parameters should be stored with least significant byte first. On
version 3.6.3 big-endian format was used incorrectly.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.3
@end deftypefun

@subheading gnutls_pubkey_import_openpgp
@anchor{gnutls_pubkey_import_openpgp}
@deftypefun {int} {gnutls_pubkey_import_openpgp} (gnutls_pubkey_t @var{key}, gnutls_openpgp_crt_t @var{crt}, unsigned int @var{flags})
@var{key}: The public key

@var{crt}: The certificate to be imported

@var{flags}: should be zero

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_import_openpgp_raw
@anchor{gnutls_pubkey_import_openpgp_raw}
@deftypefun {int} {gnutls_pubkey_import_openpgp_raw} (gnutls_pubkey_t @var{pkey}, const gnutls_datum_t * @var{data}, gnutls_openpgp_crt_fmt_t          @var{format}, const gnutls_openpgp_keyid_t          @var{keyid}, unsigned int @var{flags})
@var{pkey}: The public key

@var{data}: The public key data to be imported

@var{format}: The format of the public key

@var{keyid}: The key id to use (optional)

@var{flags}: Should be zero

This function is no-op.

@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} .

@strong{Since:} 3.1.3
@end deftypefun

@subheading gnutls_pubkey_import_pkcs11
@anchor{gnutls_pubkey_import_pkcs11}
@deftypefun {int} {gnutls_pubkey_import_pkcs11} (gnutls_pubkey_t @var{key}, gnutls_pkcs11_obj_t @var{obj}, unsigned int @var{flags})
@var{key}: The public key

@var{obj}: The parameters to be imported

@var{flags}: should be zero

Imports a public key from a pkcs11 key. This function will import
the given public key to the abstract @code{gnutls_pubkey_t}  type.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_import_privkey
@anchor{gnutls_pubkey_import_privkey}
@deftypefun {int} {gnutls_pubkey_import_privkey} (gnutls_pubkey_t @var{key}, gnutls_privkey_t @var{pkey}, unsigned int @var{usage}, unsigned int @var{flags})
@var{key}: The public key

@var{pkey}: The private key

@var{usage}: GNUTLS_KEY_* key usage flags.

@var{flags}: should be zero

Imports the public key from a private.  This function will import
the given public key to the abstract @code{gnutls_pubkey_t}  type.

Note that in certain keys this operation may not be possible, e.g.,
in other than RSA PKCS@code{11}  keys.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_import_rsa_raw
@anchor{gnutls_pubkey_import_rsa_raw}
@deftypefun {int} {gnutls_pubkey_import_rsa_raw} (gnutls_pubkey_t @var{key}, const gnutls_datum_t * @var{m}, const gnutls_datum_t * @var{e})
@var{key}: The key

@var{m}: holds the modulus

@var{e}: holds the public exponent

This function will replace the parameters in the given structure.
The new parameters should be stored in the appropriate
gnutls_datum.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, or an negative error code.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_import_tpm_raw
@anchor{gnutls_pubkey_import_tpm_raw}
@deftypefun {int} {gnutls_pubkey_import_tpm_raw} (gnutls_pubkey_t @var{pkey}, const gnutls_datum_t * @var{fdata}, gnutls_tpmkey_fmt_t @var{format}, const char * @var{srk_password}, unsigned int @var{flags})
@var{pkey}: The public key

@var{fdata}: The TPM key to be imported

@var{format}: The format of the private key

@var{srk_password}: The password for the SRK key (optional)

@var{flags}: One of the GNUTLS_PUBKEY_* flags

This function will import the public key from the provided TPM key
structure.

With respect to passwords the same as in
@code{gnutls_pubkey_import_tpm_url()}  apply.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_pubkey_import_tpm_url
@anchor{gnutls_pubkey_import_tpm_url}
@deftypefun {int} {gnutls_pubkey_import_tpm_url} (gnutls_pubkey_t @var{pkey}, const char * @var{url}, const char * @var{srk_password}, unsigned int @var{flags})
@var{pkey}: The public key

@var{url}: The URL of the TPM key to be imported

@var{srk_password}: The password for the SRK key (optional)

@var{flags}: should be zero

This function will import the given private key to the abstract
@code{gnutls_privkey_t}  type. 

Note that unless @code{GNUTLS_PUBKEY_DISABLE_CALLBACKS} 
is specified, if incorrect (or NULL) passwords are given
the PKCS11 callback functions will be used to obtain the
correct passwords. Otherwise if the SRK password is wrong
@code{GNUTLS_E_TPM_SRK_PASSWORD_ERROR}  is returned.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_pubkey_import_url
@anchor{gnutls_pubkey_import_url}
@deftypefun {int} {gnutls_pubkey_import_url} (gnutls_pubkey_t @var{key}, const char * @var{url}, unsigned int @var{flags})
@var{key}: A key of type @code{gnutls_pubkey_t} 

@var{url}: A PKCS 11 url

@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags

This function will import a public key from the provided URL.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_pubkey_import_x509
@anchor{gnutls_pubkey_import_x509}
@deftypefun {int} {gnutls_pubkey_import_x509} (gnutls_pubkey_t @var{key}, gnutls_x509_crt_t @var{crt}, unsigned int @var{flags})
@var{key}: The public key

@var{crt}: The certificate to be imported

@var{flags}: should be zero

This function will import the given public key to the abstract
@code{gnutls_pubkey_t}  type.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_import_x509_crq
@anchor{gnutls_pubkey_import_x509_crq}
@deftypefun {int} {gnutls_pubkey_import_x509_crq} (gnutls_pubkey_t @var{key}, gnutls_x509_crq_t @var{crq}, unsigned int @var{flags})
@var{key}: The public key

@var{crq}: The certificate to be imported

@var{flags}: should be zero

This function will import the given public key to the abstract
@code{gnutls_pubkey_t}  type.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.5
@end deftypefun

@subheading gnutls_pubkey_import_x509_raw
@anchor{gnutls_pubkey_import_x509_raw}
@deftypefun {int} {gnutls_pubkey_import_x509_raw} (gnutls_pubkey_t @var{pkey}, const gnutls_datum_t * @var{data}, gnutls_x509_crt_fmt_t @var{format}, unsigned int @var{flags})
@var{pkey}: The public key

@var{data}: The public key data to be imported

@var{format}: The format of the public key

@var{flags}: should be zero

This function will import the given public key to the abstract
@code{gnutls_pubkey_t}  type. 

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.3
@end deftypefun

@subheading gnutls_pubkey_init
@anchor{gnutls_pubkey_init}
@deftypefun {int} {gnutls_pubkey_init} (gnutls_pubkey_t * @var{key})
@var{key}: A pointer to the type to be initialized

This function will initialize a public key.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_print
@anchor{gnutls_pubkey_print}
@deftypefun {int} {gnutls_pubkey_print} (gnutls_pubkey_t @var{pubkey}, gnutls_certificate_print_formats_t @var{format}, gnutls_datum_t * @var{out})
@var{pubkey}: The data to be printed

@var{format}: Indicate the format to use

@var{out}: Newly allocated datum with null terminated string.

This function will pretty print public key information, suitable for
display to a human.

Only @code{GNUTLS_CRT_PRINT_FULL}  and @code{GNUTLS_CRT_PRINT_FULL_NUMBERS} 
are implemented.

The output  @code{out} needs to be deallocated using @code{gnutls_free()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.1.5
@end deftypefun

@subheading gnutls_pubkey_set_key_usage
@anchor{gnutls_pubkey_set_key_usage}
@deftypefun {int} {gnutls_pubkey_set_key_usage} (gnutls_pubkey_t @var{key}, unsigned int @var{usage})
@var{key}: a certificate of type @code{gnutls_x509_crt_t} 

@var{usage}: an ORed sequence of the GNUTLS_KEY_* elements.

This function will set the key usage flags of the public key. This
is only useful if the key is to be exported to a certificate or
certificate request.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_pubkey_set_pin_function
@anchor{gnutls_pubkey_set_pin_function}
@deftypefun {void} {gnutls_pubkey_set_pin_function} (gnutls_pubkey_t @var{key}, gnutls_pin_callback_t @var{fn}, void * @var{userdata})
@var{key}: A key of type @code{gnutls_pubkey_t} 

@var{fn}: the callback

@var{userdata}: data associated with the callback

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

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

@strong{Since:} 3.1.0
@end deftypefun

@subheading gnutls_pubkey_set_spki
@anchor{gnutls_pubkey_set_spki}
@deftypefun {int} {gnutls_pubkey_set_spki} (gnutls_pubkey_t @var{pubkey}, const gnutls_x509_spki_t @var{spki}, unsigned int @var{flags})
@var{pubkey}: a public key of type @code{gnutls_pubkey_t} 

@var{spki}: a SubjectPublicKeyInfo structure of type @code{gnutls_pubkey_spki_t} 

@var{flags}: must be zero

This function will set the public key information.
The provided  @code{spki} must be initialized.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_pubkey_verify_data2
@anchor{gnutls_pubkey_verify_data2}
@deftypefun {int} {gnutls_pubkey_verify_data2} (gnutls_pubkey_t @var{pubkey}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{data}, const gnutls_datum_t * @var{signature})
@var{pubkey}: Holds the public key

@var{algo}: The signature algorithm used

@var{flags}: Zero or an OR list of @code{gnutls_certificate_verify_flags} 

@var{data}: holds the signed data

@var{signature}: contains the signature

This function will verify the given signed data, using the
parameters from the certificate.

@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}  
is returned, and zero or positive code on success. For known to be insecure
signatures this function will return @code{GNUTLS_E_INSUFFICIENT_SECURITY}  unless
the flag @code{GNUTLS_VERIFY_ALLOW_BROKEN}  is specified.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pubkey_verify_hash2
@anchor{gnutls_pubkey_verify_hash2}
@deftypefun {int} {gnutls_pubkey_verify_hash2} (gnutls_pubkey_t @var{key}, gnutls_sign_algorithm_t @var{algo}, unsigned int @var{flags}, const gnutls_datum_t * @var{hash}, const gnutls_datum_t * @var{signature})
@var{key}: Holds the public key

@var{algo}: The signature algorithm used

@var{flags}: Zero or an OR list of @code{gnutls_certificate_verify_flags} 

@var{hash}: holds the hash digest to be verified

@var{signature}: contains the signature

This function will verify the given signed digest, using the
parameters from the public key. Note that unlike @code{gnutls_privkey_sign_hash()} ,
this function accepts a signature algorithm instead of a digest algorithm.
You can use @code{gnutls_pk_to_sign()}  to get the appropriate value.

@strong{Returns:} In case of a verification failure @code{GNUTLS_E_PK_SIG_VERIFY_FAILED}  
is returned, and zero or positive code on success. For known to be insecure
signatures this function will return @code{GNUTLS_E_INSUFFICIENT_SECURITY}  unless
the flag @code{GNUTLS_VERIFY_ALLOW_BROKEN}  is specified.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_pubkey_verify_params
@anchor{gnutls_pubkey_verify_params}
@deftypefun {int} {gnutls_pubkey_verify_params} (gnutls_pubkey_t @var{key})
@var{key}: should contain a @code{gnutls_pubkey_t}  type

This function will verify the public key parameters.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.3.0
@end deftypefun

@subheading gnutls_register_custom_url
@anchor{gnutls_register_custom_url}
@deftypefun {int} {gnutls_register_custom_url} (const gnutls_custom_url_st * @var{st})
@var{st}: A @code{gnutls_custom_url_st}  structure

Register a custom URL. This will affect the following functions:
@code{gnutls_url_is_supported()} , @code{gnutls_privkey_import_url()} ,
gnutls_pubkey_import_url, @code{gnutls_x509_crt_import_url()}  
and all functions that depend on
them, e.g., @code{gnutls_certificate_set_x509_key_file2()} .

The provided structure and callback functions must be valid throughout
the lifetime of the process. The registration of an existing URL type
will fail with @code{GNUTLS_E_INVALID_REQUEST} . Since GnuTLS 3.5.0 this function
can be used to override the builtin URLs.

This function is not thread safe.

@strong{Returns:} returns zero if the given structure was imported or a negative value otherwise.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_system_key_add_x509
@anchor{gnutls_system_key_add_x509}
@deftypefun {int} {gnutls_system_key_add_x509} (gnutls_x509_crt_t @var{crt}, gnutls_x509_privkey_t @var{privkey}, const char * @var{label}, char ** @var{cert_url}, char ** @var{key_url})
@var{crt}: the certificate to be added

@var{privkey}: the key to be added

@var{label}: the friendly name to describe the key

@var{cert_url}: if non-NULL it will contain an allocated value with the certificate URL

@var{key_url}: if non-NULL it will contain an allocated value with the key URL

This function will added the given key and certificate pair,
to the system list.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_system_key_delete
@anchor{gnutls_system_key_delete}
@deftypefun {int} {gnutls_system_key_delete} (const char * @var{cert_url}, const char * @var{key_url})
@var{cert_url}: the URL of the certificate

@var{key_url}: the URL of the key

This function will delete the key and certificate pair.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_system_key_iter_deinit
@anchor{gnutls_system_key_iter_deinit}
@deftypefun {void} {gnutls_system_key_iter_deinit} (gnutls_system_key_iter_t @var{iter})
@var{iter}: an iterator of system keys

This function will deinitialize the iterator.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_system_key_iter_get_info
@anchor{gnutls_system_key_iter_get_info}
@deftypefun {int} {gnutls_system_key_iter_get_info} (gnutls_system_key_iter_t * @var{iter}, unsigned @var{cert_type}, char ** @var{cert_url}, char ** @var{key_url}, char ** @var{label}, gnutls_datum_t * @var{der}, unsigned int @var{flags})
@var{iter}: an iterator of the system keys (must be set to @code{NULL}  initially)

@var{cert_type}: A value of gnutls_certificate_type_t which indicates the type of certificate to look for

@var{cert_url}: The certificate URL of the pair (may be @code{NULL} )

@var{key_url}: The key URL of the pair (may be @code{NULL} )

@var{label}: The friendly name (if any) of the pair (may be @code{NULL} )

@var{der}: if non-NULL the DER data of the certificate

@var{flags}: should be zero

This function will return on each call a certificate
and key pair URLs, as well as a label associated with them,
and the DER-encoded certificate. When the iteration is complete it will
return @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} .

Typically  @code{cert_type} should be @code{GNUTLS_CRT_X509} .

All values set are allocated and must be cleared using @code{gnutls_free()} ,

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_x509_crl_privkey_sign
@anchor{gnutls_x509_crl_privkey_sign}
@deftypefun {int} {gnutls_x509_crl_privkey_sign} (gnutls_x509_crl_t @var{crl}, gnutls_x509_crt_t @var{issuer}, gnutls_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
@var{crl}: should contain a gnutls_x509_crl_t type

@var{issuer}: is the certificate of the certificate issuer

@var{issuer_key}: holds the issuer's private key

@var{dig}: The message digest to use. GNUTLS_DIG_SHA256 is the safe choice unless you know what you're doing.

@var{flags}: must be 0

This function will sign the CRL with the issuer's private key, and
will copy the issuer's information into the CRL.

This must be the last step in a certificate CRL since all
the previously set parameters are now signed.

A known limitation of this function is, that a newly-signed CRL will not
be fully functional (e.g., for signature verification), until it
is exported an re-imported.

After GnuTLS 3.6.1 the value of  @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} ,
and in that case, a suitable but reasonable for the key algorithm will be selected.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

Since 2.12.0
@end deftypefun

@subheading gnutls_x509_crq_privkey_sign
@anchor{gnutls_x509_crq_privkey_sign}
@deftypefun {int} {gnutls_x509_crq_privkey_sign} (gnutls_x509_crq_t @var{crq}, gnutls_privkey_t @var{key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
@var{crq}: should contain a @code{gnutls_x509_crq_t}  type

@var{key}: holds a private key

@var{dig}: The message digest to use, i.e., @code{GNUTLS_DIG_SHA1} 

@var{flags}: must be 0

This function will sign the certificate request with a private key.
This must be the same key as the one used in
@code{gnutls_x509_crt_set_key()}  since a certificate request is self
signed.

This must be the last step in a certificate request generation
since all the previously set parameters are now signed.

A known limitation of this function is, that a newly-signed request will not
be fully functional (e.g., for signature verification), until it
is exported an re-imported.

After GnuTLS 3.6.1 the value of  @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} ,
and in that case, a suitable but reasonable for the key algorithm will be selected.

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.
@code{GNUTLS_E_ASN1_VALUE_NOT_FOUND}  is returned if you didn't set all
information in the certificate request (e.g., the version using
@code{gnutls_x509_crq_set_version()} ).

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_x509_crq_set_pubkey
@anchor{gnutls_x509_crq_set_pubkey}
@deftypefun {int} {gnutls_x509_crq_set_pubkey} (gnutls_x509_crq_t @var{crq}, gnutls_pubkey_t @var{key})
@var{crq}: should contain a @code{gnutls_x509_crq_t}  type

@var{key}: holds a public key

This function will set the public parameters from the given public
key to the request. The  @code{key} can be deallocated after that.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_x509_crt_privkey_sign
@anchor{gnutls_x509_crt_privkey_sign}
@deftypefun {int} {gnutls_x509_crt_privkey_sign} (gnutls_x509_crt_t @var{crt}, gnutls_x509_crt_t @var{issuer}, gnutls_privkey_t @var{issuer_key}, gnutls_digest_algorithm_t @var{dig}, unsigned int @var{flags})
@var{crt}: a certificate of type @code{gnutls_x509_crt_t} 

@var{issuer}: is the certificate of the certificate issuer

@var{issuer_key}: holds the issuer's private key

@var{dig}: The message digest to use, @code{GNUTLS_DIG_SHA256}  is a safe choice

@var{flags}: must be 0

This function will sign the certificate with the issuer's private key, and
will copy the issuer's information into the certificate.

This must be the last step in a certificate generation since all
the previously set parameters are now signed.

A known limitation of this function is, that a newly-signed certificate will not
be fully functional (e.g., for signature verification), until it
is exported an re-imported.

After GnuTLS 3.6.1 the value of  @code{dig} may be @code{GNUTLS_DIG_UNKNOWN} ,
and in that case, a suitable but reasonable for the key algorithm will be selected.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.
@end deftypefun

@subheading gnutls_x509_crt_set_pubkey
@anchor{gnutls_x509_crt_set_pubkey}
@deftypefun {int} {gnutls_x509_crt_set_pubkey} (gnutls_x509_crt_t @var{crt}, gnutls_pubkey_t @var{key})
@var{crt}: should contain a @code{gnutls_x509_crt_t}  type

@var{key}: holds a public key

This function will set the public parameters from the given public
key to the certificate. The  @code{key} can be deallocated after that.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a
negative error value.

@strong{Since:} 2.12.0
@end deftypefun