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