Botan 3.9.0
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#include <utility>
17
18namespace Botan {
19
21
22namespace PKCS11 {
23
24/**
25* Loads the PKCS#11 shared library
26* Calls C_Initialize on load and C_Finalize on destruction
27*/
28class BOTAN_PUBLIC_API(2, 0) Module final {
29 public:
30 /**
31 * Loads the shared library and calls C_Initialize
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 inline LowLevel* operator->() const { return m_low_level.get(); }
59
60 /// @return general information about Cryptoki
61 inline Info get_info() const {
62 Info info;
63 m_low_level->C_GetInfo(&info);
64 return info;
65 }
66
67 private:
68 const std::string m_file_path;
69 FunctionListPtr m_func_list = nullptr;
70 std::unique_ptr<Dynamically_Loaded_Library> m_library;
71 std::unique_ptr<LowLevel> m_low_level = nullptr;
72};
73
74/// Represents a PKCS#11 Slot, i.e., a card reader
75class BOTAN_PUBLIC_API(2, 0) Slot final {
76 public:
77 /**
78 * @param module the PKCS#11 module to use
79 * @param slot_id the slot id to use
80 */
82
83 /// @return a reference to the module that is used
84 inline Module& module() const { return m_module; }
85
86 /// @return the slot id
87 inline SlotId slot_id() const { return m_slot_id; }
88
89 /**
90 * Get available slots
91 * @param module the module to use
92 * @param token_present true if only slots with attached tokens should be returned, false for all slots
93 * @return a list of available slots (calls C_GetSlotList)
94 */
95 static std::vector<SlotId> get_available_slots(Module& module, bool token_present);
96
97 /// @return information about the slot (`C_GetSlotInfo`)
98 SlotInfo get_slot_info() const;
99
100 /// Obtains a list of mechanism types supported by the slot (`C_GetMechanismList`)
101 std::vector<MechanismType> get_mechanism_list() const;
102
103 /// Obtains information about a particular mechanism possibly supported by a slot (`C_GetMechanismInfo`)
104 MechanismInfo get_mechanism_info(MechanismType mechanism_type) const;
105
106 /// Obtains information about a particular token in the system (`C_GetTokenInfo`)
107 TokenInfo get_token_info() const;
108
109 /**
110 * Calls `C_InitToken` to initialize the token
111 * @param label the label for the token (must not exceed 32 bytes according to PKCS#11)
112 * @param so_pin the PIN of the security officer
113 */
114 void initialize(std::string_view label, const secure_string& so_pin) const;
115
116 private:
117 const std::reference_wrapper<Module> m_module;
118 const SlotId m_slot_id;
119};
120
121/// Represents a PKCS#11 session
122class BOTAN_PUBLIC_API(2, 0) Session final {
123 public:
124 /**
125 * @param slot the slot to use
126 * @param read_only true if the session should be read only, false to create a read-write session
127 */
128 Session(Slot& slot, bool read_only);
129
130 /**
131 * @param slot the slot to use
132 * @param flags the flags to use for the session. Remark: Flag::SerialSession is mandatory
133 * @param callback_data application-defined pointer to be passed to the notification callback
134 * @param notify_callback address of the notification callback function
135 */
136 Session(Slot& slot, Flags flags, VoidPtr callback_data, Notify notify_callback);
137
138 /// Takes ownership of a session
140
141 Session(Session&& other) = default;
142 Session& operator=(Session&& other) = delete;
143
144 // Dtor calls C_CloseSession() and eventually C_Logout. A copy could close the session while the origin still exists
145 Session(const Session& other) = delete;
146 Session& operator=(const Session& other) = delete;
147
148 /// Logout user and close the session on destruction
149 ~Session() noexcept;
150
151 /// @return a reference to the slot
152 inline const Slot& slot() const { return m_slot; }
153
154 /// @return the session handle of this session
155 inline SessionHandle handle() const { return m_handle; }
156
157 /// @return a reference to the used module
158 inline Module& module() const { return m_slot.module(); }
159
160 /// @return the released session handle
161 SessionHandle release();
162
163 /**
164 * Login to this session
165 * @param userType the user type to use for the login
166 * @param pin the PIN of the user
167 */
168 void login(UserType userType, const secure_string& pin);
169
170 /// Logout from this session
171 void logoff();
172
173 /// @return information about this session
174 SessionInfo get_info() const;
175
176 /// Calls `C_SetPIN` to change the PIN using the old PIN (requires a logged in session)
177 void set_pin(const secure_string& old_pin, const secure_string& new_pin);
178
179 /// Calls `C_InitPIN` to change or initialize the PIN using the SO_PIN (requires a logged in session)
180 void init_pin(const secure_string& new_pin);
181
182 private:
183 const Slot& m_slot;
184 SessionHandle m_handle;
185 bool m_logged_in;
186};
187
188} // namespace PKCS11
189} // namespace Botan
190
191#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:890
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})
Info get_info() const
Definition p11_types.h:61
Module(Module &&other) noexcept
LowLevel * operator->() const
Definition p11_types.h:58
Module & operator=(Module &&other)=delete
Module & operator=(const Module &other)=delete
Module(const Module &other)=delete
Session(Session &&other)=default
Session & operator=(Session &&other)=delete
Session(const Session &other)=delete
Module & module() const
Definition p11_types.h:158
const Slot & slot() const
Definition p11_types.h:152
SessionHandle handle() const
Definition p11_types.h:155
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:75
Module & module() const
Definition p11_types.h:84
Slot(Module &module, SlotId slot_id)
Definition p11_slot.cpp:13
SlotId slot_id() const
Definition p11_types.h:87
CK_SLOT_ID SlotId
Definition p11.h:824
secure_vector< uint8_t > secure_string
Definition p11.h:64
CK_C_INITIALIZE_ARGS C_InitializeArgs
Definition p11.h:816
CK_NOTIFY Notify
Definition p11.h:831
CK_FUNCTION_LIST_PTR FunctionListPtr
Definition p11.h:814
CK_INFO Info
Definition p11.h:822
CK_SLOT_INFO SlotInfo
Definition p11.h:826
CK_VOID_PTR VoidPtr
Definition p11.h:815
CK_FLAGS Flags
Definition p11.h:821
CK_SESSION_INFO SessionInfo
Definition p11.h:833
CK_TOKEN_INFO TokenInfo
Definition p11.h:827
void set_pin(Slot &slot, const secure_string &so_pin, const secure_string &pin)
Definition p11.cpp:58
CK_MECHANISM_INFO MechanismInfo
Definition p11.h:829
Flags flags(Flag flags)
Definition p11.h:848
CK_SESSION_HANDLE SessionHandle
Definition p11.h:832
CK_ULONG CK_FLAGS
Definition pkcs11t.h:54