info gnutls

E.13 Compatibility API

The following functions are carried over from old GnuTLS released. They might be removed at a later version. Their prototypes lie in ‘gnutls/compat.h’.

gnutls_certificate_client_set_retrieve_function

Function: void gnutls_certificate_client_set_retrieve_function (gnutls_certificate_credentials_t cred, gnutls_certificate_client_retrieve_function * func)

cred: is a gnutls_certificate_credentials_t structure.

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. You are advised to use gnutls_certificate_set_retrieve_function2() because it is much more efficient in the processing it requires from gnutls.

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_retr_st* st);

req_ca_cert is only used in X.509 certificates. Contains a list with the CA names that the server considers trusted. Normally we should send a certificate that is signed by one of these CAs. These names 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 signature algorithms. The certificate returned should support the server’s given algorithms.

st should contain the certificates and private keys.

If the callback function is provided then gnutls will call it, in the handshake, if a certificate is requested by the server (and after the certificate request message has been received).

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.

gnutls_certificate_server_set_retrieve_function

Function: void gnutls_certificate_server_set_retrieve_function (gnutls_certificate_credentials_t cred, gnutls_certificate_server_retrieve_function * func)

cred: is a gnutls_certificate_credentials_t structure.

func: is the callback function

The callback’s function prototype is: int (*callback)(gnutls_session_t, gnutls_retr_st* st);

st should contain the certificates and private keys.

If the callback function is provided then gnutls will call it, in the handshake, after the certificate request message has been received.

The callback function should set the certificate list to be sent, and return 0 on success. The value (-1) indicates error and the handshake will be terminated.

gnutls_certificate_set_rsa_export_params

Function: void gnutls_certificate_set_rsa_export_params (gnutls_certificate_credentials_t res, gnutls_rsa_params_t rsa_params)

res: is a gnutls_certificate_credentials_t structure

rsa_params: is a structure that holds temporary RSA parameters.

This function will set the temporary RSA parameters for a certificate server to use. These parameters will be used in RSA-EXPORT cipher suites.

gnutls_certificate_type_set_priority

Function: int gnutls_certificate_type_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_certificate_type_t elements.

Sets the priority on the certificate types supported by gnutls. Priority is higher for elements specified before others. After specifying the types you want, you must append a 0. Note that the certificate type priority is set on the client. The server does not use the cert type priority except for disabling types that were not specified.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_cipher_set_priority

Function: int gnutls_cipher_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_cipher_algorithm_t elements.

Sets the priority on the ciphers supported by gnutls. Priority is higher for elements specified before others. After specifying the ciphers you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

Returns: GNUTLS_E_SUCCESS (0) on success, or a negative error code.

gnutls_compression_set_priority

Function: int gnutls_compression_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_compression_method_t elements.

Sets the priority on the compression algorithms supported by gnutls. Priority is higher for elements specified before others. After specifying the algorithms you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

TLS 1.0 does not define any compression algorithms except NULL. Other compression algorithms are to be considered as gnutls extensions.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_kx_set_priority

Function: int gnutls_kx_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_kx_algorithm_t elements.

Sets the priority on the key exchange algorithms supported by gnutls. Priority is higher for elements specified before others. After specifying the algorithms you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_mac_set_priority

Function: int gnutls_mac_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_mac_algorithm_t elements.

Sets the priority on the mac algorithms supported by gnutls. Priority is higher for elements specified before others. After specifying the algorithms you want, you must append a 0. Note that the priority is set on the client. The server does not use the algorithm’s priority except for disabling algorithms that were not specified.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_openpgp_privkey_sign_hash

Function: int gnutls_openpgp_privkey_sign_hash (gnutls_openpgp_privkey_t key, const gnutls_datum_t * hash, gnutls_datum_t * signature)

key: Holds the key

hash: holds the data to be signed

signature: will contain newly allocated signature

This function will sign the given hash using the private key. You should use gnutls_openpgp_privkey_set_preferred_key_id() before calling this function to set the subkey to use.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Deprecated: Use gnutls_privkey_sign_hash() instead.

gnutls_privkey_sign_raw_data

Function: int gnutls_privkey_sign_raw_data (gnutls_privkey_t key, unsigned flags, const gnutls_datum_t * data, gnutls_datum_t * signature)

key: Holds the key

flags: should be zero

data: holds the data to be signed

signature: will contain the signature allocate with gnutls_malloc()

This function will sign the given data using a signature algorithm supported by the private key. Note that this is a low-level function and does not apply any preprocessing or hash on the signed data. For example on an RSA key the input data should be of the DigestInfo PKCS 1 1.5 format. Use it only if you know what are you doing.

Note this function is equivalent to using the GNUTLS_PRIVKEY_SIGN_FLAG_TLS1_RSA flag with gnutls_privkey_sign_hash() .

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Since: 3.1.10

gnutls_protocol_set_priority

Function: int gnutls_protocol_set_priority (gnutls_session_t session, const int * list)

session: is a gnutls_session_t structure.

list: is a 0 terminated list of gnutls_protocol_t elements.

Sets the priority on the protocol versions supported by gnutls. This function actually enables or disables protocols. Newer protocol versions always have highest priority.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_rsa_export_get_modulus_bits

Function: int gnutls_rsa_export_get_modulus_bits (gnutls_session_t session)

session: is a gnutls session

Get the export RSA parameter’s modulus size.

Returns: The bits used in the last RSA-EXPORT key exchange with the peer, or a negative error code in case of error.

gnutls_rsa_export_get_pubkey

Function: int gnutls_rsa_export_get_pubkey (gnutls_session_t session, gnutls_datum_t * exponent, gnutls_datum_t * modulus)

session: is a gnutls session

exponent: will hold the exponent.

modulus: will hold the modulus.

This function will return the peer’s public key exponent and modulus used in the last RSA-EXPORT authentication. The output parameters must be freed with gnutls_free() .

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise an error code is returned.

gnutls_rsa_params_cpy

Function: int gnutls_rsa_params_cpy (gnutls_rsa_params_t dst, gnutls_rsa_params_t src)

dst: Is the destination structure, which should be initialized.

src: Is the source structure

This function will copy the RSA parameters structure from source to destination.

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_deinit

Function: void gnutls_rsa_params_deinit (gnutls_rsa_params_t rsa_params)

rsa_params: Is a structure that holds the parameters

This function will deinitialize the RSA parameters structure.

gnutls_rsa_params_export_pkcs1

Function: int gnutls_rsa_params_export_pkcs1 (gnutls_rsa_params_t params, gnutls_x509_crt_fmt_t format, unsigned char * params_data, size_t * params_data_size)

params: Holds the RSA parameters

format: the format of output params. One of PEM or DER.

params_data: will contain a PKCS1 RSAPrivateKey structure PEM or DER encoded

params_data_size: holds the size of params_data (and will be replaced by the actual size of parameters)

This function will export the given RSA parameters to a PKCS1 RSAPrivateKey structure. If the buffer provided is not long enough to hold the output, then GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.

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

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_export_raw

Function: int gnutls_rsa_params_export_raw (gnutls_rsa_params_t rsa, gnutls_datum_t * m, gnutls_datum_t * e, gnutls_datum_t * d, gnutls_datum_t * p, gnutls_datum_t * q, gnutls_datum_t * u, unsigned int * bits)

rsa: a structure that holds the rsa parameters

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

bits: if non null will hold the prime’s number of bits

This function will export the RSA 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, or an negative error code.

gnutls_rsa_params_generate2

Function: int gnutls_rsa_params_generate2 (gnutls_rsa_params_t params, unsigned int bits)

params: The structure where the parameters will be stored

bits: is the prime’s number of bits

This function will generate new temporary RSA parameters for use in RSA-EXPORT ciphersuites. This function is normally slow.

Note that if the parameters are to be used in export cipher suites the bits value should be 512 or less. Also note that the generation of new RSA parameters is only useful to servers. Clients use the parameters sent by the server, thus it’s no use calling this in client side.

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_import_pkcs1

Function: int gnutls_rsa_params_import_pkcs1 (gnutls_rsa_params_t params, const gnutls_datum_t * pkcs1_params, gnutls_x509_crt_fmt_t format)

params: A structure where the parameters will be copied to

pkcs1_params: should contain a PKCS1 RSAPrivateKey structure PEM or DER encoded

format: the format of params. PEM or DER.

This function will extract the RSAPrivateKey found in a PKCS1 formatted structure.

If the structure is PEM encoded, it should have a header of "BEGIN RSA PRIVATE KEY".

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_rsa_params_import_raw

Function: int gnutls_rsa_params_import_raw (gnutls_rsa_params_t rsa_params, 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)

rsa_params: Is a structure will hold the parameters

m: holds the modulus

e: holds the public exponent

d: holds the private exponent

p: holds the first prime (p)

q: holds the second prime (q)

u: holds the coefficient

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.

gnutls_rsa_params_init

Function: int gnutls_rsa_params_init (gnutls_rsa_params_t * rsa_params)

rsa_params: Is a structure that will hold the parameters

This function will initialize the temporary RSA parameters structure.

Returns: GNUTLS_E_SUCCESS on success, or an negative error code.

gnutls_set_default_export_priority

Function: int gnutls_set_default_export_priority (gnutls_session_t session)

session: is a gnutls_session_t structure.

Sets some default priority on the ciphers, key exchange methods, macs and compression methods. This function also includes weak algorithms.

This is the same as calling:

gnutls_priority_set_direct (session, "EXPORT", NULL);

This function is kept around for backwards compatibility, but because of its wide use it is still fully supported. If you wish to allow users to provide a string that specify which ciphers to use (which is recommended), you should use gnutls_priority_set_direct() or gnutls_priority_set() instead.

Returns: GNUTLS_E_SUCCESS on success, or an error code.

gnutls_sign_callback_get

Function: gnutls_sign_func gnutls_sign_callback_get (gnutls_session_t session, void ** userdata)

session: is a gnutls session

userdata: if non-NULL , will be set to abstract callback pointer.

Retrieve the callback function, and its userdata pointer.

Returns: The function pointer set by gnutls_sign_callback_set() , or if not set, NULL .

Deprecated: Use the PKCS 11 interfaces instead.

gnutls_sign_callback_set

Function: void gnutls_sign_callback_set (gnutls_session_t session, gnutls_sign_func sign_func, void * userdata)

session: is a gnutls session

sign_func: function pointer to application’s sign callback.

userdata: void pointer that will be passed to sign callback.

Set the callback function. The function must have this prototype:

typedef int (*gnutls_sign_func) (gnutls_session_t session, void *userdata, gnutls_certificate_type_t cert_type, const gnutls_datum_t * cert, const gnutls_datum_t * hash, gnutls_datum_t * signature);

The userdata parameter is passed to the sign_func verbatim, and can be used to store application-specific data needed in the callback function. See also gnutls_sign_callback_get() .

Deprecated: Use the PKCS 11 or gnutls_privkey_t interfacess like gnutls_privkey_import_ext() instead.

gnutls_x509_crl_sign

Function: int gnutls_x509_crl_sign (gnutls_x509_crl_t crl, gnutls_x509_crt_t issuer, gnutls_x509_privkey_t issuer_key)

crl: should contain a gnutls_x509_crl_t structure

issuer: is the certificate of the certificate issuer

issuer_key: holds the issuer’s private key

This function is the same a gnutls_x509_crl_sign2() with no flags, and SHA1 as the hash algorithm.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Deprecated: Use gnutls_x509_crl_privkey_sign() .

gnutls_x509_crq_sign

Function: int gnutls_x509_crq_sign (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)

crq: should contain a gnutls_x509_crq_t structure

key: holds a private key

This function is the same a gnutls_x509_crq_sign2() with no flags, and SHA1 as the hash algorithm.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Deprecated: Use gnutls_x509_crq_privkey_sign() instead.

gnutls_x509_crt_get_preferred_hash_algorithm

Function: int gnutls_x509_crt_get_preferred_hash_algorithm (gnutls_x509_crt_t crt, gnutls_digest_algorithm_t * hash, unsigned int * mand)

crt: 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 certifcate 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).

Deprecated: Please use gnutls_pubkey_get_preferred_hash_algorithm() .

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

Since: 2.12.0

gnutls_x509_crt_get_verify_algorithm

Function: int gnutls_x509_crt_get_verify_algorithm (gnutls_x509_crt_t crt, const gnutls_datum_t * signature, gnutls_digest_algorithm_t * hash)

crt: Holds the certificate

signature: contains the signature

hash: The result of the call with the hash algorithm used for signature

This function will read the certifcate and the signed data to determine the hash algorithm used to generate the signature.

Deprecated: Use gnutls_pubkey_get_verify_algorithm() instead.

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

Since: 2.8.0

gnutls_x509_crt_verify_data

Function: int gnutls_x509_crt_verify_data (gnutls_x509_crt_t crt, unsigned int flags, const gnutls_datum_t * data, const gnutls_datum_t * signature)

crt: Holds the certificate

flags: should be 0 for now

data: holds the data to be signed

signature: contains the signature

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

Deprecated. This function cannot be easily used securely. Use gnutls_pubkey_verify_data2() instead.

Returns: In case of a verification failure GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and zero or positive code on success.

gnutls_x509_crt_verify_hash

Function: int gnutls_x509_crt_verify_hash (gnutls_x509_crt_t crt, unsigned int flags, const gnutls_datum_t * hash, const gnutls_datum_t * signature)

crt: Holds the certificate

flags: should be 0 for now

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 certificate.

Deprecated. This function cannot be easily used securely. Use gnutls_pubkey_verify_hash2() instead.

Returns: In case of a verification failure GNUTLS_E_PK_SIG_VERIFY_FAILED is returned, and zero or positive code on success.

gnutls_x509_privkey_sign_data

Function: int gnutls_x509_privkey_sign_data (gnutls_x509_privkey_t key, gnutls_digest_algorithm_t digest, unsigned int flags, const gnutls_datum_t * data, void * signature, size_t * signature_size)

key: Holds the key

digest: should be MD5 or SHA1

flags: should be 0 for now

data: holds the data to be signed

signature: will contain the signature

signature_size: holds the size of signature (and will be replaced by the new size)

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 SHA-1 for the DSA keys.

If the buffer provided is not long enough to hold the output, then * signature_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.

Use gnutls_x509_crt_get_preferred_hash_algorithm() to determine the hash algorithm.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Deprecated: Use gnutls_privkey_sign_data() .

gnutls_x509_privkey_sign_hash

Function: int gnutls_x509_privkey_sign_hash (gnutls_x509_privkey_t key, const gnutls_datum_t * hash, gnutls_datum_t * signature)

key: Holds the key

hash: holds the data to be signed

signature: will contain newly allocated signature

This function will sign the given hash using the private key. Do not use this function directly unless you know what it is. Typical signing requires the data to be hashed and stored in special formats (e.g. BER Digest-Info for RSA).

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Deprecated in: 2.12.0

This document was generated on February 9, 2014 using texi2html 5.0.