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

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