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