pkcs12

## pkcs12 pkcs12 |

## Functions

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

## Types and Values

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

## Description

## Functions

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

    void
    gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t bag);

This function will deinitialize a PKCS12 Bag structure.

#### Parameters

bag | The structure to be initialized |

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

    int
    gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t bag);

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

#### Parameters

bag | The bag |

#### Returns

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

### gnutls_pkcs12_bag_get_data ()

    int
    gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t bag,
                                int 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_get_friendly_name ()

    int
    gnutls_pkcs12_bag_get_friendly_name (gnutls_pkcs12_bag_t bag,
                                         int 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_get_key_id ()

    int
    gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t bag,
                                  int 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_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 | The structure to be initialized |

#### Returns

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

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

    int
    gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t bag,
                                         int 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.

### gnutls_pkcs12_bag_set_key_id ()

    int
    gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t bag,
                                  int 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_deinit ()

    void
    gnutls_pkcs12_deinit (gnutls_pkcs12_t pkcs12);

This function will deinitialize a PKCS12 structure.

#### Parameters

pkcs12 | The structure to be initialized |

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

#### 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 | Holds the pkcs12 structure |
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_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 | should contain a gnutls_pkcs12_t structure |
pass | The password for the MAC |

#### Returns

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

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

#### Returns

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

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

#### Returns

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

### gnutls_pkcs12_init ()

    int
    gnutls_pkcs12_init (gnutls_pkcs12_t *pkcs12);

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

#### Parameters

pkcs12 | The structure to be initialized |

#### 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 structure |
bag | An initialized bag |

#### Returns

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

### 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 blob in `p12blob` and extracts the private key, the corresponding certificate chain, and any additional certificates and a CRL.

The `extra_certs_ret` and `extra_certs_len` parameters are optional and both may be set to `NULL`. If either is non-`NULL`, then both must be set.

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

A PKCS12 file may contain many keys and/or certificates, and there is no way to identify which key/certificate pair you want. You should make sure the PKCS12 file only contain one key/certificate pair and/or one CRL.

It is believed that the limitations of this function are acceptable for common usage, and that any more flexibility would introduce complexity that would make it harder to use this functionality at all.

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.

#### Parameters

p12 | the PKCS12 blob. |
password | optional password used to decrypt PKCS12 blob, 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 blob (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

### 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 structure |
pass | The password for the MAC |

#### Returns

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

## Types and Values

### GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED

    #define GNUTLS_PKCS12_SP_INCLUDE_SELF_SIGNED 1

### gnutls_pkcs12_bag_int

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

### gnutls_pkcs12_bag_t

    typedef struct gnutls_pkcs12_bag_int *gnutls_pkcs12_bag_t;

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

    typedef struct {
    	ASN1_TYPE pkcs12;
    } gnutls_pkcs12_int;

### gnutls_pkcs12_t

    typedef struct gnutls_pkcs12_int *gnutls_pkcs12_t;