keys: XML Security Library Reference Manual

## keys keys — Crypto key object functions. |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | xmlSecKeyUseWithInitialize ()
void | xmlSecKeyUseWithFinalize ()
void | xmlSecKeyUseWithReset ()
int | xmlSecKeyUseWithCopy ()
xmlSecKeyUseWithPtr | xmlSecKeyUseWithCreate ()
xmlSecKeyUseWithPtr | xmlSecKeyUseWithDuplicate ()
void | xmlSecKeyUseWithDestroy ()
int | xmlSecKeyUseWithSet ()
void | xmlSecKeyUseWithDebugDump ()
void | xmlSecKeyUseWithDebugXmlDump ()
xmlSecPtrListId | xmlSecKeyUseWithPtrListGetKlass ()
int | xmlSecKeyReqInitialize ()
void | xmlSecKeyReqFinalize ()
void | xmlSecKeyReqReset ()
int | xmlSecKeyReqCopy ()
int | xmlSecKeyReqMatchKey ()
int | xmlSecKeyReqMatchKeyValue ()
void | xmlSecKeyReqDebugDump ()
void | xmlSecKeyReqDebugXmlDump ()
xmlSecKeyPtr | xmlSecKeyCreate ()
void | xmlSecKeyDestroy ()
void | xmlSecKeyEmpty ()
xmlSecKeyPtr | xmlSecKeyDuplicate ()
int | xmlSecKeyCopy ()
const xmlChar * | xmlSecKeyGetName ()
int | xmlSecKeySetName ()
xmlSecKeyDataType | xmlSecKeyGetType ()
xmlSecKeyDataPtr | xmlSecKeyGetValue ()
int | xmlSecKeySetValue ()
xmlSecKeyDataPtr | xmlSecKeyGetData ()
xmlSecKeyDataPtr | xmlSecKeyEnsureData ()
int | xmlSecKeyAdoptData ()
void | xmlSecKeyDebugDump ()
void | xmlSecKeyDebugXmlDump ()
xmlSecKeyPtr | xmlSecKeyGenerate ()
xmlSecKeyPtr | xmlSecKeyGenerateByName ()
int | xmlSecKeyMatch ()
xmlSecKeyPtr | xmlSecKeyReadBuffer ()
xmlSecKeyPtr | xmlSecKeyReadBinaryFile ()
xmlSecKeyPtr | xmlSecKeyReadMemory ()
#define | xmlSecKeyIsValid()
#define | xmlSecKeyCheckId()
xmlSecPtrListId | xmlSecKeyPtrListGetKlass ()

## Types and Values

typedef | xmlSecKeyUsage
#define | xmlSecKeyUsageSign
#define | xmlSecKeyUsageVerify
#define | xmlSecKeyUsageEncrypt
#define | xmlSecKeyUsageDecrypt
#define | xmlSecKeyUsageKeyExchange
#define | xmlSecKeyUsageAny
struct | xmlSecKeyUseWith
#define | xmlSecKeyUseWithPtrListId
struct | xmlSecKeyReq
struct | xmlSecKey
#define | xmlSecKeyPtrListId

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

### xmlSecKeyUsageVerify

    #define xmlSecKeyUsageVerify            0x00000002

Key for signature verification.

### xmlSecKeyUsageEncrypt

    #define xmlSecKeyUsageEncrypt           0x00000004

An encryption key.

### xmlSecKeyUsageDecrypt

    #define xmlSecKeyUsageDecrypt           0x00000008

A decryption key.

### xmlSecKeyUsageKeyExchange

    #define xmlSecKeyUsageKeyExchange       0x00000010

The key is used for key exchange.

### xmlSecKeyUsageAny

    #define xmlSecKeyUsageAny               0xFFFFFFFF

Key can be used in any way.

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