container

## container container — High-level PSKC container handling. |

## Synopsis

    int                 pskc_add_keypackage                 (pskc_t *container,
                                                             pskc_key_t **key);
    int                 pskc_build_xml                      (pskc_t *container,
                                                             char **out,
                                                             size_t *len);
    void                pskc_done                           (pskc_t *container);
    const char *        pskc_get_id                         (pskc_t *container);
    pskc_key_t *        pskc_get_keypackage                 (pskc_t *container,
                                                             size_t i);
    int                 pskc_get_signed_p                   (pskc_t *container);
    const char *        pskc_get_version                    (pskc_t *container);
    int                 pskc_init                           (pskc_t **container);
    int                 pskc_output                         (pskc_t *container,
                                                             pskc_output_formats_t format,
                                                             char **out,
                                                             size_t *len);
    enum                pskc_output_formats_t;
    int                 pskc_parse_from_memory              (pskc_t *container,
                                                             size_t len,
                                                             const char *buffer);
    void                pskc_set_id                         (pskc_t *container,
                                                             const char *id);
    void                pskc_set_version                    (pskc_t *container,
                                                             const char *version);
    int                 pskc_sign_x509                      (pskc_t *container,
                                                             const char *key_file,
                                                             const char *cert_file);
    int                 pskc_validate                       (pskc_t *container,
                                                             int *isvalid);
    int                 pskc_verify_x509crt                 (pskc_t *container,
                                                             const char *cert_file,
                                                             int *valid_signature);

## Description

PSKC data is represented through the pskc_t type which is created by calling `pskc_init()` and destroyed by calling `pskc_done()`. You may parse PSKC data in XML form from a buffer by calling `pskc_parse_from_memory()`. To convert PSKC data to human readable form you may use `pskc_output()`. To validate PSKC data against the XML Schema, you may use `pskc_validate()`. To generate PSKC based on the internal parsed representation you may use `pskc_build_xml()` which takes a pskc_output_format enumeration to indicate output form.

The PSKC data structure is a high-level structure that only carries a version indicator (see `pskc_get_version()`), an optional identity field (see `pskc_get_id()`) and any number of pskc_key_t types, each containing one key (see `pskc_get_keypackage()`).

## Details

### pskc_add_keypackage ()

    int                 pskc_add_keypackage                 (pskc_t *container,
                                                             pskc_key_t **key);

Add a new a PSKC keypackage to the `container` and give back a pskc_key_t handle.

`container` : | a pskc_t handle, from `pskc_init()`.
`key` : | pointer to pskc_key_t key package handle.
Returns : | `PSKC_MALLOC_ERROR` on memory allocation errors, or `PSKC_OK` on success.

Since 2.2.0

### pskc_build_xml ()

    int                 pskc_build_xml                      (pskc_t *container,
                                                             char **out,
                                                             size_t *len);

This function builds a XML file from the data in `container`. As a convenience, it also converts the XML into a string placed in the newly allocated *`out` of length `len` using `pskc_output()` with `PSKC_OUTPUT_XML`.

`container` : | a pskc_t handle, from `pskc_init()`.
`out` : | pointer to output variable to hold newly allocated string.
`len` : | output variable holding length of *`out`.
Returns : | On success, `PSKC_OK` (zero) is returned, on memory allocation errors `PSKC_MALLOC_ERROR` is returned.

### pskc_done ()

    void                pskc_done                           (pskc_t *container);

This function releases the resources associated with the PSKC `container` handle.

`container` : | a pskc_t handle, from `pskc_init()`.

### pskc_get_id ()

    const char *        pskc_get_id                         (pskc_t *container);

Get the PSKC KeyContainer Id attribute.

`container` : | a pskc_t handle, from `pskc_init()`.
Returns : | a constant string (must not be deallocated) holding the content, or NULL if not set.

### pskc_get_keypackage ()

    pskc_key_t *        pskc_get_keypackage                 (pskc_t *container,
                                                             size_t i);

Get a PSKC keypackage pskc_key_t handle for the `i`'th key package in `container`. `i` is zero-based, i.e., 0 refer to the first key package, 1 refer to the second key package, and so on.

`container` : | a pskc_t handle, from `pskc_init()`.
`i` : | number of keypackage to get.
Returns : | NULL if there is no `i`'th key package, or a valid pskc_key_t pointer.

### pskc_get_signed_p ()

    int                 pskc_get_signed_p                   (pskc_t *container);

Check whether the container is signed or not (note that it does not validate the signature, merely checks whether there is one).

`container` : | a pskc_t handle, from `pskc_init()`.
Returns : | a non-0 value if the container contains a Signature element, 0 if there is no Signature element.

### pskc_get_version ()

    const char *        pskc_get_version                    (pskc_t *container);

Get the PSKC KeyContainer Version attribute. Normally this string is always "1.0" and a missing field is a syntax error according to the PSKC schema.

`container` : | a pskc_t handle, from `pskc_init()`.
Returns : | a constant string (must not be deallocated) holding the content, or NULL if not set.

### pskc_init ()

    int                 pskc_init                           (pskc_t **container);

This function initializes the PSKC `container` handle. The memory allocate can be released by calling `pskc_done()`.

`container` : | pointer to a pskc_t handle to initialize.
Returns : | On success, `PSKC_OK` (zero) is returned, on memory allocation errors `PSKC_MALLOC_ERROR` is returned.

### pskc_output ()

    int                 pskc_output                         (pskc_t *container,
                                                             pskc_output_formats_t format,
                                                             char **out,
                                                             size_t *len);

Convert PSKC data to a serialized string of the indicated type. This is usually used to convert the PSKC data to some human readable form.

`container` : | a pskc_t handle, from `pskc_init()`.
`format` : | an pskc_output_formats_t enumeration type indicating format.
`out` : | pointer to output variable holding newly allocated string.
`len` : | pointer to output variable hold length of *`out`.
Returns : | `PSKC_OK` on success, or an error code.

### enum pskc_output_formats_t

    typedef enum {
      PSKC_OUTPUT_HUMAN_COMPLETE = 0,
      PSKC_OUTPUT_XML = 1,
      PSKC_OUTPUT_INDENTED_XML = 2
    } pskc_output_formats_t;

Enumeration of different PSKC output formats.

`PSKC_OUTPUT_HUMAN_COMPLETE` | All information in human-readable format.
`PSKC_OUTPUT_XML` | Output container in XML format.
`PSKC_OUTPUT_INDENTED_XML` | Output container in intended XML format (will invalidate any XML Digital Signatures).

### pskc_parse_from_memory ()

    int                 pskc_parse_from_memory              (pskc_t *container,
                                                             size_t len,
                                                             const char *buffer);

This function will parse the XML data in `buffer` of `len` size into `container`. If `PSKC_PARSE_ERROR` is returned, parsing of some elements have failed but the `container` is still valid and contain partially parsed information. In this situation, you may continue but raise a warning.

`container` : | a pskc_t handle, from `pskc_init()`.
`len` : | length of `buffer`.
`buffer` : | XML data to parse.
Returns : | On success, `PSKC_OK` (zero) is returned, on memory allocation errors `PSKC_MALLOC_ERROR` is returned, on XML library errors `PSKC_XML_ERROR` is returned, on PSKC parse errors `PSKC_PARSE_ERROR` is returned.

### pskc_set_id ()

    void                pskc_set_id                         (pskc_t *container,
                                                             const char *id);

Set the PSKC KeyContainer Id attribute.

The pointer is stored in `container`, not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using `container`.

`container` : | a pskc_t handle, from `pskc_init()`.
`id` : | pointer to id string to set.

Since 2.2.0

### pskc_set_version ()

    void                pskc_set_version                    (pskc_t *container,
                                                             const char *version);

Set the PSKC KeyContainer Version attribute. Normally this string is always "1.0" and a missing field is a syntax error according to the PSKC schema.

The pointer is stored in `container`, not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using `container`.

`container` : | a pskc_t handle, from `pskc_init()`.
`version` : | pointer to version string to set.

Since 2.2.0

### pskc_sign_x509 ()

    int                 pskc_sign_x509                      (pskc_t *container,
                                                             const char *key_file,
                                                             const char *cert_file);

Sign PSKC data using X.509 certificate and private key.

`container` : | a pskc_t handle, from `pskc_init()`.
`key_file` : | filename of file containing private key.
`cert_file` : | filename of file containing corresponding X.509 certificate.
Returns : | On success, `PSKC_OK` (zero) is returned, or an error code.

### pskc_validate ()

    int                 pskc_validate                       (pskc_t *container,
                                                             int *isvalid);

This function validate the PSKC `container` handle the PSKC XML Schema.

`container` : | a pskc_t handle, from `pskc_init()`.
`isvalid` : | output variable holding validation result, non-0 for valid.
Returns : | On success, `PSKC_OK` (zero) is returned, or an error code.

### pskc_verify_x509crt ()

    int                 pskc_verify_x509crt                 (pskc_t *container,
                                                             const char *cert_file,
                                                             int *valid_signature);

Verify signature in PSKC data against trusted X.509 certificate.

`container` : | a pskc_t handle, from `pskc_init()`.
`cert_file` : | filename of file containing trusted X.509 certificate.
`valid_signature` : | output variable with result of verification.
Returns : | On success, `PSKC_OK` (zero) is returned, or an error code.