- Home
- Download
- News
- Documentation

- FAQ
- Tutorial
- API reference
- Examples

- XML Digital Signature

- Online Verifier

- XML Encryption
- XML Canonicalization
- Reporting Bugs
- Mailing list
- Related
- Authors

# keysmngr

## Name

keysmngr -- Keys manager object support.

## Synopsis

    xmlSecKeyPtr        (*xmlSecGetKeyCallback)             (xmlNodePtr keyInfoNode,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
    struct              xmlSecKeyStore;
    #define             xmlSecKeyStoreCheckId               (store,
                                                             storeId)
    #define             xmlSecKeyStoreCheckSize             (store,
                                                             size)
    xmlSecKeyStorePtr   xmlSecKeyStoreCreate                (xmlSecKeyStoreId id);
    voidxmlSecKeyStoreDestroy               (xmlSecKeyStorePtr store);
    void                (*xmlSecKeyStoreFinalizeMethod)     (xmlSecKeyStorePtr store);
    xmlSecKeyPtrxmlSecKeyStoreFindKey               (xmlSecKeyStorePtr store,
                                                             const xmlChar *name,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
    xmlSecKeyPtr        (*xmlSecKeyStoreFindKeyMethod)      (xmlSecKeyStorePtr store,
                                                             const xmlChar *name,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
    #define             xmlSecKeyStoreGetName               (store)
    #define             xmlSecKeyStoreIdUnknown
    int                 (*xmlSecKeyStoreInitializeMethod)   (xmlSecKeyStorePtr store);
    #define             xmlSecKeyStoreIsValid               (store)
    struct              xmlSecKeyStoreKlass;
    #define             xmlSecKeyStoreKlassGetName          (klass)
    struct              xmlSecKeysMngr;
    intxmlSecKeysMngrAdoptDataStore        (xmlSecKeysMngrPtr mngr,
                                                             xmlSecKeyDataStorePtr store);
    intxmlSecKeysMngrAdoptKeysStore        (xmlSecKeysMngrPtr mngr,
                                                             xmlSecKeyStorePtr store);
    xmlSecKeysMngrPtr   xmlSecKeysMngrCreate                (void);
    voidxmlSecKeysMngrDestroy               (xmlSecKeysMngrPtr mngr);
    xmlSecKeyPtrxmlSecKeysMngrFindKey               (xmlSecKeysMngrPtr mngr,
                                                             const xmlChar *name,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
    xmlSecKeyDataStorePtrxmlSecKeysMngrGetDataStore        (xmlSecKeysMngrPtr mngr,
                                                             xmlSecKeyDataStoreId id);
    xmlSecKeyPtrxmlSecKeysMngrGetKey                (xmlNodePtr keyInfoNode,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);
    xmlSecKeyStorePtrxmlSecKeysMngrGetKeysStore          (xmlSecKeysMngrPtr mngr);
    intxmlSecSimpleKeysStoreAdoptKey       (xmlSecKeyStorePtr store,
                                                             xmlSecKeyPtr key);
    xmlSecPtrListPtrxmlSecSimpleKeysStoreGetKeys        (xmlSecKeyStorePtr store);
    xmlSecKeyStoreIdxmlSecSimpleKeysStoreGetKlass       (void);
    #define             xmlSecSimpleKeysStoreId
    intxmlSecSimpleKeysStoreLoad           (xmlSecKeyStorePtr store,
                                                             const char *uri,
                                                             xmlSecKeysMngrPtr keysMngr);
    intxmlSecSimpleKeysStoreSave           (xmlSecKeyStorePtr store,
                                                             const char *filename,
                                                             xmlSecKeyDataType type);

## Description

Keys manager object support.

## Details

### xmlSecGetKeyCallback ()

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

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

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

### struct xmlSecKeyStore

    struct xmlSecKeyStore {
        xmlSecKeyStoreId                    id;

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

The keys store.

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

### xmlSecKeyStoreCheckId()

    #define             xmlSecKeyStoreCheckId(store, storeId)

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

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

`store` : | the pointer to store.
`size` : | the expected size.

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

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

`store` : | the pointer to keys store.

### xmlSecKeyStoreFinalizeMethod ()

    void                (*xmlSecKeyStoreFinalizeMethod)     (xmlSecKeyStorePtr store);

Keys store specific finalization (destroy) method.

`store` : | the 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.

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

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

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

### xmlSecKeyStoreGetName()

    #define             xmlSecKeyStoreGetName(store)

Macro. Returns key store name.

`store` : | the pointer to store.

### xmlSecKeyStoreIdUnknown

    #define xmlSecKeyStoreIdUnknown                         ((xmlSecKeyDataStoreId)NULL)

The "unknown" id.

### xmlSecKeyStoreInitializeMethod ()

    int                 (*xmlSecKeyStoreInitializeMethod)   (xmlSecKeyStorePtr store);

Keys store specific initialization method.

`store` : | the store.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecKeyStoreIsValid()

    #define             xmlSecKeyStoreIsValid(store)

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

`store` : | the pointer to store.

### struct xmlSecKeyStoreKlass

    struct xmlSecKeyStoreKlass {
        xmlSecSize                          klassSize;
        xmlSecSize                          objSize;

        /* data */
        const xmlChar*                      name;

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

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

The keys store id (klass).

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 find method.
void *`reserved0`; | reserved for the future.
void *`reserved1`; | reserved for the future.

### xmlSecKeyStoreKlassGetName()

    #define             xmlSecKeyStoreKlassGetName(klass)

Macro. Returns store klass name.

`klass` : | the pointer to store klass.

### struct xmlSecKeysMngr

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

The keys manager structure.

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.

### xmlSecKeysMngrAdoptDataStore ()

    int                 xmlSecKeysMngrAdoptDataStore        (xmlSecKeysMngrPtr mngr,
                                                             xmlSecKeyDataStorePtr store);

Adopts data store in the keys manager.

`mngr` : | the pointer to keys manager.
`store` : | the pointer to data store.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecKeysMngrAdoptKeysStore ()

    int                 xmlSecKeysMngrAdoptKeysStore        (xmlSecKeysMngrPtr mngr,
                                                             xmlSecKeyStorePtr store);

Adopts keys store in the keys manager `mngr`.

`mngr` : | the pointer to keys manager.
`store` : | the pointer to keys store.
Returns : | 0 on success or a negative value if an error occurs.

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

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

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

### xmlSecKeysMngrGetDataStore ()

    xmlSecKeyDataStorePtr xmlSecKeysMngrGetDataStore        (xmlSecKeysMngrPtr mngr,
                                                             xmlSecKeyDataStoreId id);

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

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

### xmlSecKeysMngrGetKey ()

    xmlSecKeyPtr        xmlSecKeysMngrGetKey                (xmlNodePtr keyInfoNode,
                                                             xmlSecKeyInfoCtxPtr keyInfoCtx);

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

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

### xmlSecKeysMngrGetKeysStore ()

    xmlSecKeyStorePtr   xmlSecKeysMngrGetKeysStore          (xmlSecKeysMngrPtr mngr);

Gets the keys store.

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

### xmlSecSimpleKeysStoreAdoptKey ()

    int                 xmlSecSimpleKeysStoreAdoptKey       (xmlSecKeyStorePtr store,
                                                             xmlSecKeyPtr key);

Adds `key` to the `store`.

`store` : | the pointer to simple keys store.
`key` : | the pointer to key.
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.

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

### xmlSecSimpleKeysStoreGetKlass ()

    xmlSecKeyStoreId    xmlSecSimpleKeysStoreGetKlass       (void);

The simple list based keys store klass.

Returns : | simple list based keys store klass.

### xmlSecSimpleKeysStoreId

    #define xmlSecSimpleKeysStoreId         xmlSecSimpleKeysStoreGetKlass()

A simple keys store klass id.

### xmlSecSimpleKeysStoreLoad ()

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

Reads keys from an XML file.

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

### xmlSecSimpleKeysStoreSave ()

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

Writes keys from `store` to an XML file.

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