| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
C.5 PKCS 12 API
The following functions are to be used for PKCS 12 handling. Their prototypes lie in ‘gnutls/pkcs12.h’.
gnutls_pkcs12_bag_decrypt
- Function: int gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t bag, const char * pass)
bag: The bag
pass: The password used for encryption, must be ASCII.
Description: This function will decrypt the given encrypted bag and return 0 on success.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error code is returned.
gnutls_pkcs12_bag_deinit
- Function: void gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t bag)
bag: The structure to be initialized
Description: This function will deinitialize a PKCS12 Bag structure.
gnutls_pkcs12_bag_encrypt
- Function: int gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t bag, const char * pass, unsigned int flags)
bag: The bag
pass: The password used for encryption, must be ASCII
flags: should be one of
gnutls_pkcs_encrypt_flags_telements bitwise or’dDescription: This function will encrypt the given bag.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error code is returned.
gnutls_pkcs12_bag_get_count
- Function: int gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t bag)
bag: The bag
Description: This function will return the number of the elements withing the bag.
Returns: Number of elements in bag, or an negative error code on error.
gnutls_pkcs12_bag_get_data
- Function: int gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t bag, int indx, gnutls_datum_t * data)
bag: The bag
indx: The element of the bag to get the data from
data: where the bag’s data will be. Should be treated as constant.
Description: This function will return the bag’s data. The data is a constant that is stored into the bag. Should not be accessed after the bag is deleted.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
gnutls_pkcs12_bag_get_friendly_name
- Function: int gnutls_pkcs12_bag_get_friendly_name (gnutls_pkcs12_bag_t bag, int indx, char ** name)
bag: The bag
indx: The bag’s element to add the id
name: will hold a pointer to the name (to be treated as const)
Description: This function will return the friendly name, of the specified bag element. The key ID is usually used to distinguish the local private key and the certificate pair.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value. or a negative error code on error.
gnutls_pkcs12_bag_get_key_id
- Function: int gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t bag, int indx, gnutls_datum_t * id)
bag: The bag
indx: The bag’s element to add the id
id: where the ID will be copied (to be treated as const)
Description: This function will return the key ID, of the specified bag element. The key ID is usually used to distinguish the local private key and the certificate pair.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value. or a negative error code on error.
gnutls_pkcs12_bag_get_type
- Function: gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t bag, int indx)
bag: The bag
indx: The element of the bag to get the type
Description: This function will return the bag’s type.
Returns: One of the
gnutls_pkcs12_bag_type_tenumerations.
gnutls_pkcs12_bag_init
- Function: int gnutls_pkcs12_bag_init (gnutls_pkcs12_bag_t * bag)
bag: The structure to be initialized
Description: This function will initialize a PKCS12 bag structure. PKCS12 Bags usually contain private keys, lists of X.509 Certificates and X.509 Certificate revocation lists.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
gnutls_pkcs12_bag_set_crl
- Function: int gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t bag, gnutls_x509_crl_t crl)
bag: The bag
crl: the CRL to be copied.
Description: This function will insert the given CRL into the bag. This is just a wrapper over
gnutls_pkcs12_bag_set_data().Returns: the index of the added bag on success, or a negative error code on failure.
gnutls_pkcs12_bag_set_crt
- Function: int gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t bag, gnutls_x509_crt_t crt)
bag: The bag
crt: the certificate to be copied.
Description: This function will insert the given certificate into the bag. This is just a wrapper over
gnutls_pkcs12_bag_set_data().Returns: the index of the added bag on success, or a negative value on failure.
gnutls_pkcs12_bag_set_data
- Function: int gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t bag, gnutls_pkcs12_bag_type_t type, const gnutls_datum_t * data)
bag: The bag
type: The data’s type
data: the data to be copied.
Description: This function will insert the given data of the given type into the bag.
Returns: the index of the added bag on success, or a negative value on error.
gnutls_pkcs12_bag_set_friendly_name
- Function: int gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t bag, int indx, const char * name)
bag: The bag
indx: The bag’s element to add the id
name: the name
Description: This function will add the given key friendly name, to the specified, by the index, bag element. The name will be encoded as a ’Friendly name’ bag attribute, which is usually used to set a user name to the local private key and the certificate pair.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value. or a negative error code on error.
gnutls_pkcs12_bag_set_key_id
- Function: int gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t bag, int indx, const gnutls_datum_t * id)
bag: The bag
indx: The bag’s element to add the id
id: the ID
Description: This function will add the given key ID, to the specified, by the index, bag element. The key ID will be encoded as a ’Local key identifier’ bag attribute, which is usually used to distinguish the local private key and the certificate pair.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value. or a negative error code on error.
gnutls_pkcs12_deinit
- Function: void gnutls_pkcs12_deinit (gnutls_pkcs12_t pkcs12)
pkcs12: The structure to be initialized
Description: This function will deinitialize a PKCS12 structure.
gnutls_pkcs12_export
- Function: int gnutls_pkcs12_export (gnutls_pkcs12_t pkcs12, gnutls_x509_crt_fmt_t format, void * output_data, size_t * output_data_size)
pkcs12: Holds the pkcs12 structure
format: the format of output params. One of PEM or DER.
output_data: will contain a structure PEM or DER encoded
output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters)
Description: This function will export the pkcs12 structure to DER or PEM format.
If the buffer provided is not long enough to hold the output, then *output_data_size will be updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
If the structure is PEM encoded, it will have a header of "BEGIN PKCS12".
Returns: In case of failure a negative error code will be returned, and 0 on success.
gnutls_pkcs12_generate_mac
- Function: int gnutls_pkcs12_generate_mac (gnutls_pkcs12_t pkcs12, const char * pass)
pkcs12: should contain a gnutls_pkcs12_t structure
pass: The password for the MAC
Description: This function will generate a MAC for the PKCS12 structure.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
gnutls_pkcs12_get_bag
- Function: int gnutls_pkcs12_get_bag (gnutls_pkcs12_t pkcs12, int indx, gnutls_pkcs12_bag_t bag)
pkcs12: should contain a gnutls_pkcs12_t structure
indx: contains the index of the bag to extract
bag: An initialized bag, where the contents of the bag will be copied
Description: This function will return a Bag from the PKCS12 structure.
After the last Bag has been read
GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLEwill be returned.Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
gnutls_pkcs12_import
- Function: int gnutls_pkcs12_import (gnutls_pkcs12_t pkcs12, const gnutls_datum_t * data, gnutls_x509_crt_fmt_t format, unsigned int flags)
pkcs12: The structure to store the parsed PKCS12.
data: The DER or PEM encoded PKCS12.
format: One of DER or PEM
flags: an ORed sequence of gnutls_privkey_pkcs8_flags
Description: This function will convert the given DER or PEM encoded PKCS12 to the native gnutls_pkcs12_t format. The output will be stored in ’pkcs12’.
If the PKCS12 is PEM encoded it should have a header of "PKCS12".
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
gnutls_pkcs12_init
- Function: int gnutls_pkcs12_init (gnutls_pkcs12_t * pkcs12)
pkcs12: The structure to be initialized
Description: This function will initialize a PKCS12 structure. PKCS12 structures usually contain lists of X.509 Certificates and X.509 Certificate revocation lists.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
gnutls_pkcs12_set_bag
- Function: int gnutls_pkcs12_set_bag (gnutls_pkcs12_t pkcs12, gnutls_pkcs12_bag_t bag)
pkcs12: should contain a gnutls_pkcs12_t structure
bag: An initialized bag
Description: This function will insert a Bag into the PKCS12 structure.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
gnutls_pkcs12_verify_mac
- Function: int gnutls_pkcs12_verify_mac (gnutls_pkcs12_t pkcs12, const char * pass)
pkcs12: should contain a gnutls_pkcs12_t structure
pass: The password for the MAC
Description: This function will verify the MAC for the PKCS12 structure.
Returns: On success,
GNUTLS_E_SUCCESS(0) is returned, otherwise a negative error value.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 4, 2012 using texi2html 5.0.