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

## Synopsis

    typedef     xmlSecKeyUsage;
    #define     xmlSecKeyUsageSign
    #define     xmlSecKeyUsageVerify
    #define     xmlSecKeyUsageEncrypt
    #define     xmlSecKeyUsageDecrypt
    #define     xmlSecKeyUsageKeyExchange
    #define     xmlSecKeyUsageAny
    int         xmlSecKeyUseWithInitialize      (xmlSecKeyUseWithPtr keyUseWith);
    void        xmlSecKeyUseWithFinalize        (xmlSecKeyUseWithPtr keyUseWith);
    void        xmlSecKeyUseWithReset           (xmlSecKeyUseWithPtr keyUseWith);
    int         xmlSecKeyUseWithCopy            (xmlSecKeyUseWithPtr dst,
                                                 xmlSecKeyUseWithPtr src);
    xmlSecKeyUseWithPtr xmlSecKeyUseWithCreate  (const xmlChar *application,
                                                 const xmlChar *identifier);
    xmlSecKeyUseWithPtr xmlSecKeyUseWithDuplicate
                                                (xmlSecKeyUseWithPtr keyUseWith);
    void        xmlSecKeyUseWithDestroy         (xmlSecKeyUseWithPtr keyUseWith);
    int         xmlSecKeyUseWithSet             (xmlSecKeyUseWithPtr keyUseWith,
                                                 const xmlChar *application,
                                                 const xmlChar *identifier);
    void        xmlSecKeyUseWithDebugDump       (xmlSecKeyUseWithPtr keyUseWith,
                                                 FILE *output);
    void        xmlSecKeyUseWithDebugXmlDump    (xmlSecKeyUseWithPtr keyUseWith,
                                                 FILE *output);
    struct      xmlSecKeyUseWith;
    #define     xmlSecKeyUseWithPtrListId
    xmlSecPtrListId xmlSecKeyUseWithPtrListGetKlass
                                                (void);
    struct      xmlSecKeyReq;
    int         xmlSecKeyReqInitialize          (xmlSecKeyReqPtr keyReq);
    void        xmlSecKeyReqFinalize            (xmlSecKeyReqPtr keyReq);
    void        xmlSecKeyReqReset               (xmlSecKeyReqPtr keyReq);
    int         xmlSecKeyReqCopy                (xmlSecKeyReqPtr dst,
                                                 xmlSecKeyReqPtr src);
    int         xmlSecKeyReqMatchKey            (xmlSecKeyReqPtr keyReq,
                                                 xmlSecKeyPtr key);
    int         xmlSecKeyReqMatchKeyValue       (xmlSecKeyReqPtr keyReq,
                                                 xmlSecKeyDataPtr value);
    void        xmlSecKeyReqDebugDump           (xmlSecKeyReqPtr keyReq,
                                                 FILE *output);
    void        xmlSecKeyReqDebugXmlDump        (xmlSecKeyReqPtr keyReq,
                                                 FILE *output);
    struct      xmlSecKey;
    xmlSecKeyPtr xmlSecKeyCreate                (void);
    void        xmlSecKeyDestroy                (xmlSecKeyPtr key);
    void        xmlSecKeyEmpty                  (xmlSecKeyPtr key);
    xmlSecKeyPtr xmlSecKeyDuplicate             (xmlSecKeyPtr key);
    int         xmlSecKeyCopy                   (xmlSecKeyPtr keyDst,
                                                 xmlSecKeyPtr keySrc);
    const xmlChar* xmlSecKeyGetName             (xmlSecKeyPtr key);
    int         xmlSecKeySetName                (xmlSecKeyPtr key,
                                                 const xmlChar *name);
    xmlSecKeyDataType xmlSecKeyGetType          (xmlSecKeyPtr key);
    xmlSecKeyDataPtr xmlSecKeyGetValue          (xmlSecKeyPtr key);
    int         xmlSecKeySetValue               (xmlSecKeyPtr key,
                                                 xmlSecKeyDataPtr value);
    xmlSecKeyDataPtr xmlSecKeyGetData           (xmlSecKeyPtr key,
                                                 xmlSecKeyDataId dataId);
    xmlSecKeyDataPtr xmlSecKeyEnsureData        (xmlSecKeyPtr key,
                                                 xmlSecKeyDataId dataId);
    int         xmlSecKeyAdoptData              (xmlSecKeyPtr key,
                                                 xmlSecKeyDataPtr data);
    void        xmlSecKeyDebugDump              (xmlSecKeyPtr key,
                                                 FILE *output);
    void        xmlSecKeyDebugXmlDump           (xmlSecKeyPtr key,
                                                 FILE *output);
    xmlSecKeyPtr xmlSecKeyGenerate              (xmlSecKeyDataId dataId,
                                                 xmlSecSize sizeBits,
                                                 xmlSecKeyDataType type);
    xmlSecKeyPtr xmlSecKeyGenerateByName        (const xmlChar *name,
                                                 xmlSecSize sizeBits,
                                                 xmlSecKeyDataType type);
    int         xmlSecKeyMatch                  (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
    xmlSecPtrListId xmlSecKeyPtrListGetKlass    (void);

## Description

## 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` |
void *`reserved2` |

### 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*                       eserved2;
    };

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` |
void *`reserved1` |
void *`eserved2` |

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