keysmngr: XML Security Library Reference Manual

keysmngr

keysmngr — Keys manager object functions.

Stability Level

Stable, unless otherwise indicated

Functions

xmlSecKeysMngrPtr	xmlSecKeysMngrCreate ()
void	xmlSecKeysMngrDestroy ()
xmlSecKeyPtr	xmlSecKeysMngrFindKey ()
xmlSecKeyPtr	xmlSecKeysMngrFindKeyFromX509Data ()
int	xmlSecKeysMngrAdoptKeysStore ()
xmlSecKeyStorePtr	xmlSecKeysMngrGetKeysStore ()
int	xmlSecKeysMngrAdoptDataStore ()
xmlSecKeyDataStorePtr	xmlSecKeysMngrGetDataStore ()
xmlSecKeyPtr	(*xmlSecGetKeyCallback) ()
xmlSecKeyPtr	xmlSecKeysMngrGetKey ()
xmlSecKeyStorePtr	xmlSecKeyStoreCreate ()
void	xmlSecKeyStoreDestroy ()
xmlSecKeyPtr	xmlSecKeyStoreFindKey ()
xmlSecKeyPtr	xmlSecKeyStoreFindKeyFromX509Data ()
#define	xmlSecKeyStoreGetName()
#define	xmlSecKeyStoreIsValid()
#define	xmlSecKeyStoreCheckId()
#define	xmlSecKeyStoreCheckSize()
int	(*xmlSecKeyStoreInitializeMethod) ()
void	(*xmlSecKeyStoreFinalizeMethod) ()
xmlSecKeyPtr	(*xmlSecKeyStoreFindKeyMethod) ()
xmlSecKeyPtr	(*xmlSecKeyStoreFindKeyFromX509DataMethod) ()
#define	xmlSecKeyStoreKlassGetName()
int	(*xmlSecSimpleKeysStoreAdoptKeyFunc) ()
xmlSecKeyStoreId	xmlSecSimpleKeysStoreGetKlass ()
int	xmlSecSimpleKeysStoreAdoptKey ()
int	xmlSecSimpleKeysStoreLoad ()
int	xmlSecSimpleKeysStoreLoad_ex ()
int	xmlSecSimpleKeysStoreSave ()
xmlSecPtrListPtr	xmlSecSimpleKeysStoreGetKeys ()

Types and Values

struct	xmlSecKeysMngr
struct	xmlSecKeyStore
#define	xmlSecKeyStoreIdUnknown
struct	xmlSecKeyStoreKlass
#define	xmlSecSimpleKeysStoreId

Description

Functions

xmlSecKeysMngrCreate ()

xmlSecKeysMngrPtr
xmlSecKeysMngrCreate (void);

Creates new keys manager. Caller is responsible for freeing it with xmlSecKeysMngrDestroy function.

Returns

the pointer to newly allocated keys manager or NULL if an error occurs.

xmlSecKeysMngrDestroy ()

void
xmlSecKeysMngrDestroy (xmlSecKeysMngrPtr mngr);

Destroys keys manager created with xmlSecKeysMngrCreate function.

Parameters

mngr

the pointer to keys manager.

xmlSecKeysMngrFindKey ()

xmlSecKeyPtr
xmlSecKeysMngrFindKey (xmlSecKeysMngrPtr mngr,
                       const xmlChar *name,
                       xmlSecKeyInfoCtxPtr keyInfoCtx);

Lookups key in the keys manager keys store. The caller is responsible for destroying the returned key using xmlSecKeyDestroy method.

Parameters

mngr	the pointer to keys manager.
name	the desired key name.
keyInfoCtx	the pointer to <dsig:KeyInfo/> node processing context.

Returns

the pointer to a key or NULL if key is not found or an error occurs.

xmlSecKeysMngrFindKeyFromX509Data ()

xmlSecKeyPtr
xmlSecKeysMngrFindKeyFromX509Data (xmlSecKeysMngrPtr mngr,
                                   xmlSecKeyX509DataValuePtr x509Data,
                                   xmlSecKeyInfoCtxPtr keyInfoCtx);

Lookups key in the keys manager keys store. The caller is responsible for destroying the returned key using xmlSecKeyDestroy method.

Parameters

mngr	the pointer to keys manager.
x509Data	the X509 data to use for searching the keys.
keyInfoCtx	the pointer to <dsig:KeyInfo/> node processing context.

Returns

the pointer to a key or NULL if key is not found or an error occurs.

xmlSecKeysMngrAdoptKeysStore ()

int
xmlSecKeysMngrAdoptKeysStore (xmlSecKeysMngrPtr mngr,
                              xmlSecKeyStorePtr store);

Adopts keys store in the keys manager mngr .

Parameters

mngr	the pointer to keys manager.
store	the pointer to keys store.

Returns

0 on success or a negative value if an error occurs.

xmlSecKeysMngrGetKeysStore ()

xmlSecKeyStorePtr
xmlSecKeysMngrGetKeysStore (xmlSecKeysMngrPtr mngr);

Gets the keys store.

Parameters

mngr

the pointer to keys manager.

Returns

the keys store in the keys manager mngr or NULL if there is no store or an error occurs.

xmlSecKeysMngrAdoptDataStore ()

int
xmlSecKeysMngrAdoptDataStore (xmlSecKeysMngrPtr mngr,
                              xmlSecKeyDataStorePtr store);

Adopts data store in the keys manager.

Parameters

mngr	the pointer to keys manager.
store	the pointer to data store.

Returns

0 on success or a negative value if an error occurs.

xmlSecKeysMngrGetDataStore ()

xmlSecKeyDataStorePtr
xmlSecKeysMngrGetDataStore (xmlSecKeysMngrPtr mngr,
                            xmlSecKeyDataStoreId id);

Lookups the data store of given klass id in the keys manager.

Parameters

mngr	the pointer to keys manager.
id	the desired data store klass.

Returns

pointer to data store or NULL if it is not found or an error occurs.

xmlSecGetKeyCallback ()

xmlSecKeyPtr
(*xmlSecGetKeyCallback) (xmlNodePtr keyInfoNode,
                         xmlSecKeyInfoCtxPtr keyInfoCtx);

Reads the <dsig:KeyInfo/> node keyInfoNode and extracts the key.

Parameters

keyInfoNode	the pointer to <dsig:KeyInfo/> node.
keyInfoCtx	the pointer to <dsig:KeyInfo/> node processing context.

Returns

the pointer to key or NULL if the key is not found or an error occurs.

xmlSecKeysMngrGetKey ()

xmlSecKeyPtr
xmlSecKeysMngrGetKey (xmlNodePtr keyInfoNode,
                      xmlSecKeyInfoCtxPtr keyInfoCtx);

Reads the <dsig:KeyInfo/> node keyInfoNode and extracts the key.

Parameters

keyInfoNode	the pointer to <dsig:KeyInfo/> node.
keyInfoCtx	the pointer to <dsig:KeyInfo/> node processing context.

Returns

the pointer to key or NULL if the key is not found or an error occurs.

xmlSecKeyStoreCreate ()

xmlSecKeyStorePtr
xmlSecKeyStoreCreate (xmlSecKeyStoreId id);

Creates new store of the specified klass klass . Caller is responsible for freeing the returned store by calling xmlSecKeyStoreDestroy function.

Parameters

the key store klass.

Returns

the pointer to newly allocated keys store or NULL if an error occurs.

xmlSecKeyStoreDestroy ()

void
xmlSecKeyStoreDestroy (xmlSecKeyStorePtr store);

Destroys the store created with xmlSecKeyStoreCreate function.

Parameters

store

the pointer to keys store.

xmlSecKeyStoreFindKey ()

xmlSecKeyPtr
xmlSecKeyStoreFindKey (xmlSecKeyStorePtr store,
                       const xmlChar *name,
                       xmlSecKeyInfoCtxPtr keyInfoCtx);

Lookups key in the store. The caller is responsible for destroying the returned key using xmlSecKeyDestroy method.

Parameters

store	the pointer to keys store.
name	the desired key name.
keyInfoCtx	the pointer to <dsig:KeyInfo/> node processing context.

Returns

the pointer to a key or NULL if key is not found or an error occurs.

xmlSecKeyStoreFindKeyFromX509Data ()

xmlSecKeyPtr
xmlSecKeyStoreFindKeyFromX509Data (xmlSecKeyStorePtr store,
                                   xmlSecKeyX509DataValuePtr x509Data,
                                   xmlSecKeyInfoCtxPtr keyInfoCtx);

Lookups key in the store. The caller is responsible for destroying the returned key using xmlSecKeyDestroy method.

Parameters

store	the pointer to keys store.
x509Data	the X509 data to use for search.
keyInfoCtx	the pointer to <dsig:KeyInfo/> node processing context.

Returns

the pointer to a key or NULL if key is not found or an error occurs.

xmlSecKeyStoreGetName()

#define             xmlSecKeyStoreGetName(store)

Macro. Returns key store name.

Parameters

store

the pointer to store.

xmlSecKeyStoreIsValid()

#define             xmlSecKeyStoreIsValid(store)

Macro. Returns 1 if store is not NULL and store->id is not NULL or 0 otherwise.

Parameters

store

the pointer to store.

xmlSecKeyStoreCheckId()

#define             xmlSecKeyStoreCheckId(store, storeId)

Macro. Returns 1 if store is valid and store 's id is equal to storeId .

Parameters

store	the pointer to store.
storeId	the store Id.

xmlSecKeyStoreCheckSize()

#define             xmlSecKeyStoreCheckSize(store, size)

Macro. Returns 1 if store is valid and stores 's object has at least size bytes.

Parameters

store	the pointer to store.
size	the expected size.

xmlSecKeyStoreInitializeMethod ()

int
(*xmlSecKeyStoreInitializeMethod) (xmlSecKeyStorePtr store);

Keys store specific initialization method.

Parameters

store

the store.

Returns

0 on success or a negative value if an error occurs.

xmlSecKeyStoreFinalizeMethod ()

void
(*xmlSecKeyStoreFinalizeMethod) (xmlSecKeyStorePtr store);

Keys store specific finalization (destroy) method.

Parameters

store

the store.

xmlSecKeyStoreFindKeyMethod ()

xmlSecKeyPtr
(*xmlSecKeyStoreFindKeyMethod) (xmlSecKeyStorePtr store,
                                const xmlChar *name,
                                xmlSecKeyInfoCtxPtr keyInfoCtx);

Keys store specific find method. The caller is responsible for destroying the returned key using xmlSecKeyDestroy method.

Parameters

store	the store.
name	the desired key name.
keyInfoCtx	the pointer to key info context.

Returns

the pointer to a key or NULL if key is not found or an error occurs.

xmlSecKeyStoreFindKeyFromX509DataMethod ()

xmlSecKeyPtr
(*xmlSecKeyStoreFindKeyFromX509DataMethod)
                               (xmlSecKeyStorePtr store,
                                xmlSecKeyX509DataValuePtr x509Data,
                                xmlSecKeyInfoCtxPtr keyInfoCtx);

Keys store specific find method. The caller is responsible for destroying the returned key using xmlSecKeyDestroy method.

Parameters

store	the store.
x509Data	the x509 data to lookup key.
keyInfoCtx	the pointer to key info context.

Returns

the pointer to a key or NULL if key is not found or an error occurs.

xmlSecKeyStoreKlassGetName()

#define             xmlSecKeyStoreKlassGetName(klass)

Macro. Returns store klass name.

Parameters

klass

the pointer to store klass.

xmlSecSimpleKeysStoreAdoptKeyFunc ()

int
(*xmlSecSimpleKeysStoreAdoptKeyFunc) (xmlSecKeyStorePtr store,
                                      xmlSecKeyPtr key);

Adds key to the store . On success, the store owns the key .

Parameters

store	the pointer to key store.
key	the pointer to key.

Returns

0 on success or a negative value if an error occurs.

xmlSecSimpleKeysStoreGetKlass ()

xmlSecKeyStoreId
xmlSecSimpleKeysStoreGetKlass (void);

The simple list based keys store klass.

Returns

simple list based keys store klass.

xmlSecSimpleKeysStoreAdoptKey ()

int
xmlSecSimpleKeysStoreAdoptKey (xmlSecKeyStorePtr store,
                               xmlSecKeyPtr key);

Adds key to the store .

Parameters

store	the pointer to simple keys store.
key	the pointer to key.

Returns

0 on success or a negative value if an error occurs.

xmlSecSimpleKeysStoreLoad ()

int
xmlSecSimpleKeysStoreLoad (xmlSecKeyStorePtr store,
                           const char *uri,
                           xmlSecKeysMngrPtr keysMngr);

Reads keys from an XML file.

Parameters

store	the pointer to simple keys store.
uri	the filename.
keysMngr	the pointer to associated keys manager.

Returns

0 on success or a negative value if an error occurs.

xmlSecSimpleKeysStoreLoad_ex ()

int
xmlSecSimpleKeysStoreLoad_ex (xmlSecKeyStorePtr store,
                              const char *uri,
                              xmlSecKeysMngrPtr keysMngr,
                              xmlSecSimpleKeysStoreAdoptKeyFunc adoptKeyFunc);

Reads keys from an XML file.

Parameters

store	the pointer to simple keys store.
uri	the filename.
keysMngr	the pointer to associated keys manager.
adoptKeyFunc	the callback to add the key to keys manager.

Returns

0 on success or a negative value if an error occurs.

xmlSecSimpleKeysStoreSave ()

int
xmlSecSimpleKeysStoreSave (xmlSecKeyStorePtr store,
                           const char *filename,
                           xmlSecKeyDataType type);

Writes keys from store to an XML file.

Parameters

store	the pointer to simple keys store.
filename	the filename.
type	the saved keys type (public, private, ...).

Returns

0 on success or a negative value if an error occurs.

xmlSecSimpleKeysStoreGetKeys ()

xmlSecPtrListPtr
xmlSecSimpleKeysStoreGetKeys (xmlSecKeyStorePtr store);

Gets list of keys from simple keys store.

Parameters

store

the pointer to simple keys store.

Returns

pointer to the list of keys stored in the keys store or NULL if an error occurs.

Types and Values

struct xmlSecKeysMngr

struct xmlSecKeysMngr {
    xmlSecKeyStorePtr           keysStore;
    xmlSecPtrList               storesList;
    xmlSecGetKeyCallback        getKey;
};

The keys manager structure.

Members

xmlSecKeyStorePtr `keysStore`;	the key store (list of keys known to keys manager).
xmlSecPtrList `storesList`;	the list of key data stores known to keys manager.
xmlSecGetKeyCallback `getKey`;	the callback used to read <dsig:KeyInfo/> node.

struct xmlSecKeyStore

struct xmlSecKeyStore {
    xmlSecKeyStoreId                    id;

    /* for the future */
    void*                               reserved0;
    void*                               reserved1;
};

The keys store.

Members

xmlSecKeyStoreId `id`;	the store id (xmlSecKeyStoreId).
void *`reserved0`;	reserved for the future.
void *`reserved1`;	reserved for the future.

xmlSecKeyStoreIdUnknown

#define xmlSecKeyStoreIdUnknown                         ((xmlSecKeyDataStoreId)NULL)

The "unknown" id.

struct xmlSecKeyStoreKlass

struct xmlSecKeyStoreKlass {
    xmlSecSize                          klassSize;
    xmlSecSize                          objSize;

    /* data */
    const xmlChar*                      name;

    /* constructors/destructor */
    xmlSecKeyStoreInitializeMethod              initialize;
    xmlSecKeyStoreFinalizeMethod                finalize;

    /* key loopkup */
    xmlSecKeyStoreFindKeyMethod                 findKey;
    xmlSecKeyStoreFindKeyFromX509DataMethod     findKeyFromX509Data;

    /* for the future */
    void*                               reserved0;
};

The keys store id (klass).

Members

xmlSecSize `klassSize`;	the store klass size.
xmlSecSize `objSize`;	the store obj size.
const xmlChar *`name`;	the store's name.
xmlSecKeyStoreInitializeMethod `initialize`;	the store's initialization method.
xmlSecKeyStoreFinalizeMethod `finalize`;	the store's finalization (destroy) method.
xmlSecKeyStoreFindKeyMethod `findKey`;	the store's method to find key by key name.
xmlSecKeyStoreFindKeyFromX509DataMethod `findKeyFromX509Data`;	the store's method to find key based on x509 data.
void *`reserved0`;	reserved for the future.

xmlSecSimpleKeysStoreId

#define xmlSecSimpleKeysStoreId         xmlSecSimpleKeysStoreGetKlass()

A simple keys store klass id.