keys

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