pkcs12: GnuTLS API Reference Manual

## pkcs12 pkcs12 |

## Functions

int | gnutls_pkcs12_init ()
void | gnutls_pkcs12_deinit ()
int | gnutls_pkcs12_import ()
int | gnutls_pkcs12_export ()
int | gnutls_pkcs12_export2 ()
int | gnutls_pkcs12_get_bag ()
int | gnutls_pkcs12_set_bag ()
int | gnutls_pkcs12_generate_mac ()
int | gnutls_pkcs12_generate_mac2 ()
int | gnutls_pkcs12_verify_mac ()
int | gnutls_pkcs12_bag_decrypt ()
int | gnutls_pkcs12_bag_encrypt ()
int | gnutls_pkcs12_bag_enc_info ()
int | gnutls_pkcs12_mac_info ()
int | gnutls_pkcs12_simple_parse ()
int | gnutls_pkcs12_bag_get_data ()
int | gnutls_pkcs12_bag_set_data ()
int | gnutls_pkcs12_bag_set_crl ()
int | gnutls_pkcs12_bag_set_crt ()
int | gnutls_pkcs12_bag_set_privkey ()
int | gnutls_pkcs12_bag_init ()
void | gnutls_pkcs12_bag_deinit ()
int | gnutls_pkcs12_bag_get_count ()
int | gnutls_pkcs12_bag_get_key_id ()
int | gnutls_pkcs12_bag_set_key_id ()
int | gnutls_pkcs12_bag_get_friendly_name ()
int | gnutls_pkcs12_bag_set_friendly_name ()

## Types and Values

typedef | gnutls_pkcs12_t
typedef | gnutls_pkcs12_bag_t
#define | GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED
enum | gnutls_pkcs12_bag_type_t
| gnutls_pkcs12_bag_int
| gnutls_pkcs12_int

## 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;