diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/abstract-api.texi | 2675 |
1 files changed, 2675 insertions, 0 deletions
diff --git a/doc/abstract-api.texi b/doc/abstract-api.texi new file mode 100644 index 0000000..9e25304 --- /dev/null +++ b/doc/abstract-api.texi @@ -0,0 +1,2675 @@ + +@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 + |