33e5f97dcdda5dab2031544fd90b430d22e287a9
[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 };
39
40 /**
41 * A loaded and initialized PKCS#11 library.
42 */
43 struct pkcs11_library_t {
44
45 /**
46 * PKCS#11 function list, as returned by C_GetFunctionList
47 */
48 CK_FUNCTION_LIST_PTR f;
49
50 /**
51 * Get the name this instance was created with.
52 *
53 * @return name, as passed to constructor
54 */
55 char* (*get_name)(pkcs11_library_t *this);
56
57 /**
58 * Get the feature set supported by this library.
59 *
60 * @return ORed set of features supported
61 */
62 pkcs11_feature_t (*get_features)(pkcs11_library_t *this);
63
64 /**
65 * Create an enumerator over CK_OBJECT_HANDLE using a search template.
66 *
67 * An optional attribute array is automatically filled in with the
68 * objects associated attributes. If the value of an output attribute
69 * is NULL, the value gets allocated/freed during enumeration.
70 *
71 * @param session session to use
72 * @param tmpl search template
73 * @param tcount number of attributes in the search template
74 * @param attr attributes to read from object
75 * @param acount number of attributes to read
76 */
77 enumerator_t* (*create_object_enumerator)(pkcs11_library_t *this,
78 CK_SESSION_HANDLE session, CK_ATTRIBUTE_PTR tmpl, CK_ULONG tcount,
79 CK_ATTRIBUTE_PTR attr, CK_ULONG acount);
80
81 /**
82 * Create an enumerator over supported mechanisms of a token.
83 *
84 * The resulting enumerator enumerates over the mechanism type, and if
85 * a non-NULL pointer is given, over the mechanism info details.
86 *
87 * @param slot slot of the token
88 * @return enumerator over (CK_MECHANISM_TYPE, CK_MECHANISM_INFO)
89 */
90 enumerator_t* (*create_mechanism_enumerator)(pkcs11_library_t *this,
91 CK_SLOT_ID slot);
92
93 /**
94 * Destroy a pkcs11_library_t.
95 */
96 void (*destroy)(pkcs11_library_t *this);
97 };
98
99 /**
100 * Enum names for CK_RV return values
101 */
102 extern enum_name_t *ck_rv_names;
103
104 /**
105 * Enum names for CK_MECHANISM_TYPE values
106 */
107 extern enum_name_t *ck_mech_names;
108
109 /**
110 * Trim/null terminate a string returned by the varius PKCS#11 functions.
111 *
112 * @param str string to trim
113 * @param len max length of the string
114 */
115 void pkcs11_library_trim(char *str, int len);
116
117 /**
118 * Create a pkcs11_library instance.
119 *
120 * @param name an arbitrary name, for debugging
121 * @param file pkcs11 library file to dlopen()
122 * @param os_lock enforce OS Locking for this library
123 * @return library abstraction
124 */
125 pkcs11_library_t *pkcs11_library_create(char *name, char *file, bool os_lock);
126
127 #endif /** PKCS11_LIBRARY_H_ @}*/