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