@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 *pcert_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{pcert} should contain an allocated list of certificates and public keys.

 @code{pcert_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{pkey} 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{pcert_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.

@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

@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