XML Security Library

LibXML2
LibXSLT
OpenSSL

keys

keys — Crypto key object functions.

Stability Level

Stable, unless otherwise indicated

Description

Functions

xmlSecKeyUseWithInitialize ()

int
xmlSecKeyUseWithInitialize (xmlSecKeyUseWithPtr keyUseWith);

Initializes keyUseWith object.

Parameters

keyUseWith

the pointer to information about key application/user.

Returns

0 on success or a negative value if an error occurs.


xmlSecKeyUseWithFinalize ()

void
xmlSecKeyUseWithFinalize (xmlSecKeyUseWithPtr keyUseWith);

Finalizes keyUseWith object.

Parameters

keyUseWith

the pointer to information about key application/user.


xmlSecKeyUseWithReset ()

void
xmlSecKeyUseWithReset (xmlSecKeyUseWithPtr keyUseWith);

Resets the keyUseWith to its state after initialization.

Parameters

keyUseWith

the pointer to information about key application/user.


xmlSecKeyUseWithCopy ()

int
xmlSecKeyUseWithCopy (xmlSecKeyUseWithPtr dst,
                      xmlSecKeyUseWithPtr src);

Copies information from dst to src .

Parameters

dst

the pointer to destination object.

src

the pointer to source object.

Returns

0 on success or a negative value if an error occurs.


xmlSecKeyUseWithCreate ()

xmlSecKeyUseWithPtr
xmlSecKeyUseWithCreate (const xmlChar *application,
                        const xmlChar *identifier);

Creates new xmlSecKeyUseWith object. The caller is responsible for destroying returned object with xmlSecKeyUseWithDestroy function.

Parameters

application

the application value.

identifier

the identifier value.

Returns

pointer to newly created object or NULL if an error occurs.


xmlSecKeyUseWithDuplicate ()

xmlSecKeyUseWithPtr
xmlSecKeyUseWithDuplicate (xmlSecKeyUseWithPtr keyUseWith);

Duplicates keyUseWith object. The caller is responsible for destroying returned object with xmlSecKeyUseWithDestroy function.

Parameters

keyUseWith

the pointer to information about key application/user.

Returns

pointer to newly created object or NULL if an error occurs.


xmlSecKeyUseWithDestroy ()

void
xmlSecKeyUseWithDestroy (xmlSecKeyUseWithPtr keyUseWith);

Destroys keyUseWith created with xmlSecKeyUseWithCreate or xmlSecKeyUseWithDuplicate functions.

Parameters

keyUseWith

the pointer to information about key application/user.


xmlSecKeyUseWithSet ()

int
xmlSecKeyUseWithSet (xmlSecKeyUseWithPtr keyUseWith,
                     const xmlChar *application,
                     const xmlChar *identifier);

Sets application and identifier in the keyUseWith .

Parameters

keyUseWith

the pointer to information about key application/user.

application

the new application value.

identifier

the new identifier value.

Returns

0 on success or a negative value if an error occurs.


xmlSecKeyUseWithDebugDump ()

void
xmlSecKeyUseWithDebugDump (xmlSecKeyUseWithPtr keyUseWith,
                           FILE *output);

Prints xmlSecKeyUseWith debug information to a file output .

Parameters

keyUseWith

the pointer to information about key application/user.

output

the pointer to output FILE.


xmlSecKeyUseWithDebugXmlDump ()

void
xmlSecKeyUseWithDebugXmlDump (xmlSecKeyUseWithPtr keyUseWith,
                              FILE *output);

Prints xmlSecKeyUseWith debug information to a file output in XML format.

Parameters

keyUseWith

the pointer to information about key application/user.

output

the pointer to output FILE.


xmlSecKeyUseWithPtrListGetKlass ()

xmlSecPtrListId
xmlSecKeyUseWithPtrListGetKlass (void);

The key data list klass.

Returns

pointer to the key data list klass.


xmlSecKeyReqInitialize ()

int
xmlSecKeyReqInitialize (xmlSecKeyReqPtr keyReq);

Initialize key requirements object. Caller is responsible for cleaning it with xmlSecKeyReqFinalize function.

Parameters

keyReq

the pointer to key requirements object.

Returns

0 on success or a negative value if an error occurs.


xmlSecKeyReqFinalize ()

void
xmlSecKeyReqFinalize (xmlSecKeyReqPtr keyReq);

Cleans the key requirements object initialized with xmlSecKeyReqInitialize function.

Parameters

keyReq

the pointer to key requirements object.


xmlSecKeyReqReset ()

void
xmlSecKeyReqReset (xmlSecKeyReqPtr keyReq);

Resets key requirements object for new key search.

Parameters

keyReq

the pointer to key requirements object.


xmlSecKeyReqCopy ()

int
xmlSecKeyReqCopy (xmlSecKeyReqPtr dst,
                  xmlSecKeyReqPtr src);

Copies key requirements from src object to dst object.

Parameters

dst

the pointer to destination object.

src

the pointer to source object.

Returns

0 on success and a negative value if an error occurs.


xmlSecKeyReqMatchKey ()

int
xmlSecKeyReqMatchKey (xmlSecKeyReqPtr keyReq,
                      xmlSecKeyPtr key);

Checks whether key matches key requirements keyReq .

Parameters

keyReq

the pointer to key requirements object.

key

the pointer to key.

Returns

1 if key matches requirements, 0 if not and a negative value if an error occurs.


xmlSecKeyReqMatchKeyValue ()

int
xmlSecKeyReqMatchKeyValue (xmlSecKeyReqPtr keyReq,
                           xmlSecKeyDataPtr value);

Checks whether keyValue matches key requirements keyReq .

Parameters

keyReq

the pointer to key requirements.

value

the pointer to key value.

Returns

1 if key value matches requirements, 0 if not and a negative value if an error occurs.


xmlSecKeyReqDebugDump ()

void
xmlSecKeyReqDebugDump (xmlSecKeyReqPtr keyReq,
                       FILE *output);

Prints debug information about keyReq into output .

Parameters

keyReq

the pointer to key requirements object.

output

the pointer to output FILE.


xmlSecKeyReqDebugXmlDump ()

void
xmlSecKeyReqDebugXmlDump (xmlSecKeyReqPtr keyReq,
                          FILE *output);

Prints debug information about keyReq into output in XML format.

Parameters

keyReq

the pointer to key requirements object.

output

the pointer to output FILE.


xmlSecKeyCreate ()

xmlSecKeyPtr
xmlSecKeyCreate (void);

Allocates and initializes new key. Caller is responsible for freeing returned object with xmlSecKeyDestroy function.

Returns

the pointer to newly allocated xmlSecKey structure or NULL if an error occurs.


xmlSecKeyDestroy ()

void
xmlSecKeyDestroy (xmlSecKeyPtr key);

Destroys the key created using xmlSecKeyCreate function.

Parameters

key

the pointer to key.


xmlSecKeyEmpty ()

void
xmlSecKeyEmpty (xmlSecKeyPtr key);

Clears the key data.

Parameters

key

the pointer to key.


xmlSecKeyDuplicate ()

xmlSecKeyPtr
xmlSecKeyDuplicate (xmlSecKeyPtr key);

Creates a duplicate of the given key .

Parameters

key

the pointer to the xmlSecKey structure.

Returns

the pointer to newly allocated xmlSecKey structure or NULL if an error occurs.


xmlSecKeyCopy ()

int
xmlSecKeyCopy (xmlSecKeyPtr keyDst,
               xmlSecKeyPtr keySrc);

Copies key data from keySrc to keyDst .

Parameters

keyDst

the destination key.

keySrc

the source key.

Returns

0 on success or a negative value if an error occurs.


xmlSecKeyGetName ()

const xmlChar *
xmlSecKeyGetName (xmlSecKeyPtr key);

Gets key name (see also xmlSecKeySetName function).

Parameters

key

the pointer to key.

Returns

key name.


xmlSecKeySetName ()

int
xmlSecKeySetName (xmlSecKeyPtr key,
                  const xmlChar *name);

Sets key name (see also xmlSecKeyGetName function).

Parameters

key

the pointer to key.

name

the new key name.

Returns

0 on success or a negative value if an error occurs.


xmlSecKeyGetType ()

xmlSecKeyDataType
xmlSecKeyGetType (xmlSecKeyPtr key);

Gets key type.

Parameters

key

the pointer to key.

Returns

key type.


xmlSecKeyGetValue ()

xmlSecKeyDataPtr
xmlSecKeyGetValue (xmlSecKeyPtr key);

Gets key value (see also xmlSecKeySetValue function).

Parameters

key

the pointer to key.

Returns

key value (crypto material).


xmlSecKeySetValue ()

int
xmlSecKeySetValue (xmlSecKeyPtr key,
                   xmlSecKeyDataPtr value);

Sets key value (see also xmlSecKeyGetValue function).

Parameters

key

the pointer to key.

value

the new value.

Returns

0 on success or a negative value if an error occurs.


xmlSecKeyGetData ()

xmlSecKeyDataPtr
xmlSecKeyGetData (xmlSecKeyPtr key,
                  xmlSecKeyDataId dataId);

Gets key's data.

Parameters

key

the pointer to key.

dataId

the requested data klass.

Returns

additional data associated with the key (see also xmlSecKeyAdoptData function).


xmlSecKeyEnsureData ()

xmlSecKeyDataPtr
xmlSecKeyEnsureData (xmlSecKeyPtr key,
                     xmlSecKeyDataId dataId);

If necessary, creates key data of dataId klass and adds to key .

Parameters

key

the pointer to key.

dataId

the requested data klass.

Returns

pointer to key data or NULL if an error occurs.


xmlSecKeyAdoptData ()

int
xmlSecKeyAdoptData (xmlSecKeyPtr key,
                    xmlSecKeyDataPtr data);

Adds data to the key . The data object will be destroyed by key .

Parameters

key

the pointer to key.

data

the pointer to key data.

Returns

0 on success or a negative value otherwise.


xmlSecKeyDebugDump ()

void
xmlSecKeyDebugDump (xmlSecKeyPtr key,
                    FILE *output);

Prints the information about the key to the output .

Parameters

key

the pointer to key.

output

the pointer to output FILE.


xmlSecKeyDebugXmlDump ()

void
xmlSecKeyDebugXmlDump (xmlSecKeyPtr key,
                       FILE *output);

Prints the information about the key to the output in XML format.

Parameters

key

the pointer to key.

output

the pointer to output FILE.


xmlSecKeyGenerate ()

xmlSecKeyPtr
xmlSecKeyGenerate (xmlSecKeyDataId dataId,
                   xmlSecSize sizeBits,
                   xmlSecKeyDataType type);

Generates new key of requested klass dataId and type .

Parameters

dataId

the requested key klass (rsa, dsa, aes, ...).

sizeBits

the new key size (in bits!).

type

the new key type (session, permanent, ...).

Returns

pointer to newly created key or NULL if an error occurs.


xmlSecKeyGenerateByName ()

xmlSecKeyPtr
xmlSecKeyGenerateByName (const xmlChar *name,
                         xmlSecSize sizeBits,
                         xmlSecKeyDataType type);

Generates new key of requested klass and type .

Parameters

name

the requested key klass name (rsa, dsa, aes, ...).

sizeBits

the new key size (in bits!).

type

the new key type (session, permanent, ...).

Returns

pointer to newly created key or NULL if an error occurs.


xmlSecKeyMatch ()

int
xmlSecKeyMatch (xmlSecKeyPtr key,
                const xmlChar *name,
                xmlSecKeyReqPtr keyReq);

Checks whether the key matches the given criteria.

Parameters

key

the pointer to key.

name

the pointer to key name (may be NULL).

keyReq

the pointer to key requirements.

Returns

1 if the key satisfies the given criteria or 0 otherwise.


xmlSecKeyReadBuffer ()

xmlSecKeyPtr
xmlSecKeyReadBuffer (xmlSecKeyDataId dataId,
                     xmlSecBuffer *buffer);

Reads the key value of klass dataId from a buffer.

Parameters

dataId

the key value data klass.

buffer

the buffer that contains the binary data.

Returns

pointer to newly created key or NULL if an error occurs.


xmlSecKeyReadBinaryFile ()

xmlSecKeyPtr
xmlSecKeyReadBinaryFile (xmlSecKeyDataId dataId,
                         const char *filename);

Reads the key value of klass dataId from a binary file filename .

Parameters

dataId

the key value data klass.

filename

the key binary filename.

Returns

pointer to newly created key or NULL if an error occurs.


xmlSecKeyReadMemory ()

xmlSecKeyPtr
xmlSecKeyReadMemory (xmlSecKeyDataId dataId,
                     const xmlSecByte *data,
                     xmlSecSize dataSize);

Reads the key value of klass dataId from a memory block data .

Parameters

dataId

the key value data klass.

data

the memory containing the key

dataSize

the size of the memory block

Returns

pointer to newly created key or NULL if an error occurs.


xmlSecKeyIsValid()

#define             xmlSecKeyIsValid(key)

Macro. Returns 1 if key is not NULL and key->id is not NULL or 0 otherwise.

Parameters

key

the pointer to key.


xmlSecKeyCheckId()

#define             xmlSecKeyCheckId(key, keyId)

Macro. Returns 1 if key is valid and key 's id is equal to keyId .

Parameters

key

the pointer to key.

keyId

the key Id.


xmlSecKeyPtrListGetKlass ()

xmlSecPtrListId
xmlSecKeyPtrListGetKlass (void);

The keys list klass.

Returns

keys list id.

Types and Values

xmlSecKeyUsage

typedef unsigned int                    xmlSecKeyUsage;

The key usage.


xmlSecKeyUsageSign

#define xmlSecKeyUsageSign              0x00000001

Key can be used in any way.


xmlSecKeyUsageVerify

#define xmlSecKeyUsageVerify            0x00000002

Key for signing.


xmlSecKeyUsageEncrypt

#define xmlSecKeyUsageEncrypt           0x00000004

Key for signature verification.


xmlSecKeyUsageDecrypt

#define xmlSecKeyUsageDecrypt           0x00000008

An encryption key.


xmlSecKeyUsageKeyExchange

#define xmlSecKeyUsageKeyExchange       0x00000010

The key is used for key exchange.


xmlSecKeyUsageAny

#define xmlSecKeyUsageAny               0xFFFFFFFF

A decryption key.


struct xmlSecKeyUseWith

struct xmlSecKeyUseWith {
    xmlChar*                    application;
    xmlChar*                    identifier;

    void*                       reserved1;
    void*                       reserved2;
};

Information about application and user of the key.

Members

xmlChar *application;

the application.

xmlChar *identifier;

the identifier.

void *reserved1;

reserved for future use.

void *reserved2;

reserved for future use.


xmlSecKeyUseWithPtrListId

#define xmlSecKeyUseWithPtrListId       xmlSecKeyUseWithPtrListGetKlass()

The keys list klass.


struct xmlSecKeyReq

struct xmlSecKeyReq {
    xmlSecKeyDataId             keyId;
    xmlSecKeyDataType           keyType;
    xmlSecKeyUsage              keyUsage;
    xmlSecSize                  keyBitsSize;
    xmlSecPtrList               keyUseWithList;

    void*                       reserved1;
    void*                       reserved2;
};

The key requirements information.

Members

xmlSecKeyDataId keyId;

the desired key value klass.

xmlSecKeyDataType keyType;

the desired key type.

xmlSecKeyUsage keyUsage;

the desired key usage.

xmlSecSize keyBitsSize;

the desired key size (in bits!).

xmlSecPtrList keyUseWithList;

the desired key use with application/identifier information.

void *reserved1;

reserved for future use.

void *reserved2;

reserved for future use.


struct xmlSecKey

struct xmlSecKey {
    xmlChar*                            name;
    xmlSecKeyDataPtr                    value;
    xmlSecPtrListPtr                    dataList;
    xmlSecKeyUsage                      usage;
    time_t                              notValidBefore;
    time_t                              notValidAfter;
};

The key.

Members

xmlChar *name;

the key name.

xmlSecKeyDataPtr value;

the key value.

xmlSecPtrListPtr dataList;

the key data list.

xmlSecKeyUsage usage;

the key usage.

time_t notValidBefore;

the start key validity interval.

time_t notValidAfter;

the end key validity interval.


xmlSecKeyPtrListId

#define xmlSecKeyPtrListId      xmlSecKeyPtrListGetKlass()

The keys list klass.