Source code
Revision control
Copy as Markdown
Other Tools
/*
* PKCS#11 Object
* (C) 2016 Daniel Neus, Sirrix AG
* (C) 2016 Philipp Weber, Sirrix AG
*
* Botan is released under the Simplified BSD License (see license.txt)
*/
#ifndef BOTAN_P11_OBJECT_H_
#define BOTAN_P11_OBJECT_H_
#include <botan/p11.h>
#include <botan/p11_types.h>
#include <botan/secmem.h>
#include <vector>
#include <string>
#include <type_traits>
#include <list>
#include <functional>
namespace Botan {
namespace PKCS11 {
class Module;
/// Helper class to build the Attribute / CK_ATTRIBUTE structures
class BOTAN_PUBLIC_API(2,0) AttributeContainer
{
public:
AttributeContainer() = default;
/// @param object_class the class type of this container
AttributeContainer(ObjectClass object_class);
virtual ~AttributeContainer() = default;
AttributeContainer(AttributeContainer&& other) = default;
AttributeContainer& operator=(AttributeContainer&& other) = default;
// Warning when implementing copy/assignment: m_attributes contains pointers to the other members which must be updated after a copy
AttributeContainer(const AttributeContainer& other) = delete;
AttributeContainer& operator=(const AttributeContainer& other) = delete;
/// @return the attributes this container contains
inline const std::vector<Attribute>& attributes() const
{
return m_attributes;
}
/// @return raw attribute data
inline Attribute* data() const
{
return const_cast< Attribute* >(m_attributes.data());
}
/// @return the number of attributes in this container
inline size_t count() const
{
return m_attributes.size();
}
/**
* Add a class attribute (CKA_CLASS / AttributeType::Class).
* @param object_class class attribute to add
*/
void add_class(ObjectClass object_class);
/**
* Add a string attribute (e.g. CKA_LABEL / AttributeType::Label).
* @param attribute attribute type
* @param value string value to add
*/
void add_string(AttributeType attribute, const std::string& value);
/**
* Add a binary attribute (e.g. CKA_ID / AttributeType::Id).
* @param attribute attribute type
* @param value binary attribute value to add
* @param length size of the binary attribute value in bytes
*/
void add_binary(AttributeType attribute, const uint8_t* value, size_t length);
/**
* Add a binary attribute (e.g. CKA_ID / AttributeType::Id).
* @param attribute attribute type
* @param binary binary attribute value to add
*/
template<typename TAlloc>
void add_binary(AttributeType attribute, const std::vector<uint8_t, TAlloc>& binary)
{
add_binary(attribute, binary.data(), binary.size());
}
/**
* Add a bool attribute (e.g. CKA_SENSITIVE / AttributeType::Sensitive).
* @param attribute attribute type
* @param value boolean value to add
*/
void add_bool(AttributeType attribute, bool value);
/**
* Add a numeric attribute (e.g. CKA_MODULUS_BITS / AttributeType::ModulusBits).
* @param attribute attribute type
* @param value numeric value to add
*/
template<typename T>
void add_numeric(AttributeType attribute, T value)
{
static_assert(std::is_integral<T>::value, "Numeric value required.");
m_numerics.push_back(static_cast< uint64_t >(value));
add_attribute(attribute, reinterpret_cast< uint8_t* >(&m_numerics.back()), sizeof(T));
}
protected:
/// Add an attribute with the given value and size to the attribute collection `m_attributes`
void add_attribute(AttributeType attribute, const uint8_t* value, uint32_t size);
private:
std::vector<Attribute> m_attributes;
std::list<uint64_t> m_numerics;
std::list<std::string> m_strings;
std::list<secure_vector<uint8_t>> m_vectors;
};
/// Manages calls to C_FindObjects* functions (C_FindObjectsInit -> C_FindObjects -> C_FindObjectsFinal)
class BOTAN_PUBLIC_API(2,0) ObjectFinder final
{
public:
/**
* Initializes a search for token and session objects that match a template (calls C_FindObjectsInit)
* @param session the session to use for the search
* @param search_template the search_template as a vector of `Attribute`
*/
ObjectFinder(Session& session, const std::vector<Attribute>& search_template);
ObjectFinder(const ObjectFinder& other) = default;
ObjectFinder& operator=(const ObjectFinder& other) = delete;
ObjectFinder(ObjectFinder&& other) = default;
ObjectFinder& operator=(ObjectFinder&& other) = delete;
/// Terminates a search for token and session objects (calls C_FindObjectsFinal)
~ObjectFinder() noexcept;
/**
* Starts or continues a search for token and session objects that match a template, obtaining additional object handles (calls C_FindObjects)
* @param max_count maximum amount of object handles to retrieve. Default = 100
* @return the result of the search as a vector of `ObjectHandle`
*/
std::vector<ObjectHandle> find(std::uint32_t max_count = 100) const;
/// Finishes the search operation manually to allow a new ObjectFinder to exist
void finish();
/// @return the module this `ObjectFinder` belongs to
inline Module& module() const
{
return m_session.get().module();
}
private:
const std::reference_wrapper<Session> m_session;
bool m_search_terminated;
};
/// Common attributes of all objects
class BOTAN_PUBLIC_API(2,0) ObjectProperties : public AttributeContainer
{
public:
/// @param object_class the object class of the object
ObjectProperties(ObjectClass object_class);
/// @return the object class of this object
inline ObjectClass object_class() const
{
return m_object_class;
}
private:
const ObjectClass m_object_class;
};
/// Common attributes of all storage objects
class BOTAN_PUBLIC_API(2,0) StorageObjectProperties : public ObjectProperties
{
public:
/// @param object_class the CK_OBJECT_CLASS this storage object belongs to
StorageObjectProperties(ObjectClass object_class);
/// @param label description of the object (RFC2279 string)
inline void set_label(const std::string& label)
{
add_string(AttributeType::Label, label);
}
/// @param value if true the object is a token object; otherwise the object is a session object
inline void set_token(bool value)
{
add_bool(AttributeType::Token, value);
}
/**
* @param value if true the object is a private object; otherwise the object is a public object
* When private, a user may not access the object until the user has been authenticated to the token
*/
inline void set_private(bool value)
{
add_bool(AttributeType::Private, value);
}
/// @param value if true the object can be modified, otherwise it is read-only
void set_modifiable(bool value)
{
add_bool(AttributeType::Modifiable, value);
}
/// @param value if true the object can be copied using C_CopyObject
void set_copyable(bool value)
{
add_bool(AttributeType::Copyable, value);
}
/// @param value if true the object can be destroyed using C_DestroyObject
void set_destroyable(bool value)
{
add_bool(AttributeType::Destroyable, value);
}
};
/// Common attributes of all data objects
class BOTAN_PUBLIC_API(2,0) DataObjectProperties final : public StorageObjectProperties
{
public:
DataObjectProperties();
/// @param value description of the application that manages the object (RFC2279 string)
inline void set_application(const std::string& value)
{
add_string(AttributeType::Application, value);
}
/// @param object_id DER-encoding of the object identifier indicating the data object type
inline void set_object_id(const std::vector<uint8_t>& object_id)
{
add_binary(AttributeType::ObjectId, object_id);
}
/// @param value value of the object
inline void set_value(const secure_vector<uint8_t>& value)
{
add_binary(AttributeType::Value, value);
}
};
/// Common attributes of all certificate objects
class BOTAN_PUBLIC_API(2,0) CertificateProperties : public StorageObjectProperties
{
public:
/// @param cert_type type of certificate
CertificateProperties(CertificateType cert_type);
/// @param value the certificate can be trusted for the application that it was created (can only be set to true by SO user)
inline void set_trusted(bool value)
{
add_bool(AttributeType::Trusted, value);
}
/// @param category one of `CertificateCategory`
inline void set_category(CertificateCategory category)
{
add_numeric(AttributeType::CertificateCategory, static_cast< CK_CERTIFICATE_CATEGORY >(category));
}
/**
* @param checksum the value of this attribute is derived from the certificate by taking the
* first three bytes of the SHA - 1 hash of the certificate object's `CKA_VALUE` attribute
*/
inline void set_check_value(const std::vector<uint8_t>& checksum)
{
add_binary(AttributeType::CheckValue, checksum);
}
/// @param date start date for the certificate
inline void set_start_date(Date date)
{
add_binary(AttributeType::StartDate, reinterpret_cast<uint8_t*>(&date), sizeof(Date));
}
/// @param date end date for the certificate
inline void set_end_date(Date date)
{
add_binary(AttributeType::EndDate, reinterpret_cast<uint8_t*>(&date), sizeof(Date));
}
/// @param pubkey_info DER-encoding of the SubjectPublicKeyInfo for the public key contained in this certificate
inline void set_public_key_info(const std::vector<uint8_t>& pubkey_info)
{
add_binary(AttributeType::PublicKeyInfo, pubkey_info);
}
/// @return the certificate type of this certificate object
inline CertificateType cert_type() const
{
return m_cert_type;
}
private:
const CertificateType m_cert_type;
};
/// Common attributes of all key objects
class BOTAN_PUBLIC_API(2,0) KeyProperties : public StorageObjectProperties
{
public:
/**
* @param object_class the `CK_OBJECT_CLASS` this key object belongs to
* @param key_type type of key
*/
KeyProperties(ObjectClass object_class, KeyType key_type);
/// @param id key identifier for key
inline void set_id(const std::vector<uint8_t>& id)
{
add_binary(AttributeType::Id, id);
}
/// @param date start date for the key
inline void set_start_date(Date date)
{
add_binary(AttributeType::StartDate, reinterpret_cast<uint8_t*>(&date), sizeof(Date));
}
/// @param date end date for the key
inline void set_end_date(Date date)
{
add_binary(AttributeType::EndDate, reinterpret_cast<uint8_t*>(&date), sizeof(Date));
}
/// @param value true if key supports key derivation (i.e., if other keys can be derived from this one)
inline void set_derive(bool value)
{
add_bool(AttributeType::Derive, value);
}
/**
* Sets a list of mechanisms allowed to be used with this key
* Not implemented
*/
inline void set_allowed_mechanisms(const std::vector<MechanismType>&)
{
throw Not_Implemented("KeyProperties::set_allowed_mechanisms");
}
/// @return the key type of this key object
inline KeyType key_type() const
{
return m_key_type;
}
private:
const KeyType m_key_type;
};
/// Common attributes of all public key objects
class BOTAN_PUBLIC_API(2,0) PublicKeyProperties : public KeyProperties
{
public:
/// @param key_type type of key
PublicKeyProperties(KeyType key_type);
/// @param subject DER-encoding of the key subject name
inline void set_subject(const std::vector<uint8_t>& subject)
{
add_binary(AttributeType::Subject, subject);
}
/// @param value true if the key supports encryption
inline void set_encrypt(bool value)
{
add_bool(AttributeType::Encrypt, value);
}
/// @param value true if the key supports verification where the signature is an appendix to the data
inline void set_verify(bool value)
{
add_bool(AttributeType::Verify, value);
}
/// @param value true if the key supports verification where the data is recovered from the signature
inline void set_verify_recover(bool value)
{
add_bool(AttributeType::VerifyRecover, value);
}
/// @param value true if the key supports wrapping (i.e., can be used to wrap other keys)
inline void set_wrap(bool value)
{
add_bool(AttributeType::Wrap, value);
}
/**
* @param value true if the key can be trusted for the application that it was created.
* The wrapping key can be used to wrap keys with `CKA_WRAP_WITH_TRUSTED` set to `CK_TRUE`
*/
inline void set_trusted(bool value)
{
add_bool(AttributeType::Trusted, value);
}
/**
* For wrapping keys
* The attribute template to match against any keys wrapped using this wrapping key.
* Keys that do not match cannot be wrapped
* Not implemented
*/
inline void set_wrap_template(const AttributeContainer&)
{
throw Not_Implemented("PublicKeyProperties::set_wrap_template");
}
/// @param pubkey_info DER-encoding of the SubjectPublicKeyInfo for this public key
inline void set_public_key_info(const std::vector<uint8_t>& pubkey_info)
{
add_binary(AttributeType::PublicKeyInfo, pubkey_info);
}
};
/// Common attributes of all private keys
class BOTAN_PUBLIC_API(2,0) PrivateKeyProperties : public KeyProperties
{
public:
/// @param key_type type of key
PrivateKeyProperties(KeyType key_type);
/// @param subject DER-encoding of the key subject name
inline void set_subject(const std::vector<uint8_t>& subject)
{
add_binary(AttributeType::Subject, subject);
}
/// @param value true if the key is sensitive
inline void set_sensitive(bool value)
{
add_bool(AttributeType::Sensitive, value);
}
/// @param value true if the key supports decryption
inline void set_decrypt(bool value)
{
add_bool(AttributeType::Decrypt, value);
}
/// @param value true if the key supports signatures where the signature is an appendix to the data
inline void set_sign(bool value)
{
add_bool(AttributeType::Sign, value);
}
/// @param value true if the key supports signatures where the data can be recovered from the signature
inline void set_sign_recover(bool value)
{
add_bool(AttributeType::SignRecover, value);
}
/// @param value true if the key supports unwrapping (i.e., can be used to unwrap other keys)
inline void set_unwrap(bool value)
{
add_bool(AttributeType::Unwrap, value);
}
/// @param value true if the key is extractable and can be wrapped
inline void set_extractable(bool value)
{
add_bool(AttributeType::Extractable, value);
}
/// @param value true if the key can only be wrapped with a wrapping key that has `CKA_TRUSTED` set to `CK_TRUE`
inline void set_wrap_with_trusted(bool value)
{
add_bool(AttributeType::WrapWithTrusted, value);
}
/// @param value If true, the user has to supply the PIN for each use (sign or decrypt) with the key
inline void set_always_authenticate(bool value)
{
add_bool(AttributeType::AlwaysAuthenticate, value);
}
/**
* For wrapping keys
* The attribute template to apply to any keys unwrapped using this wrapping key.
* Any user supplied template is applied after this template as if the object has already been created
* Not implemented
*/
inline void set_unwrap_template(const AttributeContainer&)
{
throw Not_Implemented("PrivateKeyProperties::set_unwrap_template");
}
/// @param pubkey_info DER-encoding of the SubjectPublicKeyInfo for this public key
inline void set_public_key_info(const std::vector<uint8_t>& pubkey_info)
{
add_binary(AttributeType::PublicKeyInfo, pubkey_info);
}
};
/// Common attributes of all secret (symmetric) keys
class BOTAN_PUBLIC_API(2,0) SecretKeyProperties final : public KeyProperties
{
public:
/// @param key_type type of key
SecretKeyProperties(KeyType key_type);
/// @param value true if the key is sensitive
inline void set_sensitive(bool value)
{
add_bool(AttributeType::Sensitive, value);
}
/// @param value true if the key supports encryption
inline void set_encrypt(bool value)
{
add_bool(AttributeType::Encrypt, value);
}
/// @param value true if the key supports decryption
inline void set_decrypt(bool value)
{
add_bool(AttributeType::Decrypt, value);
}
/// @param value true if the key supports signatures where the signature is an appendix to the data
inline void set_sign(bool value)
{
add_bool(AttributeType::Sign, value);
}
/// @param value true if the key supports verification where the signature is an appendix to the data
inline void set_verify(bool value)
{
add_bool(AttributeType::Verify, value);
}
/// @param value true if the key supports unwrapping (i.e., can be used to unwrap other keys)
inline void set_unwrap(bool value)
{
add_bool(AttributeType::Unwrap, value);
}
/// @param value true if the key is extractable and can be wrapped
inline void set_extractable(bool value)
{
add_bool(AttributeType::Extractable, value);
}
/// @param value true if the key can only be wrapped with a wrapping key that has `CKA_TRUSTED` set to `CK_TRUE`
inline void set_wrap_with_trusted(bool value)
{
add_bool(AttributeType::WrapWithTrusted, value);
}
/// @param value if true, the user has to supply the PIN for each use (sign or decrypt) with the key
inline void set_always_authenticate(bool value)
{
add_bool(AttributeType::AlwaysAuthenticate, value);
}
/// @param value true if the key supports wrapping (i.e., can be used to wrap other keys)
inline void set_wrap(bool value)
{
add_bool(AttributeType::Wrap, value);
}
/**
* @param value the key can be trusted for the application that it was created.
* The wrapping key can be used to wrap keys with `CKA_WRAP_WITH_TRUSTED` set to `CK_TRUE`
*/
inline void set_trusted(bool value)
{
add_bool(AttributeType::Trusted, value);
}
/// @param checksum the key check value of this key
inline void set_check_value(const std::vector<uint8_t>& checksum)
{
add_binary(AttributeType::CheckValue, checksum);
}
/**
* For wrapping keys
* The attribute template to match against any keys wrapped using this wrapping key.
* Keys that do not match cannot be wrapped
* Not implemented
*/
inline void set_wrap_template(const AttributeContainer&)
{
throw Not_Implemented("SecretKeyProperties::set_wrap_template");
}
/**
* For wrapping keys
* The attribute template to apply to any keys unwrapped using this wrapping key
* Any user supplied template is applied after this template as if the object has already been created
* Not Implemented
*/
inline void set_unwrap_template(const AttributeContainer&)
{
throw Not_Implemented("SecretKeyProperties::set_unwrap_template");
}
};
/// Common attributes of domain parameter
class BOTAN_PUBLIC_API(2,0) DomainParameterProperties final : public StorageObjectProperties
{
public:
/// @param key_type type of key the domain parameters can be used to generate
DomainParameterProperties(KeyType key_type);
/// @return the key type
inline KeyType key_type() const
{
return m_key_type;
}
private:
const KeyType m_key_type;
};
/**
* Represents a PKCS#11 object.
*/
class BOTAN_PUBLIC_API(2,0) Object
{
public:
/**
* Creates an `Object` from an existing PKCS#11 object
* @param session the session the object belongs to
* @param handle handle of the object
*/
Object(Session& session, ObjectHandle handle);
/**
* Creates the object
* @param session the session in which the object should be created
* @param obj_props properties of this object
*/
Object(Session& session, const ObjectProperties& obj_props);
Object(const Object&) = default;
Object& operator=(const Object&) = delete;
virtual ~Object() = default;
/// Searches for all objects of the given type that match `search_template`
template<typename T>
static std::vector<T> search(Session& session, const std::vector<Attribute>& search_template);
/// Searches for all objects of the given type using the label (`CKA_LABEL`)
template<typename T>
static std::vector<T> search(Session& session, const std::string& label);
/// Searches for all objects of the given type using the id (`CKA_ID`)
template<typename T>
static std::vector<T> search(Session& session, const std::vector<uint8_t>& id);
/// Searches for all objects of the given type using the label (`CKA_LABEL`) and id (`CKA_ID`)
template<typename T>
static std::vector<T> search(Session& session, const std::string& label, const std::vector<uint8_t>& id);
/// Searches for all objects of the given type
template<typename T>
static std::vector<T> search(Session& session);
/// @returns the value of the given attribute (using `C_GetAttributeValue`)
secure_vector<uint8_t> get_attribute_value(AttributeType attribute) const;
/// Sets the given value for the attribute (using `C_SetAttributeValue`)
void set_attribute_value(AttributeType attribute, const secure_vector<uint8_t>& value) const;
/// Destroys the object
void destroy() const;
/**
* Copies the object
* @param modified_attributes the attributes of the copied object
*/
ObjectHandle copy(const AttributeContainer& modified_attributes) const;
/// @return the handle of this object.
inline ObjectHandle handle() const
{
return m_handle;
}
/// @return the session this objects belongs to
inline Session& session() const
{
return m_session;
}
/// @return the module this object belongs to
inline Module& module() const
{
return m_session.get().module();
}
protected:
Object(Session& session)
: m_session(session)
{}
void reset_handle(ObjectHandle handle)
{
if(m_handle != CK_INVALID_HANDLE)
throw Invalid_Argument("Cannot reset handle on already valid PKCS11 object");
m_handle = handle;
}
private:
const std::reference_wrapper<Session> m_session;
ObjectHandle m_handle = CK_INVALID_HANDLE;
};
template<typename T>
std::vector<T> Object::search(Session& session, const std::vector<Attribute>& search_template)
{
ObjectFinder finder(session, search_template);
std::vector<ObjectHandle> handles = finder.find();
std::vector<T> result;
result.reserve(handles.size());
for(const auto& handle : handles)
{
result.emplace_back(T(session, handle));
}
return result;
}
template<typename T>
std::vector<T> Object::search(Session& session, const std::string& label)
{
AttributeContainer search_template(T::Class);
search_template.add_string(AttributeType::Label, label);
return search<T>(session, search_template.attributes());
}
template<typename T>
std::vector<T> Object::search(Session& session, const std::vector<uint8_t>& id)
{
AttributeContainer search_template(T::Class);
search_template.add_binary(AttributeType::Id, id);
return search<T>(session, search_template.attributes());
}
template<typename T>
std::vector<T> Object::search(Session& session, const std::string& label, const std::vector<uint8_t>& id)
{
AttributeContainer search_template(T::Class);
search_template.add_string(AttributeType::Label, label);
search_template.add_binary(AttributeType::Id, id);
return search<T>(session, search_template.attributes());
}
template<typename T>
std::vector<T> Object::search(Session& session)
{
return search<T>(session, AttributeContainer(T::Class).attributes());
}
}
}
#endif