1 /** 

     2  * XML Security Library (http://www.aleksey.com/xmlsec).

     3  *

     4  * Keys Manager

     5  * 

     6  * This is free software; see Copyright file in the source

     7  * distribution for preciese wording.

     8  * 

     9  * Copyright (C) 2002-2003 Aleksey Sanin <aleksey@aleksey.com>

    10  * Portion Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. 

    11  */

    12 #ifndef __XMLSEC_KEYSMGMR_H__

    13 #define __XMLSEC_KEYSMGMR_H__    

    14 

    15 #ifdef __cplusplus

    16 extern "C" {

    17 #endif /* __cplusplus */ 

    18 

    19 #include "xmlsec_config.h"

    20 

    21 #include "xmlsec_xmlsec.h"

    22 #include "xmlsec_list.h"

    23 #include "xmlsec_keys.h"

    24 #include "xmlsec_keysdata.h"

    25 #include "xmlsec_keyinfo.h"

    26 

    27 typedef const struct _xmlSecKeyKlass 			xmlSecKeyKlass, 

    28 							*xmlSecKeyId; 

    29 typedef const struct _xmlSecKeyStoreKlass 		xmlSecKeyStoreKlass, 

    30 							*xmlSecKeyStoreId; 

    31 

    32 

    33 /****************************************************************************

    34  *

    35  * Keys Manager

    36  *

    37  ***************************************************************************/

    38 XMLSEC_EXPORT xmlSecKeysMngrPtr 	xmlSecKeysMngrCreate		(void);

    39 XMLSEC_EXPORT void			xmlSecKeysMngrDestroy		(xmlSecKeysMngrPtr mngr);

    40 

    41 XMLSEC_EXPORT xmlSecKeyPtr		xmlSecKeysMngrFindKey		(xmlSecKeysMngrPtr mngr,

    42 									 const xmlChar* name,

    43 									 xmlSecKeyInfoCtxPtr keyInfoCtx);

    44 

    45 XMLSEC_EXPORT int			xmlSecKeysMngrAdoptKeysStore	(xmlSecKeysMngrPtr mngr,

    46 									 xmlSecKeyStorePtr store);

    47 XMLSEC_EXPORT xmlSecKeyStorePtr		xmlSecKeysMngrGetKeysStore	(xmlSecKeysMngrPtr mngr);

    48 

    49 XMLSEC_EXPORT int			xmlSecKeysMngrAdoptDataStore	(xmlSecKeysMngrPtr mngr,

    50 									 xmlSecKeyDataStorePtr store);

    51 XMLSEC_EXPORT xmlSecKeyDataStorePtr	xmlSecKeysMngrGetDataStore	(xmlSecKeysMngrPtr mngr,

    52 									 xmlSecKeyDataStoreId id);

    53 

    54 /**

    55  * xmlSecGetKeyCallback:

    56  * @keyInfoNode: 		the pointer to <dsig:KeyInfo/> node.

    57  * @keyInfoCtx:			the pointer to <dsig:KeyInfo/> node processing context.

    58  *

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

    60  *

    61  * Returns the pointer to key or NULL if the key is not found or 

    62  * an error occurs.

    63  */

    64 typedef xmlSecKeyPtr 	(*xmlSecGetKeyCallback)		(xmlNodePtr keyInfoNode,

    65 							 xmlSecKeyInfoCtxPtr keyInfoCtx);

    66 

    67 /**

    68  * xmlSecKeysMngr:

    69  * @keysStore:			the key store (list of keys known to keys manager).

    70  * @storesList:			the list of key data stores known to keys manager.

    71  * @getKey: 			the callback used to read <dsig:KeyInfo/> node.

    72  *

    73  * The keys manager structure.

    74  */

    75 struct _xmlSecKeysMngr {	

    76     xmlSecKeyStorePtr		keysStore;	

    77     xmlSecPtrList		storesList;	

    78     xmlSecGetKeyCallback	getKey;		

    79 };

    80 

    81 

    82 XMLSEC_EXPORT xmlSecKeyPtr 	xmlSecKeysMngrGetKey	(xmlNodePtr keyInfoNode,

    83 							 xmlSecKeyInfoCtxPtr keyInfoCtx);

    84 

    85 

    86 /**************************************************************************

    87  *

    88  * xmlSecKeyStore

    89  *

    90  *************************************************************************/

    91 /**

    92  * xmlSecKeyStore:

    93  * @id: 		the store id (#xmlSecKeyStoreId).

    94  * @reserved0:		reserved for the future.

    95  * @reserved1:		reserved for the future.

    96  *

    97  * The keys store. 

    98  */

    99 struct _xmlSecKeyStore {

   100     xmlSecKeyStoreId			id;

   101 

   102     /* for the future */

   103     void*				reserved0;

   104     void*				reserved1;

   105 };

   106 

   107 XMLSEC_EXPORT xmlSecKeyStorePtr xmlSecKeyStoreCreate		(xmlSecKeyStoreId id);

   108 XMLSEC_EXPORT void		xmlSecKeyStoreDestroy		(xmlSecKeyStorePtr store);

   109 XMLSEC_EXPORT xmlSecKeyPtr	xmlSecKeyStoreFindKey		(xmlSecKeyStorePtr store,

   110 								 const xmlChar* name,

   111  								 xmlSecKeyInfoCtxPtr keyInfoCtx);

   112 /**

   113  * xmlSecKeyStoreGetName:

   114  * @store: 		the pointer to store.

   115  *

   116  * Macro. Returns key store name.

   117  */

   118 #define xmlSecKeyStoreGetName(store) \

   119     ((xmlSecKeyStoreIsValid((store))) ? \

   120       xmlSecKeyStoreKlassGetName((store)->id) : NULL)

   121 

   122 /**

   123  * xmlSecKeyStoreIsValid:

   124  * @store: 		the pointer to store.

   125  *

   126  * Macro. Returns 1 if @store is not NULL and @store->id is not NULL

   127  * or 0 otherwise.

   128  */ 

   129 #define xmlSecKeyStoreIsValid(store) \

   130 	((( store ) != NULL) && ((( store )->id) != NULL))

   131 /**

   132  * xmlSecKeyStoreCheckId:

   133  * @store: 		the pointer to store.

   134  * @storeId: 		the store Id.

   135  *

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

   137  */

   138 #define xmlSecKeyStoreCheckId(store, storeId) \

   139  	(xmlSecKeyStoreIsValid(( store )) && \

   140 	((( store )->id) == ( storeId )))

   141 

   142 /**

   143  * xmlSecKeyStoreCheckSize:

   144  * @store: 		the pointer to store.

   145  * @size: 		the expected size.

   146  *

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

   148  */

   149 #define xmlSecKeyStoreCheckSize(store, size) \

   150  	(xmlSecKeyStoreIsValid(( store )) && \

   151 	 (( store )->id->objSize >= size))

   152 

   153 

   154 /**************************************************************************

   155  *

   156  * xmlSecKeyStoreKlass

   157  *

   158  *************************************************************************/

   159 /**

   160  * xmlSecKeyStoreIdUnknown:

   161  *

   162  * The "unknown" id.

   163  */

   164 #define xmlSecKeyStoreIdUnknown 			((xmlSecKeyDataStoreId)NULL)

   165 

   166 /** 

   167  * xmlSecKeyStoreInitializeMethod:

   168  * @store: 		the store.

   169  *

   170  * Keys store specific initialization method.

   171  *

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

   173  */

   174 typedef int			(*xmlSecKeyStoreInitializeMethod)	(xmlSecKeyStorePtr store);

   175 

   176 /** 

   177  * xmlSecKeyStoreFinalizeMethod:

   178  * @store: 		the store.

   179  *

   180  * Keys store specific finalization (destroy) method.

   181  */

   182 typedef void			(*xmlSecKeyStoreFinalizeMethod)		(xmlSecKeyStorePtr store);

   183 

   184 /** 

   185  * xmlSecKeyStoreFindKeyMethod:

   186  * @store: 		the store.

   187  * @name:		the desired key name.

   188  * @keyInfoCtx: 	the pointer to key info context.

   189  *

   190  * Keys store specific find method. The caller is responsible for destroying 

   191  * the returned key using #xmlSecKeyDestroy method.

   192  *

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

   194  */

   195 typedef xmlSecKeyPtr		(*xmlSecKeyStoreFindKeyMethod)	(xmlSecKeyStorePtr store,

   196 								 const xmlChar* name,

   197 								 xmlSecKeyInfoCtxPtr keyInfoCtx);

   198 

   199 /**

   200  * xmlSecKeyStoreKlass:

   201  * @klassSize:		the store klass size.

   202  * @objSize:		the store obj size.

   203  * @name:		the store's name.

   204  * @initialize:		the store's initialization method.

   205  * @finalize:		the store's finalization (destroy) method.

   206  * @findKey:		the store's find method.

   207  * @reserved0:		reserved for the future.

   208  * @reserved1:		reserved for the future.

   209  *

   210  * The keys store id (klass).

   211  */

   212 struct _xmlSecKeyStoreKlass {

   213     xmlSecSize				klassSize;

   214     xmlSecSize				objSize;

   215 

   216     /* data */

   217     const xmlChar*			name;    

   218         

   219     /* constructors/destructor */

   220     xmlSecKeyStoreInitializeMethod	initialize;

   221     xmlSecKeyStoreFinalizeMethod	finalize;

   222     xmlSecKeyStoreFindKeyMethod		findKey;

   223 

   224     /* for the future */

   225     void*				reserved0;

   226     void*				reserved1;

   227 };

   228 

   229 /**

   230  * xmlSecKeyStoreKlassGetName:

   231  * @klass:		the pointer to store klass.

   232  * 

   233  * Macro. Returns store klass name.

   234  */

   235 #define xmlSecKeyStoreKlassGetName(klass) \

   236 	(((klass)) ? ((klass)->name) : NULL)

   237 

   238 

   239 /****************************************************************************

   240  *

   241  * Simple Keys Store

   242  *

   243  ***************************************************************************/

   244 /**

   245  * xmlSecSimpleKeysStoreId:

   246  *

   247  * A simple keys store klass id.

   248  */

   249 #define xmlSecSimpleKeysStoreId		xmlSecSimpleKeysStoreGetKlass()

   250 XMLSEC_EXPORT xmlSecKeyStoreId		xmlSecSimpleKeysStoreGetKlass	(void);

   251 XMLSEC_EXPORT int			xmlSecSimpleKeysStoreAdoptKey	(xmlSecKeyStorePtr store,

   252 									 xmlSecKeyPtr key);

   253 XMLSEC_EXPORT int			xmlSecSimpleKeysStoreLoad 	(xmlSecKeyStorePtr store,

   254 									 const char *uri,

   255 									 xmlSecKeysMngrPtr keysMngr);

   256 XMLSEC_EXPORT int			xmlSecSimpleKeysStoreSave	(xmlSecKeyStorePtr store, 

   257 									 const char *filename,

   258 									 xmlSecKeyDataType type);

   259 XMLSEC_EXPORT xmlSecPtrListPtr		xmlSecSimpleKeysStoreGetKeys	(xmlSecKeyStorePtr store);

   260 

   261 

   262 #ifdef __cplusplus

   263 }

   264 #endif /* __cplusplus */

   265 

   266 #endif /* __XMLSEC_KEYSMGMR_H__ */

   267