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