Next: Socket specific API, Previous: TPM API, Up: API reference [Contents][Index]
The following functions are to be used for abstract key handling. Their prototypes lie in gnutls/abstract.h.
res: is a gnutls_certificate_credentials_t type.
names: is an array of DNS names belonging to the public-key (NULL if none)
names_size: holds the size of the names list
pcert_list: contains a 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
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
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
pcert: The structure to be deinitialized
This function will deinitialize a pcert structure.
Since: 3.0
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
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
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
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
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
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
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
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
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
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
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
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
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
key: The key to be deinitialized
This function will deinitialize a private key structure.
Since: 2.12.0
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
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
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
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
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
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
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
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
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
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
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
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
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
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
PKCS8 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
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
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
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
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
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
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.
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
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
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
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
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 PKCS1 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 PKCS1 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
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
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
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
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
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
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.
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
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
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
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
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
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 PKCS11 key (i.e.,
when imported with a PKCS11 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
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
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
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
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
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
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
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
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
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
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
key: The key to be deinitialized
This function will deinitialize a public key structure.
Since: 2.12.0
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 PKCS11 keys.
Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value.
Since: 2.12.0
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
iter: an iterator of system keys
This function will deinitialize the iterator.
Since: 3.4.0
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
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
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
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
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.
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
Next: Socket specific API, Previous: TPM API, Up: API reference [Contents][Index]