Moved data structures to new collections subfolder
[strongswan.git] / src / libstrongswan / plugins / pkcs11 / pkcs11_library.h
1 /*
2 * Copyright (C) 2011 Tobias Brunner
3 * Hochschule fuer Technik Rapperswil
4 *
5 * Copyright (C) 2010 Martin Willi
6 * Copyright (C) 2010 revosec AG
7 *
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU General Public License as published by the
10 * Free Software Foundation; either version 2 of the License, or (at your
11 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
12 *
13 * This program is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 * for more details.
17 */
18
19 /**
20 * @defgroup pkcs11_library pkcs11_library
21 * @{ @ingroup pkcs11
22 */
23
24 #ifndef PKCS11_LIBRARY_H_
25 #define PKCS11_LIBRARY_H_
26
27 typedef enum pkcs11_feature_t pkcs11_feature_t;
28 typedef struct pkcs11_library_t pkcs11_library_t;
29
30 #include "pkcs11.h"
31
32 #include <enum.h>
33 #include <chunk.h>
34 #include <collections/enumerator.h>
35
36 /**
37 * Optional PKCS#11 features some libraries support, some not
38 */
39 enum pkcs11_feature_t {
40 /** CKA_TRUSTED attribute supported for certificate objects */
41 PKCS11_TRUSTED_CERTS = (1<<0),
42 /** CKA_ALWAYS_AUTHENTICATE attribute supported for private keys */
43 PKCS11_ALWAYS_AUTH_KEYS = (1<<1),
44 };
45
46 /**
47 * A loaded and initialized PKCS#11 library.
48 */
49 struct pkcs11_library_t {
50
51 /**
52 * PKCS#11 function list, as returned by C_GetFunctionList
53 */
54 CK_FUNCTION_LIST_PTR f;
55
56 /**
57 * Get the name this instance was created with.
58 *
59 * @return name, as passed to constructor
60 */
61 char* (*get_name)(pkcs11_library_t *this);
62
63 /**
64 * Get the feature set supported by this library.
65 *
66 * @return ORed set of features supported
67 */
68 pkcs11_feature_t (*get_features)(pkcs11_library_t *this);
69
70 /**
71 * Create an enumerator over CK_OBJECT_HANDLE using a search template.
72 *
73 * An optional attribute array is automatically filled in with the
74 * objects associated attributes. If the value of an output attribute
75 * is NULL, the value gets allocated/freed during enumeration.
76 *
77 * @param session session to use
78 * @param tmpl search template
79 * @param tcount number of attributes in the search template
80 * @param attr attributes to read from object
81 * @param acount number of attributes to read
82 */
83 enumerator_t* (*create_object_enumerator)(pkcs11_library_t *this,
84 CK_SESSION_HANDLE session, CK_ATTRIBUTE_PTR tmpl, CK_ULONG tcount,
85 CK_ATTRIBUTE_PTR attr, CK_ULONG acount);
86
87 /**
88 * This is very similar to the object enumerator but is only used to
89 * easily retrieve multiple attributes from a single object for which
90 * a handle is already known.
91 *
92 * The given attribute array is automatically filled in with the
93 * associated attributes. If the value of an output attribute is NULL,
94 * the required memory gets allocated/freed during enumeration.
95 *
96 * @param session session to use
97 * @param object object handle
98 * @param attr attributes to read from object
99 * @param count number of attributes to read
100 */
101 enumerator_t* (*create_object_attr_enumerator)(pkcs11_library_t *this,
102 CK_SESSION_HANDLE session, CK_OBJECT_HANDLE object,
103 CK_ATTRIBUTE_PTR attr, CK_ULONG count);
104
105 /**
106 * Create an enumerator over supported mechanisms of a token.
107 *
108 * The resulting enumerator enumerates over the mechanism type, and if
109 * a non-NULL pointer is given, over the mechanism info details.
110 *
111 * @param slot slot of the token
112 * @return enumerator over (CK_MECHANISM_TYPE, CK_MECHANISM_INFO)
113 */
114 enumerator_t* (*create_mechanism_enumerator)(pkcs11_library_t *this,
115 CK_SLOT_ID slot);
116
117 /**
118 * Retrieve a single attribute from the given object.
119 *
120 * Memory for the data is allocated.
121 *
122 * @param session session with the PKCS#11 library
123 * @param obj object handle
124 * @param type attribute type to extract
125 * @param data extracted data
126 * @return TRUE if successful
127 */
128 bool (*get_ck_attribute)(pkcs11_library_t *this, CK_SESSION_HANDLE session,
129 CK_OBJECT_HANDLE obj, CK_ATTRIBUTE_TYPE type,
130 chunk_t *data);
131
132 /**
133 * Destroy a pkcs11_library_t.
134 */
135 void (*destroy)(pkcs11_library_t *this);
136 };
137
138 /**
139 * Enum names for CK_RV return values
140 */
141 extern enum_name_t *ck_rv_names;
142
143 /**
144 * Enum names for CK_MECHANISM_TYPE values
145 */
146 extern enum_name_t *ck_mech_names;
147
148 /**
149 * Enum names for CK_ATTRIBUTE_TYPE values
150 */
151 extern enum_name_t *ck_attr_names;
152
153 /**
154 * Trim/null terminate a string returned by the various PKCS#11 functions.
155 *
156 * @param str string to trim
157 * @param len max length of the string
158 */
159 void pkcs11_library_trim(char *str, int len);
160
161 /**
162 * Create a pkcs11_library instance.
163 *
164 * @param name an arbitrary name (for debugging), cloned
165 * @param file pkcs11 library file to dlopen()
166 * @param os_lock enforce OS Locking for this library
167 * @return library abstraction
168 */
169 pkcs11_library_t *pkcs11_library_create(char *name, char *file, bool os_lock);
170
171 #endif /** PKCS11_LIBRARY_H_ @}*/