container: PSKC Library (libpskc) Manual

## container

container — High-level PSKC container handling.

## Functions

int | pskc_init ()
void | pskc_done ()
int | pskc_parse_from_memory ()
int | pskc_get_signed_p ()
int | pskc_validate ()
int | pskc_build_xml ()
int | pskc_sign_x509 ()
int | pskc_verify_x509crt ()
const char * | pskc_get_version ()
void | pskc_set_version ()
const char * | pskc_get_id ()
void | pskc_set_id ()
pskc_key_t * | pskc_get_keypackage ()
int | pskc_add_keypackage ()
int | pskc_output ()

## Types and Values

enum | pskc_output_formats_t

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

## Functions

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

#### Parameters

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

    void
    pskc_done (pskc_t *container);

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

#### Parameters

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

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

#### Parameters

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

#### Parameters

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

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

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

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

#### Parameters

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

#### Parameters

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

Since: 2.2.0

### pskc_get_id ()

    const char *
    pskc_get_id (pskc_t *container);

Get the PSKC KeyContainer Id attribute.

#### Parameters

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

#### Parameters

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

Since: 2.2.0

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

## Types and Values

### enum pskc_output_formats_t

Enumeration of different PSKC output formats.

#### Members

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