9cfc0169d5dc11b20e2d2912cacbb0c83d70f55b
[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 <utils/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 * Create an enumerator over supported mechanisms of a token.
89 *
90 * The resulting enumerator enumerates over the mechanism type, and if
91 * a non-NULL pointer is given, over the mechanism info details.
92 *
93 * @param slot slot of the token
94 * @return enumerator over (CK_MECHANISM_TYPE, CK_MECHANISM_INFO)
95 */
96 enumerator_t* (*create_mechanism_enumerator)(pkcs11_library_t *this,
97 CK_SLOT_ID slot);
98
99 /**
100 * Retrieve a single attribute from the given object.
101 *
102 * Memory for the data is allocated.
103 *
104 * @param session session with the PKCS#11 library
105 * @param obj object handle
106 * @param type attribute type to extract
107 * @param data extracted data
108 * @return TRUE if successful
109 */
110 bool (*get_ck_attribute)(pkcs11_library_t *this, CK_SESSION_HANDLE session,
111 CK_OBJECT_HANDLE obj, CK_ATTRIBUTE_TYPE type,
112 chunk_t *data);
113
114 /**
115 * Destroy a pkcs11_library_t.
116 */
117 void (*destroy)(pkcs11_library_t *this);
118 };
119
120 /**
121 * Enum names for CK_RV return values
122 */
123 extern enum_name_t *ck_rv_names;
124
125 /**
126 * Enum names for CK_MECHANISM_TYPE values
127 */
128 extern enum_name_t *ck_mech_names;
129
130 /**
131 * Enum names for CK_ATTRIBUTE_TYPE values
132 */
133 extern enum_name_t *ck_attr_names;
134
135 /**
136 * Trim/null terminate a string returned by the various PKCS#11 functions.
137 *
138 * @param str string to trim
139 * @param len max length of the string
140 */
141 void pkcs11_library_trim(char *str, int len);
142
143 /**
144 * Create a pkcs11_library instance.
145 *
146 * @param name an arbitrary name, for debugging
147 * @param file pkcs11 library file to dlopen()
148 * @param os_lock enforce OS Locking for this library
149 * @return library abstraction
150 */
151 pkcs11_library_t *pkcs11_library_create(char *name, char *file, bool os_lock);
152
153 #endif /** PKCS11_LIBRARY_H_ @}*/