keys: XML Security Library Reference Manual

Home Download GitHub News Documentation FAQ Tutorial API reference Examples XML Digital Signature XML Encryption XML Canonicalization Reporting Bugs Mailing list Related Authors
## 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 ()
int | xmlSecKeySwap ()
const xmlChar * | xmlSecKeyGetName ()
int | xmlSecKeySetName ()
int | xmlSecKeySetNameEx ()
xmlSecKeyDataType | xmlSecKeyGetType ()
xmlSecKeyDataPtr | xmlSecKeyGetValue ()
int | xmlSecKeySetValue ()
xmlSecSize | xmlSecKeyGetSize ()
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 | xmlSecKeyUsageKeyDerive
#define | xmlSecKeyUsageKeyAgreement
#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. ### xmlSecKeySwap ()
    int
    xmlSecKeySwap (xmlSecKeyPtr key1,
                   xmlSecKeyPtr key2);
Swaps key data for `key1` and`key2` #### Parameters
key1 | the first key. |
key2 | the second 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. ### xmlSecKeySetNameEx ()
    int
    xmlSecKeySetNameEx (xmlSecKeyPtr key,
                        const xmlChar *name,
                        xmlSecSize nameSize);
Sets key name (see also xmlSecKeyGetName function). #### Parameters
key | the pointer to key. |
name | the new key name. |
nameSize | the size of `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. ### xmlSecKeyGetSize ()
    xmlSecSize
    xmlSecKeyGetSize (xmlSecKeyPtr key);
Gets key size (in bits). Also see xmlSecKeyDataGetSize function. #### Parameters
key | the pointer to key. |
#### Returns key size (in bits). ### 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
Deprecated. The key is used for key exchange. ### xmlSecKeyUsageKeyDerive
    #define xmlSecKeyUsageKeyDerive         0x00000020
The key is used for key derivation. ### xmlSecKeyUsageKeyAgreement
    #define xmlSecKeyUsageKeyAgreement      0x00000040
The key is used for key agreement. ### 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.