Botan  2.18.2
Crypto and TLS for C++11
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 */
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
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
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
const Slot & slot() const
Definition: p11_types.h:161
CK_NOTIFY Notify
Definition: p11.h:844
Module & module() const
Definition: p11_types.h:86
Module & module() const
Definition: p11_types.h:173
void set_pin(Slot &slot, const secure_string &so_pin, const secure_string &pin)
Definition: p11.cpp:67
int(* final)(unsigned char *, CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Flags flags(Flag flags)
Definition: p11.h:860
CK_VOID_PTR VoidPtr
Definition: p11.h:828
SessionHandle handle() const
Definition: p11_types.h:167
LowLevel * operator->() const
Definition: p11_types.h:55
CK_FUNCTION_LIST_PTR FunctionListPtr
Definition: p11.h:827
CK_SESSION_HANDLE SessionHandle
Definition: p11.h:845
Info get_info() const
Definition: p11_types.h:61
Provides access to all PKCS#11 functions.
Definition: p11.h:903
Definition: alg_id.cpp:13
CK_FLAGS Flags
Definition: p11.h:834
CK_ULONG CK_FLAGS
Definition: pkcs11t.h:54
CK_SLOT_ID SlotId
Definition: p11.h:837
MechanismType
Definition: p11.h:337
secure_vector< uint8_t > secure_string
Definition: p11.h:63
Represents a PKCS#11 session.
Definition: p11_types.h:130
Represents a PKCS#11 Slot, i.e., a card reader.
Definition: p11_types.h:76
SlotId slot_id() const
Definition: p11_types.h:92