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