keysmngr: XML Security Library Reference Manual

Home Download GitHub News Documentation FAQ Tutorial API reference Examples XML Digital Signature XML Encryption XML Canonicalization Reporting Bugs Mailing list Related Authors
## 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.