pkcs12

pkcs12

Functions

Types and Values

Description

Functions

gnutls_pkcs12_init ()

int
gnutls_pkcs12_init (gnutls_pkcs12_t *pkcs12);

This function will initialize a PKCS12 type. PKCS12 structures usually contain lists of X.509 Certificates and X.509 Certificate revocation lists.

Parameters

pkcs12

A pointer to the type to be initialized

 

Returns

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


gnutls_pkcs12_deinit ()

void
gnutls_pkcs12_deinit (gnutls_pkcs12_t pkcs12);

This function will deinitialize a PKCS12 type.

Parameters

pkcs12

The type to be initialized

 

gnutls_pkcs12_import ()

int
gnutls_pkcs12_import (gnutls_pkcs12_t pkcs12,
                      const gnutls_datum_t *data,
                      gnutls_x509_crt_fmt_t format,
                      unsigned int flags);

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

Parameters

pkcs12

The data 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

 

Returns

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


gnutls_pkcs12_export ()

int
gnutls_pkcs12_export (gnutls_pkcs12_t pkcs12,
                      gnutls_x509_crt_fmt_t format,
                      void *output_data,
                      size_t *output_data_size);

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

Parameters

pkcs12

A pkcs12 type

 

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)

 

Returns

In case of failure a negative error code will be returned, and 0 on success.


gnutls_pkcs12_export2 ()

int
gnutls_pkcs12_export2 (gnutls_pkcs12_t pkcs12,
                       gnutls_x509_crt_fmt_t format,
                       gnutls_datum_t *out);

This function will export the pkcs12 structure to DER or PEM format.

The output buffer is allocated using gnutls_malloc().

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

Parameters

pkcs12

A pkcs12 type

 

format

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

 

out

will contain a structure PEM or DER encoded

 

Returns

In case of failure a negative error code will be returned, and 0 on success.

Since: 3.1.3


gnutls_pkcs12_get_bag ()

int
gnutls_pkcs12_get_bag (gnutls_pkcs12_t pkcs12,
                       int indx,
                       gnutls_pkcs12_bag_t bag);

This function will return a Bag from the PKCS12 structure.

After the last Bag has been read GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.

Parameters

pkcs12

A pkcs12 type

 

indx

contains the index of the bag to extract

 

bag

An initialized bag, where the contents of the bag will be copied

 

Returns

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


gnutls_pkcs12_set_bag ()

int
gnutls_pkcs12_set_bag (gnutls_pkcs12_t pkcs12,
                       gnutls_pkcs12_bag_t bag);

This function will insert a Bag into the PKCS12 structure.

Parameters

pkcs12

should contain a gnutls_pkcs12_t type

 

bag

An initialized bag

 

Returns

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


gnutls_pkcs12_generate_mac ()

int
gnutls_pkcs12_generate_mac (gnutls_pkcs12_t pkcs12,
                            const char *pass);

This function will generate a MAC for the PKCS12 structure.

Parameters

pkcs12

A pkcs12 type

 

pass

The password for the MAC

 

Returns

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


gnutls_pkcs12_generate_mac2 ()

int
gnutls_pkcs12_generate_mac2 (gnutls_pkcs12_t pkcs12,
                             gnutls_mac_algorithm_t mac,
                             const char *pass);

This function will generate a MAC for the PKCS12 structure.

Parameters

pkcs12

A pkcs12 type

 

mac

the MAC algorithm to use

 

pass

The password for the MAC

 

Returns

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


gnutls_pkcs12_verify_mac ()

int
gnutls_pkcs12_verify_mac (gnutls_pkcs12_t pkcs12,
                          const char *pass);

This function will verify the MAC for the PKCS12 structure.

Parameters

pkcs12

should contain a gnutls_pkcs12_t type

 

pass

The password for the MAC

 

Returns

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


gnutls_pkcs12_bag_decrypt ()

int
gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t bag,
                           const char *pass);

This function will decrypt the given encrypted bag and return 0 on success.

Parameters

bag

The bag

 

pass

The password used for encryption, must be ASCII.

 

Returns

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.


gnutls_pkcs12_bag_encrypt ()

int
gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t bag,
                           const char *pass,
                           unsigned int flags);

This function will encrypt the given bag.

Parameters

bag

The bag

 

pass

The password used for encryption, must be ASCII

 

flags

should be one of gnutls_pkcs_encrypt_flags_t elements bitwise or'd

 

Returns

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.


gnutls_pkcs12_bag_enc_info ()

int
gnutls_pkcs12_bag_enc_info (gnutls_pkcs12_bag_t bag,
                            unsigned int *schema,
                            unsigned int *cipher,
                            void *salt,
                            unsigned int *salt_size,
                            unsigned int *iter_count,
                            char **oid);

This function will provide information on the encryption algorithms used in an encrypted bag. If the structure algorithms are unknown the code GNUTLS_E_UNKNOWN_CIPHER_TYPE will be returned, and only oid , will be set. That is, oid will be set on encrypted bags whether supported or not. It must be deinitialized using gnutls_free(). The other variables are only set on supported structures.

Parameters

bag

The bag

 

schema

indicate the schema as one of gnutls_pkcs_encrypt_flags_t

 

cipher

the cipher used as gnutls_cipher_algorithm_t

 

salt

PBKDF2 salt (if non-NULL then salt_size initially holds its size)

 

salt_size

PBKDF2 salt size

 

iter_count

PBKDF2 iteration count

 

oid

if non-NULL it will contain an allocated null-terminated variable with the OID

 

Returns

GNUTLS_E_INVALID_REQUEST if the provided bag isn't encrypted, GNUTLS_E_UNKNOWN_CIPHER_TYPE if the structure's encryption isn't supported, or another negative error code in case of a failure. Zero on success.


gnutls_pkcs12_mac_info ()

int
gnutls_pkcs12_mac_info (gnutls_pkcs12_t pkcs12,
                        unsigned int *mac,
                        void *salt,
                        unsigned int *salt_size,
                        unsigned int *iter_count,
                        char **oid);

This function will provide information on the MAC algorithm used in a PKCS 12 structure. If the structure algorithms are unknown the code GNUTLS_E_UNKNOWN_HASH_ALGORITHM will be returned, and only oid , will be set. That is, oid will be set on structures with a MAC whether supported or not. It must be deinitialized using gnutls_free(). The other variables are only set on supported structures.

Parameters

pkcs12

A pkcs12 type

 

mac

the MAC algorithm used as gnutls_mac_algorithm_t

 

salt

the salt used for string to key (if non-NULL then salt_size initially holds its size)

 

salt_size

string to key salt size

 

iter_count

string to key iteration count

 

oid

if non-NULL it will contain an allocated null-terminated variable with the OID

 

Returns

GNUTLS_E_INVALID_REQUEST if the provided structure doesn't contain a MAC, GNUTLS_E_UNKNOWN_HASH_ALGORITHM if the structure's MAC isn't supported, or another negative error code in case of a failure. Zero on success.


gnutls_pkcs12_simple_parse ()

int
gnutls_pkcs12_simple_parse (gnutls_pkcs12_t p12,
                            const char *password,
                            gnutls_x509_privkey_t *key,
                            gnutls_x509_crt_t **chain,
                            unsigned int *chain_len,
                            gnutls_x509_crt_t **extra_certs,
                            unsigned int *extra_certs_len,
                            gnutls_x509_crl_t *crl,
                            unsigned int flags);

This function parses a PKCS12 structure in pkcs12 and extracts the private key, the corresponding certificate chain, any additional certificates and a CRL. The structures in key , chain crl , and extra_certs must not be initialized.

The extra_certs and extra_certs_len parameters are optional and both may be set to NULL. If either is non-NULL, then both must be set. The value for extra_certs is allocated using gnutls_malloc().

Encrypted PKCS12 bags and PKCS8 private keys are supported, but only with password based security and the same password for all operations.

Note that a PKCS12 structure may contain many keys and/or certificates, and there is no way to identify which key/certificate pair you want. For this reason this function is useful for PKCS12 files that contain only one key/certificate pair and/or one CRL.

If the provided structure has encrypted fields but no password is provided then this function returns GNUTLS_E_DECRYPTION_FAILED.

Note that normally the chain constructed does not include self signed certificates, to comply with TLS' requirements. If, however, the flag GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED is specified then self signed certificates will be included in the chain.

Prior to using this function the PKCS 12 structure integrity must be verified using gnutls_pkcs12_verify_mac().

Parameters

p12

A pkcs12 type

 

password

optional password used to decrypt the structure, bags and keys.

 

key

a structure to store the parsed private key.

 

chain

the corresponding to key certificate chain (may be NULL)

 

chain_len

will be updated with the number of additional (may be NULL)

 

extra_certs

optional pointer to receive an array of additional certificates found in the PKCS12 structure (may be NULL).

 

extra_certs_len

will be updated with the number of additional certs (may be NULL).

 

crl

an optional structure to store the parsed CRL (may be NULL).

 

flags

should be zero or one of GNUTLS_PKCS12_SP_*

 

Returns

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

Since: 3.1.0


gnutls_pkcs12_bag_get_data ()

int
gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t bag,
                            unsigned  indx,
                            gnutls_datum_t *data);

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.

Parameters

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.

 

Returns

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


gnutls_pkcs12_bag_set_data ()

int
gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t bag,
                            gnutls_pkcs12_bag_type_t type,
                            const gnutls_datum_t *data);

This function will insert the given data of the given type into the bag.

Parameters

bag

The bag

 

type

The data's type

 

data

the data to be copied.

 

Returns

the index of the added bag on success, or a negative value on error.


gnutls_pkcs12_bag_set_crl ()

int
gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t bag,
                           gnutls_x509_crl_t crl);

This function will insert the given CRL into the bag. This is just a wrapper over gnutls_pkcs12_bag_set_data().

Parameters

bag

The bag

 

crl

the CRL to be copied.

 

Returns

the index of the added bag on success, or a negative error code on failure.


gnutls_pkcs12_bag_set_crt ()

int
gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t bag,
                           gnutls_x509_crt_t crt);

This function will insert the given certificate into the bag. This is just a wrapper over gnutls_pkcs12_bag_set_data().

Parameters

bag

The bag

 

crt

the certificate to be copied.

 

Returns

the index of the added bag on success, or a negative value on failure.


gnutls_pkcs12_bag_set_privkey ()

int
gnutls_pkcs12_bag_set_privkey (gnutls_pkcs12_bag_t bag,
                               gnutls_x509_privkey_t privkey,
                               const char *password,
                               unsigned  flags);

This function will insert the given private key into the bag. This is just a wrapper over gnutls_pkcs12_bag_set_data().

Parameters

bag

The bag

 

privkey

the private key to be copied.

 

password

the password to protect the key with (may be NULL)

 

flags

should be one of gnutls_pkcs_encrypt_flags_t elements bitwise or'd

 

Returns

the index of the added bag on success, or a negative value on failure.


gnutls_pkcs12_bag_init ()

int
gnutls_pkcs12_bag_init (gnutls_pkcs12_bag_t *bag);

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.

Parameters

bag

A pointer to the type to be initialized

 

Returns

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


gnutls_pkcs12_bag_deinit ()

void
gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t bag);

This function will deinitialize a PKCS12 Bag structure.

Parameters

bag

A pointer to the type to be initialized

 

gnutls_pkcs12_bag_get_count ()

int
gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t bag);

This function will return the number of the elements within the bag.

Parameters

bag

The bag

 

Returns

Number of elements in bag, or an negative error code on error.


gnutls_pkcs12_bag_get_key_id ()

int
gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t bag,
                              unsigned  indx,
                              gnutls_datum_t *id);

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.

Parameters

bag

The bag

 

indx

The bag's element to add the id

 

id

where the ID will be copied (to be treated as const)

 

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 ()

int
gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t bag,
                              unsigned  indx,
                              const gnutls_datum_t *id);

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.

Parameters

bag

The bag

 

indx

The bag's element to add the id

 

id

the ID

 

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_friendly_name ()

int
gnutls_pkcs12_bag_get_friendly_name (gnutls_pkcs12_bag_t bag,
                                     unsigned  indx,
                                     char **name);

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.

Parameters

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)

 

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_friendly_name ()

int
gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t bag,
                                     unsigned  indx,
                                     const char *name);

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.

Parameters

bag

The bag

 

indx

The bag's element to add the id

 

name

the name

 

Returns

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value. or a negative error code on error.

Types and Values

gnutls_pkcs12_t

typedef struct gnutls_pkcs12_int *gnutls_pkcs12_t;

gnutls_pkcs12_bag_t

typedef struct gnutls_pkcs12_bag_int *gnutls_pkcs12_bag_t;

GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED

#define GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED 1

enum gnutls_pkcs12_bag_type_t

Enumeration of different PKCS 12 bag types.

Members

GNUTLS_BAG_EMPTY

Empty PKCS-12 bag.

 

GNUTLS_BAG_PKCS8_ENCRYPTED_KEY

PKCS-12 bag with PKCS-8 encrypted key.

 

GNUTLS_BAG_PKCS8_KEY

PKCS-12 bag with PKCS-8 key.

 

GNUTLS_BAG_CERTIFICATE

PKCS-12 bag with certificate.

 

GNUTLS_BAG_CRL

PKCS-12 bag with CRL.

 

GNUTLS_BAG_SECRET

PKCS-12 bag with secret PKCS-9 keys.

 

GNUTLS_BAG_ENCRYPTED

Encrypted PKCS-12 bag.

 

GNUTLS_BAG_UNKNOWN

Unknown PKCS-12 bag.

 

gnutls_pkcs12_bag_int

typedef struct {
	struct bag_element element[MAX_BAG_ELEMENTS];
	unsigned bag_elements;
} gnutls_pkcs12_bag_int;

gnutls_pkcs12_int

typedef struct {
	asn1_node pkcs12;
	unsigned expanded;
} gnutls_pkcs12_int;