pkcs12

## pkcs12 pkcs12 |

## Synopsis

    struct              gnutls_pkcs12_int;
    typedef             gnutls_pkcs12_t;
    struct              gnutls_pkcs12_bag_int;
    typedef             gnutls_pkcs12_bag_t;
    int                 gnutls_pkcs12_init                  (gnutls_pkcs12_t *pkcs12);
    void                gnutls_pkcs12_deinit                (gnutls_pkcs12_t pkcs12);
    int                 gnutls_pkcs12_import                (gnutls_pkcs12_t pkcs12,
                                                             const gnutls_datum_t *data,
                                                             gnutls_x509_crt_fmt_t format,
                                                             unsigned int flags);
    int                 gnutls_pkcs12_export                (gnutls_pkcs12_t pkcs12,
                                                             gnutls_x509_crt_fmt_t format,
                                                             void *output_data,
                                                             size_t *output_data_size);
    int                 gnutls_pkcs12_get_bag               (gnutls_pkcs12_t pkcs12,
                                                             int indx,
                                                             gnutls_pkcs12_bag_t bag);
    int                 gnutls_pkcs12_set_bag               (gnutls_pkcs12_t pkcs12,
                                                             gnutls_pkcs12_bag_t bag);
    int                 gnutls_pkcs12_generate_mac          (gnutls_pkcs12_t pkcs12,
                                                             const char *pass);
    int                 gnutls_pkcs12_verify_mac            (gnutls_pkcs12_t pkcs12,
                                                             const char *pass);
    int                 gnutls_pkcs12_bag_decrypt           (gnutls_pkcs12_bag_t bag,
                                                             const char *pass);
    int                 gnutls_pkcs12_bag_encrypt           (gnutls_pkcs12_bag_t bag,
                                                             const char *pass,
                                                             unsigned int flags);
    enum                gnutls_pkcs12_bag_type_t;
    gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type     (gnutls_pkcs12_bag_t bag,
                                                             int indx);
    int                 gnutls_pkcs12_bag_get_data          (gnutls_pkcs12_bag_t bag,
                                                             int indx,
                                                             gnutls_datum_t *data);
    int                 gnutls_pkcs12_bag_set_data          (gnutls_pkcs12_bag_t bag,
                                                             gnutls_pkcs12_bag_type_t type,
                                                             const gnutls_datum_t *data);
    int                 gnutls_pkcs12_bag_set_crl           (gnutls_pkcs12_bag_t bag,
                                                             gnutls_x509_crl_t crl);
    int                 gnutls_pkcs12_bag_set_crt           (gnutls_pkcs12_bag_t bag,
                                                             gnutls_x509_crt_t crt);
    int                 gnutls_pkcs12_bag_init              (gnutls_pkcs12_bag_t *bag);
    void                gnutls_pkcs12_bag_deinit            (gnutls_pkcs12_bag_t bag);
    int                 gnutls_pkcs12_bag_get_count         (gnutls_pkcs12_bag_t bag);
    int                 gnutls_pkcs12_bag_get_key_id        (gnutls_pkcs12_bag_t bag,
                                                             int indx,
                                                             gnutls_datum_t *id);
    int                 gnutls_pkcs12_bag_set_key_id        (gnutls_pkcs12_bag_t bag,
                                                             int indx,
                                                             const gnutls_datum_t *id);
    int                 gnutls_pkcs12_bag_get_friendly_name (gnutls_pkcs12_bag_t bag,
                                                             int indx,
                                                             char **name);
    int                 gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t bag,
                                                             int indx,
                                                             const char *name);

## Description

## Details

### struct gnutls_pkcs12_int

    struct gnutls_pkcs12_int;

### gnutls_pkcs12_t

      typedef struct gnutls_pkcs12_int *gnutls_pkcs12_t;

### struct gnutls_pkcs12_bag_int

    struct gnutls_pkcs12_bag_int;

### gnutls_pkcs12_bag_t

      typedef struct gnutls_pkcs12_bag_int *gnutls_pkcs12_bag_t;

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

`pkcs12` : | The structure to be initialized
Returns : | On success, `GNUTLS_E_SUCCESS` is returned, otherwise a negative error value.

### gnutls_pkcs12_deinit ()

    void                gnutls_pkcs12_deinit                (gnutls_pkcs12_t pkcs12);

This function will deinitialize a PKCS12 structure.

`pkcs12` : | The structure 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".

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

`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 value will be returned, and 0 on success.

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

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

`pkcs12` : | should contain a gnutls_pkcs12_t structure
`bag` : | An initialized bag
Returns : | On success, `GNUTLS_E_SUCCESS` 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.

`pkcs12` : | should contain a gnutls_pkcs12_t structure
`pass` : | The password for the MAC
Returns : | On success, `GNUTLS_E_SUCCESS` 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.

`pkcs12` : | should contain a gnutls_pkcs12_t structure
`pass` : | The password for the MAC
Returns : | On success, `GNUTLS_E_SUCCESS` 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.

`bag` : | The bag
`pass` : | The password used for encryption, must be ASCII.
Returns : | On success, `GNUTLS_E_SUCCESS` (zero) is returned, otherwise an 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.

`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` (zero) is returned, otherwise an error code is returned.

### enum gnutls_pkcs12_bag_type_t

    typedef enum {
        GNUTLS_BAG_EMPTY = 0,
        GNUTLS_BAG_PKCS8_ENCRYPTED_KEY = 1,
        GNUTLS_BAG_PKCS8_KEY = 2,
        GNUTLS_BAG_CERTIFICATE = 3,
        GNUTLS_BAG_CRL = 4,
        GNUTLS_BAG_SECRET = 5,      /* Secret data. Underspecified in pkcs-12,
                                     * gnutls extension. We use the PKCS-9
                                     * random nonce ID 1.2.840.113549.1.9.25.3
                                     * to store randomly generated keys.
                                     */
        GNUTLS_BAG_ENCRYPTED = 10,
        GNUTLS_BAG_UNKNOWN = 20
    } gnutls_pkcs12_bag_type_t;

Enumeration of different PKCS 12 bag types.

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

    gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type     (gnutls_pkcs12_bag_t bag,
                                                             int indx);

This function will return the bag's type.

`bag` : | The bag
`indx` : | The element of the bag to get the type
Returns : | One of the gnutls_pkcs12_bag_type_t enumerations.

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

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

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

`bag` : | The bag
`crl` : | the CRL to be copied.
Returns : | the index of the added bag on success, or a negative value 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()`.

`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_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.

`bag` : | The structure to be initialized
Returns : | On success, `GNUTLS_E_SUCCESS` 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.

`bag` : | The structure 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 withing the bag.

`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,
                                                             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.

`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` is returned, otherwise a negative error value. or a negative value 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.

`bag` : | The bag
`indx` : | The bag's element to add the id
`id` : | the ID
Returns : | On success, `GNUTLS_E_SUCCESS` is returned, otherwise a negative error value. or a negative value on error.

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

`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` is returned, otherwise a negative error value. 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.

`bag` : | The bag
`indx` : | The bag's element to add the id
`name` : | the name
Returns : | On success, `GNUTLS_E_SUCCESS` is returned, otherwise a negative error value. or a negative value on error.