»Home
»News
»Download
»Documentation
     »oathtool(1)
     »pskctool(1)
     »Liboath API
     »Libpskc Quickstart
     »Libpskc API
     »pam_oath
»Contribute
     »Code
     »Bug tracker
OATH Toolkit
One-time password components

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.