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-2016 Aleksey Sanin <aleksey@aleksey.com>. All Rights Reserved.
10  */
11 #ifndef __XMLSEC_KEYSMGMR_H__
12 #define __XMLSEC_KEYSMGMR_H__
13 
14 #include <xmlsec/xmlsec.h>
15 #include <xmlsec/list.h>
16 #include <xmlsec/keys.h>
17 #include <xmlsec/keysdata.h>
18 #include <xmlsec/keyinfo.h>
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif /* __cplusplus */
23 
24 typedef const struct _xmlSecKeyKlass                    xmlSecKeyKlass,
25                                                         *xmlSecKeyId;
26 typedef const struct _xmlSecKeyStoreKlass               xmlSecKeyStoreKlass,
27                                                         *xmlSecKeyStoreId;
28 
29 
30 /****************************************************************************
31  *
32  * Keys Manager
33  *
34  ***************************************************************************/
35 XMLSEC_EXPORT xmlSecKeysMngrPtr         xmlSecKeysMngrCreate            (void);
36 XMLSEC_EXPORT void                      xmlSecKeysMngrDestroy           (xmlSecKeysMngrPtr mngr);
37 
38 XMLSEC_EXPORT xmlSecKeyPtr              xmlSecKeysMngrFindKey           (xmlSecKeysMngrPtr mngr,
39                                                                          const xmlChar* name,
40                                                                          xmlSecKeyInfoCtxPtr keyInfoCtx);
41 
42 XMLSEC_EXPORT int                       xmlSecKeysMngrAdoptKeysStore    (xmlSecKeysMngrPtr mngr,
43                                                                          xmlSecKeyStorePtr store);
44 XMLSEC_EXPORT xmlSecKeyStorePtr         xmlSecKeysMngrGetKeysStore      (xmlSecKeysMngrPtr mngr);
45 
46 XMLSEC_EXPORT int                       xmlSecKeysMngrAdoptDataStore    (xmlSecKeysMngrPtr mngr,
47                                                                          xmlSecKeyDataStorePtr store);
48 XMLSEC_EXPORT xmlSecKeyDataStorePtr     xmlSecKeysMngrGetDataStore      (xmlSecKeysMngrPtr mngr,
49                                                                          xmlSecKeyDataStoreId id);
50 
51 /**
52  * xmlSecGetKeyCallback:
53  * @keyInfoNode:                the pointer to <dsig:KeyInfo/> node.
54  * @keyInfoCtx:                 the pointer to <dsig:KeyInfo/> node processing context.
55  *
56  * Reads the <dsig:KeyInfo/> node @keyInfoNode and extracts the key.
57  *
58  * Returns: the pointer to key or NULL if the key is not found or
59  * an error occurs.
60  */
61 typedef xmlSecKeyPtr    (*xmlSecGetKeyCallback)         (xmlNodePtr keyInfoNode,
62                                                          xmlSecKeyInfoCtxPtr keyInfoCtx);
63 
64 /**
65  * xmlSecKeysMngr:
66  * @keysStore:                  the key store (list of keys known to keys manager).
67  * @storesList:                 the list of key data stores known to keys manager.
68  * @getKey:                     the callback used to read <dsig:KeyInfo/> node.
69  *
70  * The keys manager structure.
71  */
72 struct _xmlSecKeysMngr {
73     xmlSecKeyStorePtr           keysStore;
74     xmlSecPtrList               storesList;
75     xmlSecGetKeyCallback        getKey;
76 };
77 
78 
79 XMLSEC_EXPORT xmlSecKeyPtr      xmlSecKeysMngrGetKey    (xmlNodePtr keyInfoNode,
80                                                          xmlSecKeyInfoCtxPtr keyInfoCtx);
81 
82 
83 /**************************************************************************
84  *
85  * xmlSecKeyStore
86  *
87  *************************************************************************/
88 /**
89  * xmlSecKeyStore:
90  * @id:                 the store id (#xmlSecKeyStoreId).
91  * @reserved0:          reserved for the future.
92  * @reserved1:          reserved for the future.
93  *
94  * The keys store.
95  */
96 struct _xmlSecKeyStore {
97     xmlSecKeyStoreId                    id;
98 
99     /* for the future */
100     void*                               reserved0;
101     void*                               reserved1;
102 };
103 
104 XMLSEC_EXPORT xmlSecKeyStorePtr xmlSecKeyStoreCreate            (xmlSecKeyStoreId id);
105 XMLSEC_EXPORT void              xmlSecKeyStoreDestroy           (xmlSecKeyStorePtr store);
106 XMLSEC_EXPORT xmlSecKeyPtr      xmlSecKeyStoreFindKey           (xmlSecKeyStorePtr store,
107                                                                  const xmlChar* name,
108                                                                  xmlSecKeyInfoCtxPtr keyInfoCtx);
109 /**
110  * xmlSecKeyStoreGetName:
111  * @store:              the pointer to store.
112  *
113  * Macro. Returns key store name.
114  */
115 #define xmlSecKeyStoreGetName(store) \
116     ((xmlSecKeyStoreIsValid((store))) ? \
117       xmlSecKeyStoreKlassGetName((store)->id) : NULL)
118 
119 /**
120  * xmlSecKeyStoreIsValid:
121  * @store:              the pointer to store.
122  *
123  * Macro. Returns 1 if @store is not NULL and @store->id is not NULL
124  * or 0 otherwise.
125  */
126 #define xmlSecKeyStoreIsValid(store) \
127         ((( store ) != NULL) && ((( store )->id) != NULL))
128 /**
129  * xmlSecKeyStoreCheckId:
130  * @store:              the pointer to store.
131  * @storeId:            the store Id.
132  *
133  * Macro. Returns 1 if @store is valid and @store's id is equal to @storeId.
134  */
135 #define xmlSecKeyStoreCheckId(store, storeId) \
136         (xmlSecKeyStoreIsValid(( store )) && \
137         ((( store )->id) == ( storeId )))
138 
139 /**
140  * xmlSecKeyStoreCheckSize:
141  * @store:              the pointer to store.
142  * @size:               the expected size.
143  *
144  * Macro. Returns 1 if @store is valid and @stores's object has at least @size bytes.
145  */
146 #define xmlSecKeyStoreCheckSize(store, size) \
147         (xmlSecKeyStoreIsValid(( store )) && \
148          (( store )->id->objSize >= size))
149 
150 
151 /**************************************************************************
152  *
153  * xmlSecKeyStoreKlass
154  *
155  *************************************************************************/
156 /**
157  * xmlSecKeyStoreIdUnknown:
158  *
159  * The "unknown" id.
160  */
161 #define xmlSecKeyStoreIdUnknown                         ((xmlSecKeyDataStoreId)NULL)
162 
163 /**
164  * xmlSecKeyStoreInitializeMethod:
165  * @store:              the store.
166  *
167  * Keys store specific initialization method.
168  *
169  * Returns: 0 on success or a negative value if an error occurs.
170  */
171 typedef int                     (*xmlSecKeyStoreInitializeMethod)       (xmlSecKeyStorePtr store);
172 
173 /**
174  * xmlSecKeyStoreFinalizeMethod:
175  * @store:              the store.
176  *
177  * Keys store specific finalization (destroy) method.
178  */
179 typedef void                    (*xmlSecKeyStoreFinalizeMethod)         (xmlSecKeyStorePtr store);
180 
181 /**
182  * xmlSecKeyStoreFindKeyMethod:
183  * @store:              the store.
184  * @name:               the desired key name.
185  * @keyInfoCtx:         the pointer to key info context.
186  *
187  * Keys store specific find method. The caller is responsible for destroying
188  * the returned key using #xmlSecKeyDestroy method.
189  *
190  * Returns: the pointer to a key or NULL if key is not found or an error occurs.
191  */
192 typedef xmlSecKeyPtr            (*xmlSecKeyStoreFindKeyMethod)  (xmlSecKeyStorePtr store,
193                                                                  const xmlChar* name,
194                                                                  xmlSecKeyInfoCtxPtr keyInfoCtx);
195 
196 /**
197  * xmlSecKeyStoreKlass:
198  * @klassSize:          the store klass size.
199  * @objSize:            the store obj size.
200  * @name:               the store's name.
201  * @initialize:         the store's initialization method.
202  * @finalize:           the store's finalization (destroy) method.
203  * @findKey:            the store's find method.
204  * @reserved0:          reserved for the future.
205  * @reserved1:          reserved for the future.
206  *
207  * The keys store id (klass).
208  */
209 struct _xmlSecKeyStoreKlass {
210     xmlSecSize                          klassSize;
211     xmlSecSize                          objSize;
212 
213     /* data */
214     const xmlChar*                      name;
215 
216     /* constructors/destructor */
217     xmlSecKeyStoreInitializeMethod      initialize;
218     xmlSecKeyStoreFinalizeMethod        finalize;
219     xmlSecKeyStoreFindKeyMethod         findKey;
220 
221     /* for the future */
222     void*                               reserved0;
223     void*                               reserved1;
224 };
225 
226 /**
227  * xmlSecKeyStoreKlassGetName:
228  * @klass:              the pointer to store klass.
229  *
230  * Macro. Returns store klass name.
231  */
232 #define xmlSecKeyStoreKlassGetName(klass) \
233         (((klass)) ? ((klass)->name) : NULL)
234 
235 
236 /****************************************************************************
237  *
238  * Simple Keys Store
239  *
240  ***************************************************************************/
241 /**
242  * xmlSecSimpleKeysStoreId:
243  *
244  * A simple keys store klass id.
245  */
246 #define xmlSecSimpleKeysStoreId         xmlSecSimpleKeysStoreGetKlass()
247 XMLSEC_EXPORT xmlSecKeyStoreId          xmlSecSimpleKeysStoreGetKlass   (void);
248 XMLSEC_EXPORT int                       xmlSecSimpleKeysStoreAdoptKey   (xmlSecKeyStorePtr store,
249                                                                          xmlSecKeyPtr key);
250 XMLSEC_EXPORT int                       xmlSecSimpleKeysStoreLoad       (xmlSecKeyStorePtr store,
251                                                                          const char *uri,
252                                                                          xmlSecKeysMngrPtr keysMngr);
253 XMLSEC_EXPORT int                       xmlSecSimpleKeysStoreSave       (xmlSecKeyStorePtr store,
254                                                                          const char *filename,
255                                                                          xmlSecKeyDataType type);
256 XMLSEC_EXPORT xmlSecPtrListPtr          xmlSecSimpleKeysStoreGetKeys    (xmlSecKeyStorePtr store);
257 
258 
259 #ifdef __cplusplus
260 }
261 #endif /* __cplusplus */
262 
263 #endif /* __XMLSEC_KEYSMGMR_H__ */
264 
265