»Home
»News
»Download
»Documentation
     »oathtool(1)
     »pskctool(1)
     »Liboath API
     »PSKC Tutorial
     »Libpskc API
     »pam_oath
»Contribute
OATH Toolkit
One-time password components

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

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