- Home
- Download
- News
- Documentation

- FAQ
- Tutorial
- API reference
- Examples

- XML Digital Signature

- Online Verifier

- XML Encryption
- XML Canonicalization
- Reporting Bugs
- Mailing list
- Related
- Authors

# keys

## Name

keys -- Crypto key object definition.

## Synopsis

    typedef             xmlSecKeyUsage;
    #define             xmlSecKeyUsageSign
    #define             xmlSecKeyUsageVerify
    #define             xmlSecKeyUsageEncrypt
    #define             xmlSecKeyUsageDecrypt
    #define             xmlSecKeyUsageKeyExchange
    #define             xmlSecKeyUsageAny
    intxmlSecKeyUseWithInitialize          (xmlSecKeyUseWithPtr keyUseWith);
    voidxmlSecKeyUseWithFinalize            (xmlSecKeyUseWithPtr keyUseWith);
    voidxmlSecKeyUseWithReset               (xmlSecKeyUseWithPtr keyUseWith);
    intxmlSecKeyUseWithCopy                (xmlSecKeyUseWithPtr dst,
                                                             xmlSecKeyUseWithPtr src);
    xmlSecKeyUseWithPtr  xmlSecKeyUseWithCreate             (const xmlChar *application,
                                                             const xmlChar *identifier);
    xmlSecKeyUseWithPtrxmlSecKeyUseWithDuplicate          (xmlSecKeyUseWithPtr keyUseWith);
    voidxmlSecKeyUseWithDestroy             (xmlSecKeyUseWithPtr keyUseWith);
    intxmlSecKeyUseWithSet                 (xmlSecKeyUseWithPtr keyUseWith,
                                                             const xmlChar *application,
                                                             const xmlChar *identifier);
    voidxmlSecKeyUseWithDebugDump           (xmlSecKeyUseWithPtr keyUseWith,
                                                             FILE *output);
    voidxmlSecKeyUseWithDebugXmlDump        (xmlSecKeyUseWithPtr keyUseWith,
                                                             FILE *output);
    struct              xmlSecKeyUseWith;
    #define             xmlSecKeyUseWithPtrListId
    xmlSecPtrListIdxmlSecKeyUseWithPtrListGetKlass     (void);
    struct              xmlSecKeyReq;
    intxmlSecKeyReqInitialize              (xmlSecKeyReqPtr keyReq);
    voidxmlSecKeyReqFinalize                (xmlSecKeyReqPtr keyReq);
    voidxmlSecKeyReqReset                   (xmlSecKeyReqPtr keyReq);
    intxmlSecKeyReqCopy                    (xmlSecKeyReqPtr dst,
                                                             xmlSecKeyReqPtr src);
    intxmlSecKeyReqMatchKey                (xmlSecKeyReqPtr keyReq,
                                                             xmlSecKeyPtr key);
    intxmlSecKeyReqMatchKeyValue           (xmlSecKeyReqPtr keyReq,
                                                             xmlSecKeyDataPtr value);
    voidxmlSecKeyReqDebugDump               (xmlSecKeyReqPtr keyReq,
                                                             FILE *output);
    voidxmlSecKeyReqDebugXmlDump            (xmlSecKeyReqPtr keyReq,
                                                             FILE *output);
    struct              xmlSecKey;
    xmlSecKeyPtr        xmlSecKeyCreate                     (void);
    voidxmlSecKeyDestroy                    (xmlSecKeyPtr key);
    voidxmlSecKeyEmpty                      (xmlSecKeyPtr key);
    xmlSecKeyPtrxmlSecKeyDuplicate                  (xmlSecKeyPtr key);
    intxmlSecKeyCopy                       (xmlSecKeyPtr keyDst,
                                                             xmlSecKeyPtr keySrc);
    const xmlChar*      xmlSecKeyGetName                    (xmlSecKeyPtr key);
    intxmlSecKeySetName                    (xmlSecKeyPtr key,
                                                             const xmlChar *name);
    xmlSecKeyDataType   xmlSecKeyGetType                    (xmlSecKeyPtr key);
    xmlSecKeyDataPtrxmlSecKeyGetValue                   (xmlSecKeyPtr key);
    intxmlSecKeySetValue                   (xmlSecKeyPtr key,
                                                             xmlSecKeyDataPtr value);
    xmlSecKeyDataPtrxmlSecKeyGetData                    (xmlSecKeyPtr key,
                                                             xmlSecKeyDataId dataId);
    xmlSecKeyDataPtrxmlSecKeyEnsureData                 (xmlSecKeyPtr key,
                                                             xmlSecKeyDataId dataId);
    intxmlSecKeyAdoptData                  (xmlSecKeyPtr key,
                                                             xmlSecKeyDataPtr data);
    voidxmlSecKeyDebugDump                  (xmlSecKeyPtr key,
                                                             FILE *output);
    voidxmlSecKeyDebugXmlDump               (xmlSecKeyPtr key,
                                                             FILE *output);
    xmlSecKeyPtr        xmlSecKeyGenerate                   (xmlSecKeyDataId dataId,
                                                             xmlSecSize sizeBits,
                                                             xmlSecKeyDataType type);
    xmlSecKeyPtr        xmlSecKeyGenerateByName             (const xmlChar *name,
                                                             xmlSecSize sizeBits,
                                                             xmlSecKeyDataType type);
    intxmlSecKeyMatch                      (xmlSecKeyPtr key,
                                                             const xmlChar *name,
                                                             xmlSecKeyReqPtr keyReq);
    xmlSecKeyPtr        xmlSecKeyReadBuffer                 (xmlSecKeyDataId dataId,
                                                             xmlSecBuffer *buffer);
    xmlSecKeyPtr        xmlSecKeyReadBinaryFile             (xmlSecKeyDataId dataId,
                                                             const char *filename);
    xmlSecKeyPtr        xmlSecKeyReadMemory                 (xmlSecKeyDataId dataId,
                                                             const xmlSecByte *data,
                                                             xmlSecSize dataSize);
    #define             xmlSecKeyIsValid                    (key)
    #define             xmlSecKeyCheckId                    (key,
                                                             keyId)
    #define             xmlSecKeyPtrListId
    xmlSecPtrListIdxmlSecKeyPtrListGetKlass            (void);

## Description

Crypto key object definition.

## Details

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

### xmlSecKeyUseWithInitialize ()

    int                 xmlSecKeyUseWithInitialize          (xmlSecKeyUseWithPtr keyUseWith);

Initializes `keyUseWith` object.

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

`keyUseWith` : | the pointer to information about key application/user.

### xmlSecKeyUseWithReset ()

    void                xmlSecKeyUseWithReset               (xmlSecKeyUseWithPtr keyUseWith);

Resets the `keyUseWith` to its state after initialization.

`keyUseWith` : | the pointer to information about key application/user.

### xmlSecKeyUseWithCopy ()

    int                 xmlSecKeyUseWithCopy                (xmlSecKeyUseWithPtr dst,
                                                             xmlSecKeyUseWithPtr src);

Copies information from `dst` to `src`.

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

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

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

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

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

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

`keyUseWith` : | the pointer to information about key application/user.
`output` : | the pointer to output FILE.

### struct xmlSecKeyUseWith

    struct xmlSecKeyUseWith {
        xmlChar*                    application;
        xmlChar*                    identifier;

        void*                       reserved1;
        void*                       reserved2;
    };

Information about application and user of the key.

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.

### xmlSecKeyUseWithPtrListGetKlass ()

    xmlSecPtrListId     xmlSecKeyUseWithPtrListGetKlass     (void);

The key data list klass.

Returns : | pointer to the key data list klass.

### struct xmlSecKeyReq

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

        void*                       reserved1;
        void*                       reserved2;
    };

The key requirements information.

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.

### xmlSecKeyReqInitialize ()

    int                 xmlSecKeyReqInitialize              (xmlSecKeyReqPtr keyReq);

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

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

`keyReq` : | the pointer to key requirements object.

### xmlSecKeyReqReset ()

    void                xmlSecKeyReqReset                   (xmlSecKeyReqPtr keyReq);

Resets key requirements object for new key search.

`keyReq` : | the pointer to key requirements object.

### xmlSecKeyReqCopy ()

    int                 xmlSecKeyReqCopy                    (xmlSecKeyReqPtr dst,
                                                             xmlSecKeyReqPtr src);

Copies key requirements from `src` object to `dst` object.

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

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

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

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

`keyReq` : | the pointer to key requirements object.
`output` : | the pointer to output FILE.

### struct xmlSecKey

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

The key.

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.

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

`key` : | the pointer to key.

### xmlSecKeyEmpty ()

    void                xmlSecKeyEmpty                      (xmlSecKeyPtr key);

Clears the `key` data.

`key` : | the pointer to key.

### xmlSecKeyDuplicate ()

    xmlSecKeyPtr        xmlSecKeyDuplicate                  (xmlSecKeyPtr key);

Creates a duplicate of the given `key`.

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

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

`key` : | the pointer to key.
Returns : | key name.

### xmlSecKeySetName ()

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

Sets key name (see also xmlSecKeyGetName function).

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

`key` : | the pointer to key.
Returns : | key type.

### xmlSecKeyGetValue ()

    xmlSecKeyDataPtr    xmlSecKeyGetValue                   (xmlSecKeyPtr key);

Gets key value (see also xmlSecKeySetValue function).

`key` : | the pointer to key.
Returns : | key value (crypto material).

### xmlSecKeySetValue ()

    int                 xmlSecKeySetValue                   (xmlSecKeyPtr key,
                                                             xmlSecKeyDataPtr value);

Sets key value (see also xmlSecKeyGetValue function).

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

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

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

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

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

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

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

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

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

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

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

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

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

`key` : | the pointer to key.
`keyId` : | the key Id.

### xmlSecKeyPtrListId

    #define xmlSecKeyPtrListId      xmlSecKeyPtrListGetKlass()

The keys list klass.

### xmlSecKeyPtrListGetKlass ()

    xmlSecPtrListId     xmlSecKeyPtrListGetKlass            (void);

The keys list klass.

Returns : | keys list id.