certificate list (chain) or raw public-key PCERT_LIST_SIZE: holds the size of the certificate list KEY: is a ‘gnutls_privkey_t’ key corresponding to the first public-key in pcert_list This function sets a public/private key pair in the gnutls_certificate_credentials_t type. The given public key may be encapsulated in a certificate or can be given as a raw key. This function may be called more than once, in case multiple key pairs exist for the server. For clients that want to send more than their own end- entity certificate (e.g., also an intermediate CA cert), the full certificate chain must be provided in ‘pcert_list’ . Note that the ‘key’ will become part of the credentials structure and must not be deallocated. It will be automatically deallocated when the ‘res’ structure is deinitialized. If this function fails, the ‘res’ structure is at an undefined state and it must not be reused to load other keys or certificates. Note that, this function by default returns zero on success and a negative value on error. Since 3.5.6, when the flag ‘GNUTLS_CERTIFICATE_API_V2’ is set using ‘gnutls_certificate_set_flags()’ it returns an index (greater or equal to zero). That index can be used for other functions to refer to the added key-pair. Since GnuTLS 3.6.6 this function also handles raw public keys. *Returns:* On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). *Since:* 3.0 gnutls_certificate_set_retrieve_function2 ----------------------------------------- -- Function: void gnutls_certificate_set_retrieve_function2 (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function2 * FUNC) CRED: is a ‘gnutls_certificate_credentials_t’ type. 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); ‘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 ‘gnutls_x509_rdn_get()’ . ‘pk_algos’ contains a list with server's acceptable public key algorithms. The certificate returned should support the server's given algorithms. ‘pcert’ should contain a single certificate and public key or a list of them. ‘pcert_length’ is the size of the previous list. ‘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. *Since:* 3.0 gnutls_certificate_set_retrieve_function3 ----------------------------------------- -- Function: void gnutls_certificate_set_retrieve_function3 (gnutls_certificate_credentials_t CRED, gnutls_certificate_retrieve_function3 * FUNC) CRED: is a ‘gnutls_certificate_credentials_t’ type. 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. ‘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: ‘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 ‘gnutls_x509_rdn_get()’ . ‘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: ‘certs’ should contain an allocated list of certificates and public keys. ‘certs_length’ is the size of the previous list. ‘ocsp’ should contain an allocated list of OCSP responses. ‘ocsp_length’ is the size of the previous list. ‘privkey’ is the private key. If flags in the callback are set to ‘GNUTLS_CERT_RETR_DEINIT_ALL’ then all provided values must be allocated using ‘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 ‘certs_length’ and ‘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, ‘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. *Since:* 3.6.3 gnutls_pcert_deinit ------------------- -- Function: void gnutls_pcert_deinit (gnutls_pcert_st * PCERT) PCERT: The structure to be deinitialized This function will deinitialize a pcert structure. *Since:* 3.0 gnutls_pcert_export_openpgp --------------------------- -- Function: int gnutls_pcert_export_openpgp (gnutls_pcert_st * PCERT, gnutls_openpgp_crt_t * CRT) PCERT: The pcert structure. CRT: An initialized ‘gnutls_openpgp_crt_t’ . This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 3.4.0 gnutls_pcert_export_x509 ------------------------ -- Function: int gnutls_pcert_export_x509 (gnutls_pcert_st * PCERT, gnutls_x509_crt_t * CRT) PCERT: The pcert structure. CRT: An initialized ‘gnutls_x509_crt_t’ . Converts the given ‘gnutls_pcert_t’ type into a ‘gnutls_x509_crt_t’ . This function only works if the type of ‘pcert’ is ‘GNUTLS_CRT_X509’ . When successful, the value written to ‘crt’ must be freed with ‘gnutls_x509_crt_deinit()’ when no longer needed. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pcert_import_openpgp --------------------------- -- Function: int gnutls_pcert_import_openpgp (gnutls_pcert_st * PCERT, gnutls_openpgp_crt_t CRT, unsigned int FLAGS) PCERT: The pcert structure CRT: The raw certificate to be imported FLAGS: zero for now This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 3.0 gnutls_pcert_import_openpgp_raw ------------------------------- -- Function: int gnutls_pcert_import_openpgp_raw (gnutls_pcert_st * PCERT, const gnutls_datum_t * CERT, gnutls_openpgp_crt_fmt_t FORMAT, gnutls_openpgp_keyid_t KEYID, unsigned int FLAGS) PCERT: The pcert structure CERT: The raw certificate to be imported FORMAT: The format of the certificate KEYID: The key ID to use (NULL for the master key) FLAGS: zero for now This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 3.0 gnutls_pcert_import_rawpk ------------------------- -- Function: int gnutls_pcert_import_rawpk (gnutls_pcert_st * PCERT, gnutls_pubkey_t PUBKEY, unsigned int FLAGS) PCERT: The pcert structure to import the data into. PUBKEY: The raw public-key in ‘gnutls_pubkey_t’ format to be imported FLAGS: zero for now This convenience function will import (i.e. convert) the given raw public key ‘pubkey’ into a ‘gnutls_pcert_st’ structure. The structure must be deinitialized afterwards using ‘gnutls_pcert_deinit()’ . The given ‘pubkey’ must not be deinitialized because it will be associated with the given ‘pcert’ structure and will be deinitialized with it. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.6 gnutls_pcert_import_rawpk_raw ----------------------------- -- Function: int gnutls_pcert_import_rawpk_raw (gnutls_pcert_st * PCERT, const gnutls_datum_t * RAWPUBKEY, gnutls_x509_crt_fmt_t FORMAT, unsigned int KEY_USAGE, unsigned int FLAGS) PCERT: The pcert structure to import the data into. RAWPUBKEY: The raw public-key in ‘gnutls_datum_t’ format to be imported. FORMAT: The format of the raw public-key. DER or PEM. KEY_USAGE: An ORed sequence of ‘GNUTLS_KEY_’ * flags. FLAGS: zero for now This convenience function will import (i.e. convert) the given raw public key ‘rawpubkey’ into a ‘gnutls_pcert_st’ structure. The structure must be deinitialized afterwards using ‘gnutls_pcert_deinit()’ . Note that the caller is responsible for freeing ‘rawpubkey’ . All necessary values will be copied into ‘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 ‘gnutls_x509_crt_get_key_usage()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.6 gnutls_pcert_import_x509 ------------------------ -- Function: int gnutls_pcert_import_x509 (gnutls_pcert_st * PCERT, gnutls_x509_crt_t CRT, unsigned int FLAGS) PCERT: The pcert structure CRT: The certificate to be imported FLAGS: zero for now This convenience function will import the given certificate to a ‘gnutls_pcert_st’ structure. The structure must be deinitialized afterwards using ‘gnutls_pcert_deinit()’ ; *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_pcert_import_x509_list ----------------------------- -- Function: int gnutls_pcert_import_x509_list (gnutls_pcert_st * PCERT_LIST, gnutls_x509_crt_t * CRT, unsigned * NCRT, unsigned int FLAGS) PCERT_LIST: The structures to store the certificates; must not contain initialized ‘gnutls_pcert_st’ structures. CRT: The certificates to be imported NCRT: The number of certificates in ‘crt’ ; will be updated if necessary FLAGS: zero or ‘GNUTLS_X509_CRT_LIST_SORT’ This convenience function will import the given certificates to an already allocated set of ‘gnutls_pcert_st’ structures. The structures must be deinitialized afterwards using ‘gnutls_pcert_deinit()’ . ‘pcert_list’ should contain space for at least ‘ncrt’ elements. In the case ‘GNUTLS_X509_CRT_LIST_SORT’ is specified and that function cannot sort the list, ‘GNUTLS_E_CERTIFICATE_LIST_UNSORTED’ will be returned. Currently sorting can fail if the list size exceeds an internal constraint (16). *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pcert_import_x509_raw ---------------------------- -- Function: int gnutls_pcert_import_x509_raw (gnutls_pcert_st * PCERT, const gnutls_datum_t * CERT, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS) PCERT: The pcert structure CERT: The raw certificate to be imported FORMAT: The format of the certificate FLAGS: zero for now This convenience function will import the given certificate to a ‘gnutls_pcert_st’ structure. The structure must be deinitialized afterwards using ‘gnutls_pcert_deinit()’ ; *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_pcert_list_import_x509_file ---------------------------------- -- Function: int gnutls_pcert_list_import_x509_file (gnutls_pcert_st * PCERT_LIST, unsigned * PCERT_LIST_SIZE, const char * FILE, gnutls_x509_crt_fmt_t FORMAT, gnutls_pin_callback_t PIN_FN, void * PIN_FN_USERDATA, unsigned int FLAGS) PCERT_LIST: The structures to store the certificates; must not contain initialized ‘gnutls_pcert_st’ structures. PCERT_LIST_SIZE: Initially must hold the maximum number of certs. It will be updated with the number of certs available. FILE: A file or supported URI with the certificates to load FORMAT: ‘GNUTLS_X509_FMT_DER’ or ‘GNUTLS_X509_FMT_PEM’ if a file is given PIN_FN: a PIN callback if not globally set PIN_FN_USERDATA: parameter for the PIN callback FLAGS: zero or flags from ‘gnutls_certificate_import_flags’ This convenience function will import a certificate chain from the given file or supported URI to ‘gnutls_pcert_st’ structures. The structures must be deinitialized afterwards using ‘gnutls_pcert_deinit()’ . This function will always return a sorted certificate chain. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value; if the ‘pcert’ list doesn't have enough space ‘GNUTLS_E_SHORT_MEMORY_BUFFER’ will be returned. *Since:* 3.6.3 gnutls_pcert_list_import_x509_raw --------------------------------- -- Function: int gnutls_pcert_list_import_x509_raw (gnutls_pcert_st * PCERT_LIST, unsigned int * PCERT_LIST_SIZE, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS) PCERT_LIST: The structures to store the certificates; must not contain initialized ‘gnutls_pcert_st’ structures. PCERT_LIST_SIZE: Initially must hold the maximum number of certs. It will be updated with the number of certs available. DATA: The certificates. FORMAT: One of DER or PEM. 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 ‘gnutls_pcert_st’ structures. The structures must be deinitialized afterwards using ‘gnutls_pcert_deinit()’ . ‘pcert_list’ should contain space for at least ‘pcert_list_size’ elements. If the Certificate is PEM encoded it should have a header of "X509 CERTIFICATE", or "CERTIFICATE". *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value; if the ‘pcert’ list doesn't have enough space ‘GNUTLS_E_SHORT_MEMORY_BUFFER’ will be returned. *Since:* 3.0 gnutls_privkey_decrypt_data --------------------------- -- Function: int gnutls_privkey_decrypt_data (gnutls_privkey_t KEY, unsigned int FLAGS, const gnutls_datum_t * CIPHERTEXT, gnutls_datum_t * PLAINTEXT) KEY: Holds the key FLAGS: zero for now CIPHERTEXT: holds the data to be decrypted PLAINTEXT: will contain the decrypted data, allocated with ‘gnutls_malloc()’ This function will decrypt the given data using the algorithm supported by the private key. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_privkey_decrypt_data2 ---------------------------- -- Function: int gnutls_privkey_decrypt_data2 (gnutls_privkey_t KEY, unsigned int FLAGS, const gnutls_datum_t * CIPHERTEXT, unsigned char * PLAINTEXT, size_t PLAINTEXT_SIZE) KEY: Holds the key FLAGS: zero for now CIPHERTEXT: holds the data to be decrypted PLAINTEXT: a preallocated buffer that will be filled with the plaintext 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 ‘gnutls_privkey_decrypt_data()’ this function operates in constant time and constant memory access. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.5 gnutls_privkey_deinit --------------------- -- Function: void gnutls_privkey_deinit (gnutls_privkey_t KEY) KEY: The key to be deinitialized This function will deinitialize a private key structure. *Since:* 2.12.0 gnutls_privkey_derive_secret ---------------------------- -- Function: int gnutls_privkey_derive_secret (gnutls_privkey_t PRIVKEY, gnutls_pubkey_t PUBKEY, const gnutls_datum_t * NONCE, gnutls_datum_t * SECRET, unsigned int FLAGS) PRIVKEY: a private key of type ‘gnutls_privkey_t’ PUBKEY: a public key of type ‘gnutls_pubkey_t’ NONCE: an optional nonce value SECRET: where shared secret will be stored FLAGS: must be zero This function will calculate a shared secret from our ‘privkey’ and peer's ‘pubkey’ . The result will be stored in ‘secret’ , whose data member should be freed after use using ‘gnutls_free()’ . ‘privkey’ and ‘pubkey’ must be backed by the X.509 keys. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.8.2 gnutls_privkey_export_dh_raw ---------------------------- -- Function: int gnutls_privkey_export_dh_raw (gnutls_privkey_t KEY, gnutls_dh_params_t PARAMS, gnutls_datum_t * Y, gnutls_datum_t * X, unsigned int FLAGS) KEY: Holds the private key PARAMS: will hold the Diffie-Hellman parameters (optional), must be initialized Y: will hold the y (optional) X: will hold the x FLAGS: flags from ‘gnutls_abstract_export_flags_t’ This function will export the Diffie-Hellman private key parameter found in the given ‘gnutls_privkey_t’ structure. The new parameter will be allocated using ‘gnutls_malloc()’ and will be stored in the appropriate datum. To retrieve other parameters common in both public key and private key, use ‘gnutls_dh_params_export_raw()’ . *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.8.2 gnutls_privkey_export_dsa_raw ----------------------------- -- Function: int gnutls_privkey_export_dsa_raw (gnutls_privkey_t KEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t * X) KEY: Holds the public key P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y 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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.3.0 gnutls_privkey_export_dsa_raw2 ------------------------------ -- Function: int gnutls_privkey_export_dsa_raw2 (gnutls_privkey_t KEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y, gnutls_datum_t * X, unsigned int FLAGS) KEY: Holds the public key P: will hold the p Q: will hold the q G: will hold the g Y: will hold the y X: will hold the x FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.0 gnutls_privkey_export_ecc_raw ----------------------------- -- Function: int gnutls_privkey_export_ecc_raw (gnutls_privkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t * Y, gnutls_datum_t * K) KEY: Holds the public key CURVE: will hold the curve X: will hold the x-coordinate Y: will hold the y-coordinate 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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. In EdDSA curves the ‘y’ parameter will be ‘NULL’ and the other parameters will be in the native format for the curve. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.3.0 gnutls_privkey_export_ecc_raw2 ------------------------------ -- Function: int gnutls_privkey_export_ecc_raw2 (gnutls_privkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t * Y, gnutls_datum_t * K, unsigned int FLAGS) KEY: Holds the public key CURVE: will hold the curve X: will hold the x-coordinate Y: will hold the y-coordinate K: will hold the private key FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. In EdDSA curves the ‘y’ parameter will be ‘NULL’ and the other parameters will be in the native format for the curve. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.0 gnutls_privkey_export_gost_raw2 ------------------------------- -- Function: int gnutls_privkey_export_gost_raw2 (gnutls_privkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_digest_algorithm_t * DIGEST, gnutls_gost_paramset_t * PARAMSET, gnutls_datum_t * X, gnutls_datum_t * Y, gnutls_datum_t * K, unsigned int FLAGS) KEY: Holds the public key CURVE: will hold the curve DIGEST: will hold the digest PARAMSET: will hold the GOST parameter set ID X: will hold the x-coordinate Y: will hold the y-coordinate K: will hold the private key FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. *Note:* parameters will be stored with least significant byte first. On version 3.6.3 this was incorrectly returned in big-endian format. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.3 gnutls_privkey_export_openpgp ----------------------------- -- Function: int gnutls_privkey_export_openpgp (gnutls_privkey_t PKEY, gnutls_openpgp_privkey_t * KEY) PKEY: The private key KEY: Location for the key to be exported. This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 3.4.0 gnutls_privkey_export_pkcs11 ---------------------------- -- Function: int gnutls_privkey_export_pkcs11 (gnutls_privkey_t PKEY, gnutls_pkcs11_privkey_t * KEY) PKEY: The private key KEY: Location for the key to be exported. Converts the given abstract private key to a ‘gnutls_pkcs11_privkey_t’ type. The key must be of type ‘GNUTLS_PRIVKEY_PKCS11’ . The key returned in ‘key’ must be deinitialized with ‘gnutls_pkcs11_privkey_deinit()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_privkey_export_rsa_raw ----------------------------- -- Function: int gnutls_privkey_export_rsa_raw (gnutls_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U, gnutls_datum_t * E1, gnutls_datum_t * E2) KEY: Holds the certificate M: will hold the modulus E: will hold the public exponent D: will hold the private exponent P: will hold the first prime (p) Q: will hold the second prime (q) U: will hold the coefficient E1: will hold e1 = d mod (p-1) 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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. For EdDSA keys, the ‘y’ value should be ‘NULL’ . *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.3.0 gnutls_privkey_export_rsa_raw2 ------------------------------ -- Function: int gnutls_privkey_export_rsa_raw2 (gnutls_privkey_t KEY, gnutls_datum_t * M, gnutls_datum_t * E, gnutls_datum_t * D, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * U, gnutls_datum_t * E1, gnutls_datum_t * E2, unsigned int FLAGS) KEY: Holds the certificate M: will hold the modulus E: will hold the public exponent D: will hold the private exponent P: will hold the first prime (p) Q: will hold the second prime (q) U: will hold the coefficient E1: will hold e1 = d mod (p-1) E2: will hold e2 = d mod (q-1) FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.0 gnutls_privkey_export_x509 -------------------------- -- Function: int gnutls_privkey_export_x509 (gnutls_privkey_t PKEY, gnutls_x509_privkey_t * KEY) PKEY: The private key KEY: Location for the key to be exported. Converts the given abstract private key to a ‘gnutls_x509_privkey_t’ type. The abstract key must be of type ‘GNUTLS_PRIVKEY_X509’ . The input ‘key’ must not be initialized. The key returned in ‘key’ should be deinitialized using ‘gnutls_x509_privkey_deinit()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_privkey_generate ----------------------- -- Function: int gnutls_privkey_generate (gnutls_privkey_t PKEY, gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned int FLAGS) PKEY: An initialized private key ALGO: is one of the algorithms in ‘gnutls_pk_algorithm_t’ . BITS: the size of the parameters to generate FLAGS: Must be zero or flags from ‘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 ‘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 ‘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 ‘GNUTLS_CURVE_TO_BITS()’ macro. The input to the macro is any curve from ‘gnutls_ecc_curve_t’ . For DSA keys, if the subgroup size needs to be specified check the ‘GNUTLS_SUBGROUP_TO_BITS()’ macro. It is recommended to do not set the number of ‘bits’ directly, use ‘gnutls_sec_param_to_pk_bits()’ instead . See also ‘gnutls_privkey_generate2()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.3.0 gnutls_privkey_generate2 ------------------------ -- Function: int gnutls_privkey_generate2 (gnutls_privkey_t PKEY, gnutls_pk_algorithm_t ALGO, unsigned int BITS, unsigned int FLAGS, const gnutls_keygen_data_st * DATA, unsigned DATA_SIZE) PKEY: The private key ALGO: is one of the algorithms in ‘gnutls_pk_algorithm_t’ . BITS: the size of the modulus FLAGS: Must be zero or flags from ‘gnutls_privkey_flags_t’ . DATA: Allow specifying ‘gnutls_keygen_data_st’ types such as the seed to be used. DATA_SIZE: The number of ‘data’ available. This function will generate a random private key. Note that this function must be called on an initialized private key. The flag ‘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 ‘data’ with a ‘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 ‘GNUTLS_CURVE_TO_BITS()’ macro. To export the generated keys in memory or in files it is recommended to use the PKCS‘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 ‘gnutls_privkey_export_x509()’ , and then with ‘gnutls_x509_privkey_export2_pkcs8()’ . If key generation is part of your application, avoid setting the number of bits directly, and instead use ‘gnutls_sec_param_to_pk_bits()’ . That way the generated keys will adapt to the security levels of the underlying GnuTLS library. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.5.0 gnutls_privkey_get_pk_algorithm ------------------------------- -- Function: int gnutls_privkey_get_pk_algorithm (gnutls_privkey_t KEY, unsigned int * BITS) KEY: should contain a ‘gnutls_privkey_t’ type 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. *Returns:* a member of the ‘gnutls_pk_algorithm_t’ enumeration on success, or a negative error code on error. *Since:* 2.12.0 gnutls_privkey_get_seed ----------------------- -- Function: int gnutls_privkey_get_seed (gnutls_privkey_t KEY, gnutls_digest_algorithm_t * DIGEST, void * SEED, size_t * SEED_SIZE) KEY: should contain a ‘gnutls_privkey_t’ type DIGEST: if non-NULL it will contain the digest algorithm used for key generation (if applicable) SEED: where seed will be copied to SEED_SIZE: originally holds the size of ‘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. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.5.0 gnutls_privkey_get_spki ----------------------- -- Function: int gnutls_privkey_get_spki (gnutls_privkey_t PRIVKEY, gnutls_x509_spki_t SPKI, unsigned int FLAGS) PRIVKEY: a public key of type ‘gnutls_privkey_t’ SPKI: a SubjectPublicKeyInfo structure of type ‘gnutls_privkey_spki_t’ FLAGS: must be zero This function will return the public key information if available. The provided ‘spki’ must be initialized. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.0 gnutls_privkey_get_type ----------------------- -- Function: gnutls_privkey_type_t gnutls_privkey_get_type (gnutls_privkey_t KEY) KEY: should contain a ‘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. *Returns:* a member of the ‘gnutls_privkey_type_t’ enumeration on success, or a negative error code on error. *Since:* 2.12.0 gnutls_privkey_import_dh_raw ---------------------------- -- Function: int gnutls_privkey_import_dh_raw (gnutls_privkey_t KEY, const gnutls_dh_params_t PARAMS, const gnutls_datum_t * Y, const gnutls_datum_t * X) KEY: The structure to store the parsed key PARAMS: holds the ‘gnutls_dh_params_t’ Y: holds the y (optional) X: holds the x This function will convert the given Diffie-Hellman raw parameters to the native ‘gnutls_privkey_t’ format. The output will be stored in ‘key’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.8.2 gnutls_privkey_import_dsa_raw ----------------------------- -- Function: int gnutls_privkey_import_dsa_raw (gnutls_privkey_t KEY, const gnutls_datum_t * P, const gnutls_datum_t * Q, const gnutls_datum_t * G, const gnutls_datum_t * Y, const gnutls_datum_t * X) KEY: The structure to store the parsed key P: holds the p Q: holds the q G: holds the g Y: holds the y (optional) X: holds the x This function will convert the given DSA raw parameters to the native ‘gnutls_privkey_t’ format. The output will be stored in ‘key’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_privkey_import_ecc_raw ----------------------------- -- Function: int gnutls_privkey_import_ecc_raw (gnutls_privkey_t KEY, gnutls_ecc_curve_t CURVE, const gnutls_datum_t * X, const gnutls_datum_t * Y, const gnutls_datum_t * K) KEY: The key CURVE: holds the curve X: holds the x-coordinate Y: holds the y-coordinate K: holds the k (private key) This function will convert the given elliptic curve parameters to the native ‘gnutls_privkey_t’ format. The output will be stored in ‘key’ . In EdDSA curves the ‘y’ parameter should be ‘NULL’ and the ‘x’ and ‘k’ parameters must be in the native format for the curve. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_privkey_import_ext ------------------------- -- Function: int gnutls_privkey_import_ext (gnutls_privkey_t PKEY, gnutls_pk_algorithm_t PK, void * USERDATA, gnutls_privkey_sign_func SIGN_FUNC, gnutls_privkey_decrypt_func DECRYPT_FUNC, unsigned int FLAGS) PKEY: The private key PK: The public key algorithm USERDATA: private data to be provided to the callbacks SIGN_FUNC: callback for signature operations DECRYPT_FUNC: callback for decryption operations FLAGS: Flags for the import This function will associate the given callbacks with the ‘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 ‘1’ 1.5 padding and the exponentiation. See also ‘gnutls_privkey_import_ext3()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_privkey_import_ext2 -------------------------- -- Function: int gnutls_privkey_import_ext2 (gnutls_privkey_t PKEY, gnutls_pk_algorithm_t PK, void * USERDATA, gnutls_privkey_sign_func SIGN_FN, gnutls_privkey_decrypt_func DECRYPT_FN, gnutls_privkey_deinit_func DEINIT_FN, unsigned int FLAGS) PKEY: The private key PK: The public key algorithm USERDATA: private data to be provided to the callbacks SIGN_FN: callback for signature operations DECRYPT_FN: callback for decryption operations DEINIT_FN: a deinitialization function FLAGS: Flags for the import This function will associate the given callbacks with the ‘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 ‘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 ‘1’ 1.5 padding and the exponentiation. See also ‘gnutls_privkey_import_ext3()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1 gnutls_privkey_import_ext3 -------------------------- -- Function: int gnutls_privkey_import_ext3 (gnutls_privkey_t PKEY, void * USERDATA, gnutls_privkey_sign_func SIGN_FN, gnutls_privkey_decrypt_func DECRYPT_FN, gnutls_privkey_deinit_func DEINIT_FN, gnutls_privkey_info_func INFO_FN, unsigned int FLAGS) PKEY: The private key USERDATA: private data to be provided to the callbacks SIGN_FN: callback for signature operations DECRYPT_FN: callback for decryption operations DEINIT_FN: a deinitialization function INFO_FN: returns info about the public key algorithm (should not be ‘NULL’ ) FLAGS: Flags for the import This function will associate the given callbacks with the ‘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 ‘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 ‘1’ 1.5 padding and the exponentiation. The ‘info_fn’ must provide information on the algorithms supported by this private key, and should support the flags ‘GNUTLS_PRIVKEY_INFO_PK_ALGO’ and ‘GNUTLS_PRIVKEY_INFO_SIGN_ALGO’ . It must return -1 on unknown flags. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_privkey_import_ext4 -------------------------- -- Function: int gnutls_privkey_import_ext4 (gnutls_privkey_t PKEY, void * USERDATA, gnutls_privkey_sign_data_func SIGN_DATA_FN, gnutls_privkey_sign_hash_func SIGN_HASH_FN, gnutls_privkey_decrypt_func DECRYPT_FN, gnutls_privkey_deinit_func DEINIT_FN, gnutls_privkey_info_func INFO_FN, unsigned int FLAGS) PKEY: The private key USERDATA: private data to be provided to the callbacks SIGN_DATA_FN: callback for signature operations (may be ‘NULL’ ) SIGN_HASH_FN: callback for signature operations (may be ‘NULL’ ) DECRYPT_FN: callback for decryption operations (may be ‘NULL’ ) DEINIT_FN: a deinitialization function INFO_FN: returns info about the public key algorithm (should not be ‘NULL’ ) FLAGS: Flags for the import This function will associate the given callbacks with the ‘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 ‘GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE’ . Note that in contrast with the signing function of ‘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 ‘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‘1’ signatures, the signature algorithm can be set to ‘GNUTLS_SIGN_RSA_RAW’ , and in that case the data should be handled as if they were an RSA PKCS‘1’ DigestInfo structure. The ‘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 ‘sign_data_fn’ and ‘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 ‘info_fn’ must provide information on the signature algorithms supported by this private key, and should support the flags ‘GNUTLS_PRIVKEY_INFO_PK_ALGO’ , ‘GNUTLS_PRIVKEY_INFO_HAVE_SIGN_ALGO’ and ‘GNUTLS_PRIVKEY_INFO_PK_ALGO_BITS’ . It must return -1 on unknown flags. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.0 gnutls_privkey_import_gost_raw ------------------------------ -- Function: int gnutls_privkey_import_gost_raw (gnutls_privkey_t KEY, gnutls_ecc_curve_t CURVE, gnutls_digest_algorithm_t DIGEST, gnutls_gost_paramset_t PARAMSET, const gnutls_datum_t * X, const gnutls_datum_t * Y, const gnutls_datum_t * K) KEY: The key CURVE: holds the curve DIGEST: holds the digest PARAMSET: holds the GOST parameter set ID X: holds the x-coordinate Y: holds the y-coordinate K: holds the k (private key) This function will convert the given GOST private key's parameters to the native ‘gnutls_privkey_t’ format. The output will be stored in ‘key’ . ‘digest’ should be one of GNUTLS_DIG_GOSR_94, GNUTLS_DIG_STREEBOG_256 or GNUTLS_DIG_STREEBOG_512. If ‘paramset’ is set to GNUTLS_GOST_PARAMSET_UNKNOWN default one will be selected depending on ‘digest’ . *Note:* parameters should be stored with least significant byte first. On version 3.6.3 big-endian format was used incorrectly. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.3 gnutls_privkey_import_openpgp ----------------------------- -- Function: int gnutls_privkey_import_openpgp (gnutls_privkey_t PKEY, gnutls_openpgp_privkey_t KEY, unsigned int FLAGS) PKEY: The private key KEY: The private key to be imported FLAGS: Flags for the import This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 2.12.0 gnutls_privkey_import_openpgp_raw --------------------------------- -- Function: int gnutls_privkey_import_openpgp_raw (gnutls_privkey_t PKEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT, const gnutls_openpgp_keyid_t KEYID, const char * PASSWORD) PKEY: The private key DATA: The private key data to be imported FORMAT: The format of the private key KEYID: The key id to use (optional) PASSWORD: A password (optional) This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 3.1.0 gnutls_privkey_import_pkcs11 ---------------------------- -- Function: int gnutls_privkey_import_pkcs11 (gnutls_privkey_t PKEY, gnutls_pkcs11_privkey_t KEY, unsigned int FLAGS) PKEY: The private key KEY: The private key to be imported FLAGS: Flags for the import This function will import the given private key to the abstract ‘gnutls_privkey_t’ type. The ‘gnutls_pkcs11_privkey_t’ object must not be deallocated during the lifetime of this structure. ‘flags’ might be zero or one of ‘GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE’ and ‘GNUTLS_PRIVKEY_IMPORT_COPY’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_privkey_import_pkcs11_url -------------------------------- -- Function: int gnutls_privkey_import_pkcs11_url (gnutls_privkey_t KEY, const char * URL) KEY: A key of type ‘gnutls_pubkey_t’ URL: A PKCS 11 url This function will import a PKCS 11 private key to a ‘gnutls_privkey_t’ type. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_privkey_import_rsa_raw ----------------------------- -- Function: int gnutls_privkey_import_rsa_raw (gnutls_privkey_t KEY, const gnutls_datum_t * M, const gnutls_datum_t * E, const gnutls_datum_t * D, const gnutls_datum_t * P, const gnutls_datum_t * Q, const gnutls_datum_t * U, const gnutls_datum_t * E1, const gnutls_datum_t * E2) KEY: The structure to store the parsed key M: holds the modulus E: holds the public exponent D: holds the private exponent (optional) P: holds the first prime (p) Q: holds the second prime (q) U: holds the coefficient (optional) E1: holds e1 = d mod (p-1) (optional) E2: holds e2 = d mod (q-1) (optional) This function will convert the given RSA raw parameters to the native ‘gnutls_privkey_t’ format. The output will be stored in ‘key’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_privkey_import_tpm_raw ----------------------------- -- Function: int gnutls_privkey_import_tpm_raw (gnutls_privkey_t PKEY, const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT, const char * SRK_PASSWORD, const char * KEY_PASSWORD, unsigned int FLAGS) PKEY: The private key FDATA: The TPM key to be imported FORMAT: The format of the private key SRK_PASSWORD: The password for the SRK key (optional) KEY_PASSWORD: A password for the key (optional) FLAGS: should be zero This function will import the given private key to the abstract ‘gnutls_privkey_t’ type. With respect to passwords the same as in ‘gnutls_privkey_import_tpm_url()’ apply. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_privkey_import_tpm_url ----------------------------- -- Function: int gnutls_privkey_import_tpm_url (gnutls_privkey_t PKEY, const char * URL, const char * SRK_PASSWORD, const char * KEY_PASSWORD, unsigned int FLAGS) PKEY: The private key URL: The URL of the TPM key to be imported SRK_PASSWORD: The password for the SRK key (optional) KEY_PASSWORD: A password for the key (optional) FLAGS: One of the GNUTLS_PRIVKEY_* flags This function will import the given private key to the abstract ‘gnutls_privkey_t’ type. Note that unless ‘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 ‘GNUTLS_E_TPM_SRK_PASSWORD_ERROR’ is returned and if the key password is wrong or not provided then ‘GNUTLS_E_TPM_KEY_PASSWORD_ERROR’ is returned. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_privkey_import_url ------------------------- -- Function: int gnutls_privkey_import_url (gnutls_privkey_t KEY, const char * URL, unsigned int FLAGS) KEY: A key of type ‘gnutls_privkey_t’ URL: A PKCS 11 url 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 ‘gnutls_url_is_supported()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_privkey_import_x509 -------------------------- -- Function: int gnutls_privkey_import_x509 (gnutls_privkey_t PKEY, gnutls_x509_privkey_t KEY, unsigned int FLAGS) PKEY: The private key KEY: The private key to be imported FLAGS: Flags for the import This function will import the given private key to the abstract ‘gnutls_privkey_t’ type. The ‘gnutls_x509_privkey_t’ object must not be deallocated during the lifetime of this structure. ‘flags’ might be zero or one of ‘GNUTLS_PRIVKEY_IMPORT_AUTO_RELEASE’ and ‘GNUTLS_PRIVKEY_IMPORT_COPY’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_privkey_import_x509_raw ------------------------------ -- Function: int gnutls_privkey_import_x509_raw (gnutls_privkey_t PKEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, const char * PASSWORD, unsigned int FLAGS) PKEY: The private key DATA: The private key data to be imported FORMAT: The format of the private key PASSWORD: A password (optional) FLAGS: an ORed sequence of gnutls_pkcs_encrypt_flags_t This function will import the given private key to the abstract ‘gnutls_privkey_t’ type. The supported formats are basic unencrypted key, PKCS8, PKCS12, TSS2, and the openssl format. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_privkey_init ------------------- -- Function: int gnutls_privkey_init (gnutls_privkey_t * KEY) 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‘11’ key (i.e., when imported with a PKCS‘11’ URI), the limitations of ‘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 ‘gnutls_privkey_t’ can be re-used by many threads. However, for performance it is recommended to utilize one object per key per thread. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_privkey_set_flags ------------------------ -- Function: void gnutls_privkey_set_flags (gnutls_privkey_t KEY, unsigned int FLAGS) KEY: A key of type ‘gnutls_privkey_t’ FLAGS: flags from the ‘gnutls_privkey_flags’ This function will set flags for the specified private key, after it is generated. Currently this is useful for the ‘GNUTLS_PRIVKEY_FLAG_EXPORT_COMPAT’ to allow exporting a "provable" private key in backwards compatible way. *Since:* 3.5.0 gnutls_privkey_set_pin_function ------------------------------- -- Function: void gnutls_privkey_set_pin_function (gnutls_privkey_t KEY, gnutls_pin_callback_t FN, void * USERDATA) KEY: A key of type ‘gnutls_privkey_t’ FN: the callback 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. *Since:* 3.1.0 gnutls_privkey_set_spki ----------------------- -- Function: int gnutls_privkey_set_spki (gnutls_privkey_t PRIVKEY, const gnutls_x509_spki_t SPKI, unsigned int FLAGS) PRIVKEY: a public key of type ‘gnutls_privkey_t’ SPKI: a SubjectPublicKeyInfo structure of type ‘gnutls_privkey_spki_t’ FLAGS: must be zero This function will set the public key information. The provided ‘spki’ must be initialized. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.0 gnutls_privkey_sign_data ------------------------ -- Function: int gnutls_privkey_sign_data (gnutls_privkey_t SIGNER, gnutls_digest_algorithm_t HASH, unsigned int FLAGS, const gnutls_datum_t * DATA, gnutls_datum_t * SIGNATURE) SIGNER: Holds the key HASH: should be a digest algorithm FLAGS: Zero or one of ‘gnutls_privkey_flags_t’ DATA: holds the data to be signed SIGNATURE: will contain the signature allocated with ‘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 ‘gnutls_pubkey_get_preferred_hash_algorithm()’ to determine the hash algorithm. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_privkey_sign_data2 ------------------------- -- Function: int gnutls_privkey_sign_data2 (gnutls_privkey_t SIGNER, gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const gnutls_datum_t * DATA, gnutls_datum_t * SIGNATURE) SIGNER: Holds the key ALGO: The signature algorithm used FLAGS: Zero or one of ‘gnutls_privkey_flags_t’ DATA: holds the data to be signed SIGNATURE: will contain the signature allocated with ‘gnutls_malloc()’ This function will sign the given data using the specified signature algorithm. This function is an enhancement of ‘gnutls_privkey_sign_data()’ , as it allows utilizing a alternative signature algorithm where possible (e.g, use an RSA key with RSA-PSS). *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.0 gnutls_privkey_sign_hash ------------------------ -- Function: int gnutls_privkey_sign_hash (gnutls_privkey_t SIGNER, gnutls_digest_algorithm_t HASH_ALGO, unsigned int FLAGS, const gnutls_datum_t * HASH_DATA, gnutls_datum_t * SIGNATURE) SIGNER: Holds the signer's key HASH_ALGO: The hash algorithm used FLAGS: Zero or one of ‘gnutls_privkey_flags_t’ HASH_DATA: holds the data to be signed 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 ‘gnutls_pubkey_get_preferred_hash_algorithm()’ to determine the hash algorithm. The flags may be ‘GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA’ or ‘GNUTLS_PRIVKEY_SIGN_FLAG_RSA_PSS’ . In the former case this function will ignore ‘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, ‘gnutls_privkey_sign_data()’ should be used. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_privkey_sign_hash2 ------------------------- -- Function: int gnutls_privkey_sign_hash2 (gnutls_privkey_t SIGNER, gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const gnutls_datum_t * HASH_DATA, gnutls_datum_t * SIGNATURE) SIGNER: Holds the signer's key ALGO: The signature algorithm used FLAGS: Zero or one of ‘gnutls_privkey_flags_t’ HASH_DATA: holds the data to be signed 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 ‘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 ‘GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA’ . In that case this function will ignore ‘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, ‘gnutls_privkey_sign_data2()’ should be used instead. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.0 gnutls_privkey_status --------------------- -- Function: int gnutls_privkey_status (gnutls_privkey_t KEY) KEY: Holds the key Checks the status of the private key token. This function is an actual wrapper over ‘gnutls_pkcs11_privkey_status()’ , and if the private key is a PKCS ‘11’ token it will check whether it is inserted or not. *Returns:* this function will return non-zero if the token holding the private key is still available (inserted), and zero otherwise. *Since:* 3.1.10 gnutls_privkey_verify_params ---------------------------- -- Function: int gnutls_privkey_verify_params (gnutls_privkey_t KEY) KEY: should contain a ‘gnutls_privkey_t’ type This function will verify the private key parameters. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.3.0 gnutls_privkey_verify_seed -------------------------- -- Function: int gnutls_privkey_verify_seed (gnutls_privkey_t KEY, gnutls_digest_algorithm_t DIGEST, const void * SEED, size_t SEED_SIZE) KEY: should contain a ‘gnutls_privkey_t’ type DIGEST: it contains the digest algorithm used for key generation (if applicable) SEED: the seed of the key to be checked with SEED_SIZE: holds the size of ‘seed’ This function will verify that the given private key was generated from the provided seed. *Returns:* In case of a verification failure ‘GNUTLS_E_PRIVKEY_VERIFICATION_ERROR’ is returned, and zero or positive code on success. *Since:* 3.5.0 gnutls_pubkey_deinit -------------------- -- Function: void gnutls_pubkey_deinit (gnutls_pubkey_t KEY) KEY: The key to be deinitialized This function will deinitialize a public key structure. *Since:* 2.12.0 gnutls_pubkey_encrypt_data -------------------------- -- Function: int gnutls_pubkey_encrypt_data (gnutls_pubkey_t KEY, unsigned int FLAGS, const gnutls_datum_t * PLAINTEXT, gnutls_datum_t * CIPHERTEXT) KEY: Holds the public key FLAGS: should be 0 for now PLAINTEXT: The data to be encrypted CIPHERTEXT: contains the encrypted data This function will encrypt the given data, using the public key. On success the ‘ciphertext’ will be allocated using ‘gnutls_malloc()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_pubkey_export -------------------- -- Function: int gnutls_pubkey_export (gnutls_pubkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) KEY: Holds the certificate FORMAT: the format of output params. One of PEM or DER. OUTPUT_DATA: will contain a certificate PEM or DER encoded 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 ‘GNUTLS_E_SHORT_MEMORY_BUFFER’ will be returned. If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE". *Returns:* In case of failure a negative error code will be returned, and 0 on success. *Since:* 2.12.0 gnutls_pubkey_export2 --------------------- -- Function: int gnutls_pubkey_export2 (gnutls_pubkey_t KEY, gnutls_x509_crt_fmt_t FORMAT, gnutls_datum_t * OUT) KEY: Holds the certificate FORMAT: the format of output params. One of PEM or DER. 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 ‘gnutls_malloc()’ . If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE". *Returns:* In case of failure a negative error code will be returned, and 0 on success. *Since:* 3.1.3 gnutls_pubkey_export_dh_raw --------------------------- -- Function: int gnutls_pubkey_export_dh_raw (gnutls_pubkey_t KEY, gnutls_dh_params_t PARAMS, gnutls_datum_t * Y, unsigned FLAGS) KEY: Holds the public key PARAMS: will hold the Diffie-Hellman parameter (optional), must be initialized Y: will hold the y FLAGS: flags from ‘gnutls_abstract_export_flags_t’ This function will export the Diffie-Hellman public key parameter found in the given public key. The new parameter will be allocated using ‘gnutls_malloc()’ and will be stored in the appropriate datum. To retrieve other parameters common in both public key and private key, use ‘gnutls_dh_params_export_raw()’ . This function allows for ‘NULL’ parameters since 3.4.1. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.8.2 gnutls_pubkey_export_dsa_raw ---------------------------- -- Function: int gnutls_pubkey_export_dsa_raw (gnutls_pubkey_t KEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y) KEY: Holds the public key P: will hold the p (may be ‘NULL’ ) Q: will hold the q (may be ‘NULL’ ) G: will hold the g (may be ‘NULL’ ) Y: will hold the y (may be ‘NULL’ ) This function will export the DSA public key's parameters found in the given certificate. The new parameters will be allocated using ‘gnutls_malloc()’ and will be stored in the appropriate datum. This function allows for ‘NULL’ parameters since 3.4.1. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.3.0 gnutls_pubkey_export_dsa_raw2 ----------------------------- -- Function: int gnutls_pubkey_export_dsa_raw2 (gnutls_pubkey_t KEY, gnutls_datum_t * P, gnutls_datum_t * Q, gnutls_datum_t * G, gnutls_datum_t * Y, unsigned FLAGS) KEY: Holds the public key P: will hold the p (may be ‘NULL’ ) Q: will hold the q (may be ‘NULL’ ) G: will hold the g (may be ‘NULL’ ) Y: will hold the y (may be ‘NULL’ ) FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. This function allows for ‘NULL’ parameters since 3.4.1. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.0 gnutls_pubkey_export_ecc_raw ---------------------------- -- Function: int gnutls_pubkey_export_ecc_raw (gnutls_pubkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t * Y) KEY: Holds the public key CURVE: will hold the curve (may be ‘NULL’ ) X: will hold x-coordinate (may be ‘NULL’ ) Y: will hold y-coordinate (may be ‘NULL’ ) This function will export the ECC public key's parameters found in the given key. The new parameters will be allocated using ‘gnutls_malloc()’ and will be stored in the appropriate datum. In EdDSA curves the ‘y’ parameter will be ‘NULL’ and the other parameters will be in the native format for the curve. This function allows for ‘NULL’ parameters since 3.4.1. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.0 gnutls_pubkey_export_ecc_raw2 ----------------------------- -- Function: int gnutls_pubkey_export_ecc_raw2 (gnutls_pubkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_datum_t * X, gnutls_datum_t * Y, unsigned int FLAGS) KEY: Holds the public key CURVE: will hold the curve (may be ‘NULL’ ) X: will hold x-coordinate (may be ‘NULL’ ) Y: will hold y-coordinate (may be ‘NULL’ ) FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. In EdDSA curves the ‘y’ parameter will be ‘NULL’ and the other parameters will be in the native format for the curve. This function allows for ‘NULL’ parameters since 3.4.1. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.0 gnutls_pubkey_export_ecc_x962 ----------------------------- -- Function: int gnutls_pubkey_export_ecc_x962 (gnutls_pubkey_t KEY, gnutls_datum_t * PARAMETERS, gnutls_datum_t * ECPOINT) KEY: Holds the public key PARAMETERS: DER encoding of an ANSI X9.62 parameters 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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.3.0 gnutls_pubkey_export_gost_raw2 ------------------------------ -- Function: int gnutls_pubkey_export_gost_raw2 (gnutls_pubkey_t KEY, gnutls_ecc_curve_t * CURVE, gnutls_digest_algorithm_t * DIGEST, gnutls_gost_paramset_t * PARAMSET, gnutls_datum_t * X, gnutls_datum_t * Y, unsigned int FLAGS) KEY: Holds the public key CURVE: will hold the curve (may be ‘NULL’ ) DIGEST: will hold the curve (may be ‘NULL’ ) PARAMSET: will hold the parameters id (may be ‘NULL’ ) X: will hold the x-coordinate (may be ‘NULL’ ) Y: will hold the y-coordinate (may be ‘NULL’ ) FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. *Note:* parameters will be stored with least significant byte first. On version 3.6.3 this was incorrectly returned in big-endian format. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.3 gnutls_pubkey_export_rsa_raw ---------------------------- -- Function: int gnutls_pubkey_export_rsa_raw (gnutls_pubkey_t KEY, gnutls_datum_t * M, gnutls_datum_t * E) KEY: Holds the certificate M: will hold the modulus (may be ‘NULL’ ) E: will hold the public exponent (may be ‘NULL’ ) This function will export the RSA public key's parameters found in the given structure. The new parameters will be allocated using ‘gnutls_malloc()’ and will be stored in the appropriate datum. This function allows for ‘NULL’ parameters since 3.4.1. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.3.0 gnutls_pubkey_export_rsa_raw2 ----------------------------- -- Function: int gnutls_pubkey_export_rsa_raw2 (gnutls_pubkey_t KEY, gnutls_datum_t * M, gnutls_datum_t * E, unsigned FLAGS) KEY: Holds the certificate M: will hold the modulus (may be ‘NULL’ ) E: will hold the public exponent (may be ‘NULL’ ) FLAGS: flags from ‘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 ‘gnutls_malloc()’ and will be stored in the appropriate datum. This function allows for ‘NULL’ parameters since 3.4.1. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error code. *Since:* 3.6.0 gnutls_pubkey_get_key_id ------------------------ -- Function: int gnutls_pubkey_get_key_id (gnutls_pubkey_t KEY, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) KEY: Holds the public key FLAGS: should be one of the flags from ‘gnutls_keyid_flags_t’ OUTPUT_DATA: will contain the key ID 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 ‘GNUTLS_E_SHORT_MEMORY_BUFFER’ will be returned. The output will normally be a SHA-1 hash output, which is 20 bytes. *Returns:* In case of failure a negative error code will be returned, and 0 on success. *Since:* 2.12.0 gnutls_pubkey_get_key_usage --------------------------- -- Function: int gnutls_pubkey_get_key_usage (gnutls_pubkey_t KEY, unsigned int * USAGE) KEY: should contain a ‘gnutls_pubkey_t’ type 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. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_get_openpgp_key_id -------------------------------- -- Function: int gnutls_pubkey_get_openpgp_key_id (gnutls_pubkey_t KEY, unsigned int FLAGS, unsigned char * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE, unsigned int * SUBKEY) KEY: Holds the public key FLAGS: should be one of the flags from ‘gnutls_keyid_flags_t’ OUTPUT_DATA: will contain the key ID OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) SUBKEY: ignored This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 2.12.0 gnutls_pubkey_get_pk_algorithm ------------------------------ -- Function: int gnutls_pubkey_get_pk_algorithm (gnutls_pubkey_t KEY, unsigned int * BITS) KEY: should contain a ‘gnutls_pubkey_t’ type 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. *Returns:* a member of the ‘gnutls_pk_algorithm_t’ enumeration on success, or a negative error code on error. *Since:* 2.12.0 gnutls_pubkey_get_preferred_hash_algorithm ------------------------------------------ -- Function: int gnutls_pubkey_get_preferred_hash_algorithm (gnutls_pubkey_t KEY, gnutls_digest_algorithm_t * HASH, unsigned int * MAND) KEY: Holds the certificate HASH: The result of the call with the hash algorithm used for signature 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 ‘gnutls_pk_to_sign()’ with the algorithm of the certificate/key and the provided ‘hash’ . *Returns:* the 0 if the hash algorithm is found. A negative error code is returned on error. *Since:* 2.12.0 gnutls_pubkey_get_spki ---------------------- -- Function: int gnutls_pubkey_get_spki (gnutls_pubkey_t PUBKEY, gnutls_x509_spki_t SPKI, unsigned int FLAGS) PUBKEY: a public key of type ‘gnutls_pubkey_t’ SPKI: a SubjectPublicKeyInfo structure of type ‘gnutls_pubkey_spki_t’ FLAGS: must be zero This function will return the public key information if available. The provided ‘spki’ must be initialized. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.0 gnutls_pubkey_import -------------------- -- Function: int gnutls_pubkey_import (gnutls_pubkey_t KEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT) KEY: The public key. DATA: The DER or PEM encoded certificate. FORMAT: One of DER or PEM This function will import the provided public key in a SubjectPublicKeyInfo X.509 structure to a native ‘gnutls_pubkey_t’ type. The output will be stored in ‘key’ . If the public key is PEM encoded it should have a header of "PUBLIC KEY". *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_import_dh_raw --------------------------- -- Function: int gnutls_pubkey_import_dh_raw (gnutls_pubkey_t KEY, const gnutls_dh_params_t PARAMS, const gnutls_datum_t * Y) KEY: The structure to store the parsed key PARAMS: holds the ‘gnutls_dh_params_t’ Y: holds the y This function will convert the given Diffie-Hellman raw parameters to the native ‘gnutls_pubkey_t’ format. The output will be stored in ‘key’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.8.2 gnutls_pubkey_import_dsa_raw ---------------------------- -- Function: int gnutls_pubkey_import_dsa_raw (gnutls_pubkey_t KEY, const gnutls_datum_t * P, const gnutls_datum_t * Q, const gnutls_datum_t * G, const gnutls_datum_t * Y) KEY: The structure to store the parsed key P: holds the p Q: holds the q G: holds the g Y: holds the y This function will convert the given DSA raw parameters to the native ‘gnutls_pubkey_t’ format. The output will be stored in ‘key’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_import_ecc_raw ---------------------------- -- Function: int gnutls_pubkey_import_ecc_raw (gnutls_pubkey_t KEY, gnutls_ecc_curve_t CURVE, const gnutls_datum_t * X, const gnutls_datum_t * Y) KEY: The structure to store the parsed key CURVE: holds the curve X: holds the x-coordinate Y: holds the y-coordinate This function will convert the given elliptic curve parameters to a ‘gnutls_pubkey_t’ . The output will be stored in ‘key’ . In EdDSA curves the ‘y’ parameter should be ‘NULL’ and the ‘x’ parameter must be the value in the native format for the curve. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_pubkey_import_ecc_x962 ----------------------------- -- Function: int gnutls_pubkey_import_ecc_x962 (gnutls_pubkey_t KEY, const gnutls_datum_t * PARAMETERS, const gnutls_datum_t * ECPOINT) KEY: The structure to store the parsed key PARAMETERS: DER encoding of an ANSI X9.62 parameters ECPOINT: DER encoding of ANSI X9.62 ECPoint This function will convert the given elliptic curve parameters to a ‘gnutls_pubkey_t’ . The output will be stored in ‘key’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_pubkey_import_gost_raw ----------------------------- -- Function: int gnutls_pubkey_import_gost_raw (gnutls_pubkey_t KEY, gnutls_ecc_curve_t CURVE, gnutls_digest_algorithm_t DIGEST, gnutls_gost_paramset_t PARAMSET, const gnutls_datum_t * X, const gnutls_datum_t * Y) KEY: The structure to store the parsed key CURVE: holds the curve DIGEST: holds the digest PARAMSET: holds the parameters id X: holds the x-coordinate Y: holds the y-coordinate This function will convert the given GOST public key's parameters to a ‘gnutls_pubkey_t’ . The output will be stored in ‘key’ . ‘digest’ should be one of GNUTLS_DIG_GOSR_94, GNUTLS_DIG_STREEBOG_256 or GNUTLS_DIG_STREEBOG_512. If ‘paramset’ is set to GNUTLS_GOST_PARAMSET_UNKNOWN default one will be selected depending on ‘digest’ . *Note:* parameters should be stored with least significant byte first. On version 3.6.3 big-endian format was used incorrectly. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.3 gnutls_pubkey_import_openpgp ---------------------------- -- Function: int gnutls_pubkey_import_openpgp (gnutls_pubkey_t KEY, gnutls_openpgp_crt_t CRT, unsigned int FLAGS) KEY: The public key CRT: The certificate to be imported FLAGS: should be zero This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 2.12.0 gnutls_pubkey_import_openpgp_raw -------------------------------- -- Function: int gnutls_pubkey_import_openpgp_raw (gnutls_pubkey_t PKEY, const gnutls_datum_t * DATA, gnutls_openpgp_crt_fmt_t FORMAT, const gnutls_openpgp_keyid_t KEYID, unsigned int FLAGS) PKEY: The public key DATA: The public key data to be imported FORMAT: The format of the public key KEYID: The key id to use (optional) FLAGS: Should be zero This function is no-op. *Returns:* ‘GNUTLS_E_UNIMPLEMENTED_FEATURE’ . *Since:* 3.1.3 gnutls_pubkey_import_pkcs11 --------------------------- -- Function: int gnutls_pubkey_import_pkcs11 (gnutls_pubkey_t KEY, gnutls_pkcs11_obj_t OBJ, unsigned int FLAGS) KEY: The public key OBJ: The parameters to be imported FLAGS: should be zero Imports a public key from a pkcs11 key. This function will import the given public key to the abstract ‘gnutls_pubkey_t’ type. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_import_privkey ---------------------------- -- Function: int gnutls_pubkey_import_privkey (gnutls_pubkey_t KEY, gnutls_privkey_t PKEY, unsigned int USAGE, unsigned int FLAGS) KEY: The public key PKEY: The private key USAGE: GNUTLS_KEY_* key usage flags. FLAGS: should be zero Imports the public key from a private. This function will import the given public key to the abstract ‘gnutls_pubkey_t’ type. Note that in certain keys this operation may not be possible, e.g., in other than RSA PKCS‘11’ keys. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_import_rsa_raw ---------------------------- -- Function: int gnutls_pubkey_import_rsa_raw (gnutls_pubkey_t KEY, const gnutls_datum_t * M, const gnutls_datum_t * E) KEY: The key M: holds the modulus 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. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, or an negative error code. *Since:* 2.12.0 gnutls_pubkey_import_tpm_raw ---------------------------- -- Function: int gnutls_pubkey_import_tpm_raw (gnutls_pubkey_t PKEY, const gnutls_datum_t * FDATA, gnutls_tpmkey_fmt_t FORMAT, const char * SRK_PASSWORD, unsigned int FLAGS) PKEY: The public key FDATA: The TPM key to be imported FORMAT: The format of the private key SRK_PASSWORD: The password for the SRK key (optional) 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 ‘gnutls_pubkey_import_tpm_url()’ apply. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_pubkey_import_tpm_url ---------------------------- -- Function: int gnutls_pubkey_import_tpm_url (gnutls_pubkey_t PKEY, const char * URL, const char * SRK_PASSWORD, unsigned int FLAGS) PKEY: The public key URL: The URL of the TPM key to be imported SRK_PASSWORD: The password for the SRK key (optional) FLAGS: should be zero This function will import the given private key to the abstract ‘gnutls_privkey_t’ type. Note that unless ‘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 ‘GNUTLS_E_TPM_SRK_PASSWORD_ERROR’ is returned. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_pubkey_import_url ------------------------ -- Function: int gnutls_pubkey_import_url (gnutls_pubkey_t KEY, const char * URL, unsigned int FLAGS) KEY: A key of type ‘gnutls_pubkey_t’ URL: A PKCS 11 url FLAGS: One of GNUTLS_PKCS11_OBJ_* flags This function will import a public key from the provided URL. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.0 gnutls_pubkey_import_x509 ------------------------- -- Function: int gnutls_pubkey_import_x509 (gnutls_pubkey_t KEY, gnutls_x509_crt_t CRT, unsigned int FLAGS) KEY: The public key CRT: The certificate to be imported FLAGS: should be zero This function will import the given public key to the abstract ‘gnutls_pubkey_t’ type. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_import_x509_crq ----------------------------- -- Function: int gnutls_pubkey_import_x509_crq (gnutls_pubkey_t KEY, gnutls_x509_crq_t CRQ, unsigned int FLAGS) KEY: The public key CRQ: The certificate to be imported FLAGS: should be zero This function will import the given public key to the abstract ‘gnutls_pubkey_t’ type. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.5 gnutls_pubkey_import_x509_raw ----------------------------- -- Function: int gnutls_pubkey_import_x509_raw (gnutls_pubkey_t PKEY, const gnutls_datum_t * DATA, gnutls_x509_crt_fmt_t FORMAT, unsigned int FLAGS) PKEY: The public key DATA: The public key data to be imported FORMAT: The format of the public key FLAGS: should be zero This function will import the given public key to the abstract ‘gnutls_pubkey_t’ type. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.3 gnutls_pubkey_init ------------------ -- Function: int gnutls_pubkey_init (gnutls_pubkey_t * KEY) KEY: A pointer to the type to be initialized This function will initialize a public key. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_print ------------------- -- Function: int gnutls_pubkey_print (gnutls_pubkey_t PUBKEY, gnutls_certificate_print_formats_t FORMAT, gnutls_datum_t * OUT) PUBKEY: The data to be printed FORMAT: Indicate the format to use OUT: Newly allocated datum with null terminated string. This function will pretty print public key information, suitable for display to a human. Only ‘GNUTLS_CRT_PRINT_FULL’ and ‘GNUTLS_CRT_PRINT_FULL_NUMBERS’ are implemented. The output ‘out’ needs to be deallocated using ‘gnutls_free()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.5 gnutls_pubkey_set_key_usage --------------------------- -- Function: int gnutls_pubkey_set_key_usage (gnutls_pubkey_t KEY, unsigned int USAGE) KEY: a certificate of type ‘gnutls_x509_crt_t’ 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. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pubkey_set_pin_function ------------------------------ -- Function: void gnutls_pubkey_set_pin_function (gnutls_pubkey_t KEY, gnutls_pin_callback_t FN, void * USERDATA) KEY: A key of type ‘gnutls_pubkey_t’ FN: the callback 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. *Since:* 3.1.0 gnutls_pubkey_set_spki ---------------------- -- Function: int gnutls_pubkey_set_spki (gnutls_pubkey_t PUBKEY, const gnutls_x509_spki_t SPKI, unsigned int FLAGS) PUBKEY: a public key of type ‘gnutls_pubkey_t’ SPKI: a SubjectPublicKeyInfo structure of type ‘gnutls_pubkey_spki_t’ FLAGS: must be zero This function will set the public key information. The provided ‘spki’ must be initialized. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.6.0 gnutls_pubkey_verify_data2 -------------------------- -- Function: int gnutls_pubkey_verify_data2 (gnutls_pubkey_t PUBKEY, gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const gnutls_datum_t * DATA, const gnutls_datum_t * SIGNATURE) PUBKEY: Holds the public key ALGO: The signature algorithm used FLAGS: Zero or an OR list of ‘gnutls_certificate_verify_flags’ DATA: holds the signed data SIGNATURE: contains the signature This function will verify the given signed data, using the parameters from the certificate. *Returns:* In case of a verification failure ‘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 ‘GNUTLS_E_INSUFFICIENT_SECURITY’ unless the flag ‘GNUTLS_VERIFY_ALLOW_BROKEN’ is specified. *Since:* 3.0 gnutls_pubkey_verify_hash2 -------------------------- -- Function: int gnutls_pubkey_verify_hash2 (gnutls_pubkey_t KEY, gnutls_sign_algorithm_t ALGO, unsigned int FLAGS, const gnutls_datum_t * HASH, const gnutls_datum_t * SIGNATURE) KEY: Holds the public key ALGO: The signature algorithm used FLAGS: Zero or an OR list of ‘gnutls_certificate_verify_flags’ HASH: holds the hash digest to be verified SIGNATURE: contains the signature This function will verify the given signed digest, using the parameters from the public key. Note that unlike ‘gnutls_privkey_sign_hash()’ , this function accepts a signature algorithm instead of a digest algorithm. You can use ‘gnutls_pk_to_sign()’ to get the appropriate value. *Returns:* In case of a verification failure ‘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 ‘GNUTLS_E_INSUFFICIENT_SECURITY’ unless the flag ‘GNUTLS_VERIFY_ALLOW_BROKEN’ is specified. *Since:* 3.0 gnutls_pubkey_verify_params --------------------------- -- Function: int gnutls_pubkey_verify_params (gnutls_pubkey_t KEY) KEY: should contain a ‘gnutls_pubkey_t’ type This function will verify the public key parameters. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.3.0 gnutls_register_custom_url -------------------------- -- Function: int gnutls_register_custom_url (const gnutls_custom_url_st * ST) ST: A ‘gnutls_custom_url_st’ structure Register a custom URL. This will affect the following functions: ‘gnutls_url_is_supported()’ , ‘gnutls_privkey_import_url()’ , gnutls_pubkey_import_url, ‘gnutls_x509_crt_import_url()’ and all functions that depend on them, e.g., ‘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 ‘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. *Returns:* returns zero if the given structure was imported or a negative value otherwise. *Since:* 3.4.0 gnutls_system_key_add_x509 -------------------------- -- Function: int gnutls_system_key_add_x509 (gnutls_x509_crt_t CRT, gnutls_x509_privkey_t PRIVKEY, const char * LABEL, char ** CERT_URL, char ** KEY_URL) CRT: the certificate to be added PRIVKEY: the key to be added LABEL: the friendly name to describe the key CERT_URL: if non-NULL it will contain an allocated value with the certificate URL 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. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_system_key_delete ------------------------ -- Function: int gnutls_system_key_delete (const char * CERT_URL, const char * KEY_URL) CERT_URL: the URL of the certificate KEY_URL: the URL of the key This function will delete the key and certificate pair. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_system_key_iter_deinit ----------------------------- -- Function: void gnutls_system_key_iter_deinit (gnutls_system_key_iter_t ITER) ITER: an iterator of system keys This function will deinitialize the iterator. *Since:* 3.4.0 gnutls_system_key_iter_get_info ------------------------------- -- Function: int gnutls_system_key_iter_get_info (gnutls_system_key_iter_t * ITER, unsigned CERT_TYPE, char ** CERT_URL, char ** KEY_URL, char ** LABEL, gnutls_datum_t * DER, unsigned int FLAGS) ITER: an iterator of the system keys (must be set to ‘NULL’ initially) CERT_TYPE: A value of gnutls_certificate_type_t which indicates the type of certificate to look for CERT_URL: The certificate URL of the pair (may be ‘NULL’ ) KEY_URL: The key URL of the pair (may be ‘NULL’ ) LABEL: The friendly name (if any) of the pair (may be ‘NULL’ ) DER: if non-NULL the DER data of the certificate 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 ‘GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE’ . Typically ‘cert_type’ should be ‘GNUTLS_CRT_X509’ . All values set are allocated and must be cleared using ‘gnutls_free()’ , *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_x509_crl_privkey_sign ---------------------------- -- Function: int gnutls_x509_crl_privkey_sign (gnutls_x509_crl_t CRL, gnutls_x509_crt_t ISSUER, gnutls_privkey_t ISSUER_KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS) CRL: should contain a gnutls_x509_crl_t type ISSUER: is the certificate of the certificate issuer ISSUER_KEY: holds the issuer's private key DIG: The message digest to use. GNUTLS_DIG_SHA256 is the safe choice unless you know what you're doing. 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 ‘dig’ may be ‘GNUTLS_DIG_UNKNOWN’ , and in that case, a suitable but reasonable for the key algorithm will be selected. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. Since 2.12.0 gnutls_x509_crq_privkey_sign ---------------------------- -- Function: int gnutls_x509_crq_privkey_sign (gnutls_x509_crq_t CRQ, gnutls_privkey_t KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS) CRQ: should contain a ‘gnutls_x509_crq_t’ type KEY: holds a private key DIG: The message digest to use, i.e., ‘GNUTLS_DIG_SHA1’ 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 ‘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 ‘dig’ may be ‘GNUTLS_DIG_UNKNOWN’ , and in that case, a suitable but reasonable for the key algorithm will be selected. *Returns:* ‘GNUTLS_E_SUCCESS’ on success, otherwise a negative error 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 ‘gnutls_x509_crq_set_version()’ ). *Since:* 2.12.0 gnutls_x509_crq_set_pubkey -------------------------- -- Function: int gnutls_x509_crq_set_pubkey (gnutls_x509_crq_t CRQ, gnutls_pubkey_t KEY) CRQ: should contain a ‘gnutls_x509_crq_t’ type KEY: holds a public key This function will set the public parameters from the given public key to the request. The ‘key’ can be deallocated after that. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_x509_crt_privkey_sign ---------------------------- -- Function: int gnutls_x509_crt_privkey_sign (gnutls_x509_crt_t CRT, gnutls_x509_crt_t ISSUER, gnutls_privkey_t ISSUER_KEY, gnutls_digest_algorithm_t DIG, unsigned int FLAGS) CRT: a certificate of type ‘gnutls_x509_crt_t’ ISSUER: is the certificate of the certificate issuer ISSUER_KEY: holds the issuer's private key DIG: The message digest to use, ‘GNUTLS_DIG_SHA256’ is a safe choice 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 ‘dig’ may be ‘GNUTLS_DIG_UNKNOWN’ , and in that case, a suitable but reasonable for the key algorithm will be selected. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_x509_crt_set_pubkey -------------------------- -- Function: int gnutls_x509_crt_set_pubkey (gnutls_x509_crt_t CRT, gnutls_pubkey_t KEY) CRT: should contain a ‘gnutls_x509_crt_t’ type KEY: holds a public key This function will set the public parameters from the given public key to the certificate. The ‘key’ can be deallocated after that. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0