keys: XML Security Library Reference Manual

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 andkey2

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 (see also xmlSecKeyDataGetSize function).

Parameters

key

the pointer to key.

Returns

key size.

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.