Botan 3.14.1
Crypto and TLS for C&
p11_types.h
Go to the documentation of this file.
1/*
2* PKCS#11 Module/Slot/Session
3* (C) 2016 Daniel Neus, Sirrix AG
4* (C) 2016 Philipp Weber, Sirrix AG
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_P11_TYPES_H_
10#define BOTAN_P11_TYPES_H_
11
12#include <botan/p11.h>
13#include <functional>
14#include <memory>
15#include <string>
16
17namespace Botan {
18
20
21namespace PKCS11 {
22
23/**
24* Loads the PKCS#11 shared library
25* Calls C_Initialize on load and C_Finalize on destruction
26*/
27class BOTAN_PUBLIC_API(2, 0) Module final {
28 public:
29 /**
30 * Loads the shared library and calls C_Initialize. The latest supported
31 * "PKCS 11" interface is used.
32 * @param file_path the path to the PKCS#11 shared library
33 * @param init_args flags to use for `C_Initialize`
34 */
36 std::string_view file_path,
37 C_InitializeArgs init_args = {
38 nullptr, nullptr, nullptr, nullptr, static_cast<CK_FLAGS>(Flag::OsLockingOk), nullptr});
39
40 Module(Module&& other) noexcept;
41 Module& operator=(Module&& other) = delete;
42
43 // Dtor calls C_Finalize(). A copy could be deleted while the origin still exists
44 // Furthermore std::unique_ptr member -> not copyable
45 Module(const Module& other) = delete;
46 Module& operator=(const Module& other) = delete;
47
48 /// Calls C_Finalize()
49 ~Module() noexcept;
50
51 /**
52 * Reloads the module and reinitializes it.
53 * @param init_args flags to use for `C_Initialize`
54 */
55 void reload(C_InitializeArgs init_args = {
56 nullptr, nullptr, nullptr, nullptr, static_cast<CK_FLAGS>(Flag::OsLockingOk), nullptr});
57
58 /**
59 * @throws Invalid_State if the module is not initialized, which is the
60 * case after a failed reload()
61 */
62 inline LowLevel* operator->() const {
63 if(!m_low_level) {
64 throw Invalid_State("PKCS11 module is not initialized");
65 }
66 return m_low_level.get();
67 }
68
69 /// @return general information about Cryptoki
70 inline Info get_info() const {
71 Info info;
72 (*this)->C_GetInfo(&info);
73 return info;
74 }
75
76 std::string_view library_path() const { return m_file_path; }
77
79 if(!m_library) {
80 throw Invalid_State("PKCS11 module is not initialized");
81 }
82 return *m_library;
83 }
84
85 private:
86 const std::string m_file_path;
87 std::unique_ptr<Dynamically_Loaded_Library> m_library;
88 std::unique_ptr<LowLevel> m_low_level = nullptr;
89};
90
91/// Represents a PKCS#11 Slot, i.e., a card reader
92class BOTAN_PUBLIC_API(2, 0) Slot final {
93 public:
94 /**
95 * @param module the PKCS#11 module to use
96 * @param slot_id the slot id to use
97 */
99
100 /// @return a reference to the module that is used
101 inline Module& module() const { return m_module; }
102
103 /// @return the slot id
104 inline SlotId slot_id() const { return m_slot_id; }
105
106 /**
107 * Get available slots
108 * @param module the module to use
109 * @param token_present true if only slots with attached tokens should be returned, false for all slots
110 * @return a list of available slots (calls C_GetSlotList)
111 */
112 static std::vector<SlotId> get_available_slots(Module& module, bool token_present);
113
114 /// @return information about the slot (`C_GetSlotInfo`)
115 SlotInfo get_slot_info() const;
116
117 /// Obtains a list of mechanism types supported by the slot (`C_GetMechanismList`)
118 std::vector<MechanismType> get_mechanism_list() const;
119
120 /// Obtains information about a particular mechanism possibly supported by a slot (`C_GetMechanismInfo`)
121 MechanismInfo get_mechanism_info(MechanismType mechanism_type) const;
122
123 /// Obtains information about a particular token in the system (`C_GetTokenInfo`)
124 TokenInfo get_token_info() const;
125
126 /**
127 * Calls `C_InitToken` to initialize the token
128 * @param label the label for the token (must not exceed 32 bytes according to PKCS#11)
129 * @param so_pin the PIN of the security officer
130 */
131 void initialize(std::string_view label, const secure_string& so_pin) const;
132
133 private:
134 const std::reference_wrapper<Module> m_module;
135 const SlotId m_slot_id;
136};
137
138/// Represents a PKCS#11 session
139class BOTAN_PUBLIC_API(2, 0) Session final {
140 public:
141 /**
142 * @param slot the slot to use
143 * @param read_only true if the session should be read only, false to create a read-write session
144 */
145 Session(Slot& slot, bool read_only);
146
147 /**
148 * @param slot the slot to use
149 * @param flags the flags to use for the session. Remark: Flag::SerialSession is mandatory
150 * @param callback_data application-defined pointer to be passed to the notification callback
151 * @param notify_callback address of the notification callback function
152 */
153 Session(Slot& slot, Flags flags, VoidPtr callback_data, Notify notify_callback);
154
155 /// Takes ownership of a session
157
158 Session(Session&& other) noexcept;
159 Session& operator=(Session&& other) = delete;
160
161 // Dtor calls C_CloseSession() and eventually C_Logout. A copy could close the session while the origin still exists
162 Session(const Session& other) = delete;
163 Session& operator=(const Session& other) = delete;
164
165 /// Logout user and close the session on destruction
166 ~Session() noexcept;
167
168 /// @return a reference to the slot
169 inline const Slot& slot() const { return m_slot; }
170
171 /// @return the session handle of this session
172 inline SessionHandle handle() const { return m_handle; }
173
174 /// @return a reference to the used module
175 inline Module& module() const { return m_slot.module(); }
176
177 /// @return the released session handle
178 SessionHandle release();
179
180 /**
181 * Login to this session
182 * @param userType the user type to use for the login
183 * @param pin the PIN of the user
184 */
185 void login(UserType userType, const secure_string& pin);
186
187 /// Logout from this session
188 void logoff();
189
190 /// @return information about this session
191 SessionInfo get_info() const;
192
193 /// Calls `C_SetPIN` to change the PIN using the old PIN (requires a logged in session)
194 void set_pin(const secure_string& old_pin, const secure_string& new_pin);
195
196 /// Calls `C_InitPIN` to change or initialize the PIN using the SO_PIN (requires a logged in session)
197 void init_pin(const secure_string& new_pin);
198
199 private:
200 const Slot& m_slot;
201 SessionHandle m_handle;
202 bool m_logged_in;
203};
204
205} // namespace PKCS11
206} // namespace Botan
207
208#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_FUTURE_EXPLICIT
Definition api.h:52
Provides access to all PKCS #11 functions.
Definition p11.h:1330
void reload(C_InitializeArgs init_args={ nullptr, nullptr, nullptr, nullptr, static_cast< CK_FLAGS >(Flag::OsLockingOk), nullptr})
BOTAN_FUTURE_EXPLICIT Module(std::string_view file_path, C_InitializeArgs init_args={ nullptr, nullptr, nullptr, nullptr, static_cast< CK_FLAGS >(Flag::OsLockingOk), nullptr})
const Dynamically_Loaded_Library & library()
Definition p11_types.h:78
Info get_info() const
Definition p11_types.h:70
Module(Module &&other) noexcept
LowLevel * operator->() const
Definition p11_types.h:62
Module & operator=(Module &&other)=delete
std::string_view library_path() const
Definition p11_types.h:76
Module & operator=(const Module &other)=delete
Module(const Module &other)=delete
Session & operator=(Session &&other)=delete
Session(const Session &other)=delete
Module & module() const
Definition p11_types.h:175
const Slot & slot() const
Definition p11_types.h:169
SessionHandle handle() const
Definition p11_types.h:172
Session & operator=(const Session &other)=delete
Session(Slot &slot, bool read_only)
Represents a PKCS#11 Slot, i.e., a card reader.
Definition p11_types.h:92
Module & module() const
Definition p11_types.h:101
Slot(Module &module, SlotId slot_id)
Definition p11_slot.cpp:13
SlotId slot_id() const
Definition p11_types.h:104
CK_SLOT_ID SlotId
Definition p11.h:1203
secure_vector< uint8_t > secure_string
Definition p11.h:46
CK_C_INITIALIZE_ARGS C_InitializeArgs
Definition p11.h:1194
CK_NOTIFY Notify
Definition p11.h:1210
CK_INFO Info
Definition p11.h:1200
CK_SLOT_INFO SlotInfo
Definition p11.h:1205
CK_VOID_PTR VoidPtr
Definition p11.h:1193
CK_FLAGS Flags
Definition p11.h:1199
CK_SESSION_INFO SessionInfo
Definition p11.h:1212
CK_TOKEN_INFO TokenInfo
Definition p11.h:1206
void set_pin(Slot &slot, const secure_string &so_pin, const secure_string &pin)
Definition p11.cpp:75
CK_MECHANISM_INFO MechanismInfo
Definition p11.h:1208
Flags flags(Flag flags)
Definition p11.h:1235
CK_SESSION_HANDLE SessionHandle
Definition p11.h:1211
CK_ULONG CK_FLAGS
Definition pkcs11.h:49