pub struct Session { /* private fields */ }
Expand description
Type that identifies a session
It will automatically get closed (and logout) on drop. Session does not implement Sync to prevent the same Session instance to be used from multiple threads. A Session needs to be created in its own thread or to be passed by ownership to another thread.
Implementations§
source§impl Session
impl Session
sourcepub fn generate_key(
&self,
mechanism: &Mechanism<'_>,
template: &[Attribute]
) -> Result<ObjectHandle>
pub fn generate_key( &self, mechanism: &Mechanism<'_>, template: &[Attribute] ) -> Result<ObjectHandle>
Generate a secret key
sourcepub fn generate_key_pair(
&self,
mechanism: &Mechanism<'_>,
pub_key_template: &[Attribute],
priv_key_template: &[Attribute]
) -> Result<(ObjectHandle, ObjectHandle)>
pub fn generate_key_pair( &self, mechanism: &Mechanism<'_>, pub_key_template: &[Attribute], priv_key_template: &[Attribute] ) -> Result<(ObjectHandle, ObjectHandle)>
Generate a public/private key pair
sourcepub fn derive_key(
&self,
mechanism: &Mechanism<'_>,
base_key: ObjectHandle,
template: &[Attribute]
) -> Result<ObjectHandle>
pub fn derive_key( &self, mechanism: &Mechanism<'_>, base_key: ObjectHandle, template: &[Attribute] ) -> Result<ObjectHandle>
Derives a key from a base key
sourcepub fn wrap_key(
&self,
mechanism: &Mechanism<'_>,
wrapping_key: ObjectHandle,
key: ObjectHandle
) -> Result<Vec<u8>>
pub fn wrap_key( &self, mechanism: &Mechanism<'_>, wrapping_key: ObjectHandle, key: ObjectHandle ) -> Result<Vec<u8>>
Wrap key
sourcepub fn unwrap_key(
&self,
mechanism: &Mechanism<'_>,
unwrapping_key: ObjectHandle,
wrapped_key: &[u8],
template: &[Attribute]
) -> Result<ObjectHandle>
pub fn unwrap_key( &self, mechanism: &Mechanism<'_>, unwrapping_key: ObjectHandle, wrapped_key: &[u8], template: &[Attribute] ) -> Result<ObjectHandle>
Unwrap previously wrapped key
source§impl Session
impl Session
sourcepub fn find_objects(&self, template: &[Attribute]) -> Result<Vec<ObjectHandle>>
pub fn find_objects(&self, template: &[Attribute]) -> Result<Vec<ObjectHandle>>
Search for session objects matching a template
sourcepub fn create_object(&self, template: &[Attribute]) -> Result<ObjectHandle>
pub fn create_object(&self, template: &[Attribute]) -> Result<ObjectHandle>
Create a new object
sourcepub fn destroy_object(&self, object: ObjectHandle) -> Result<()>
pub fn destroy_object(&self, object: ObjectHandle) -> Result<()>
Destroy an object
sourcepub fn get_attribute_info(
&self,
object: ObjectHandle,
attributes: &[AttributeType]
) -> Result<Vec<AttributeInfo>>
pub fn get_attribute_info( &self, object: ObjectHandle, attributes: &[AttributeType] ) -> Result<Vec<AttributeInfo>>
Get the attribute info of an object: if the attribute is present and its size.
§Arguments
object
- The ObjectHandle used to reference the objectattributes
- The list of attributes to get the information of
§Returns
This function will return a Vector of AttributeInfo enums that will either contain the size of the requested attribute, AttributeInfo::TypeInvalid if the attribute is not a valid type for the object, or AttributeInfo::Sensitive if the requested attribute is sensitive and will not be returned to the user.
The list of returned attributes is 1-to-1 matched with the provided vector of attribute types. If you wish, you may create a hash table simply by:
use cryptoki::context::Pkcs11;
use cryptoki::context::CInitializeArgs;
use cryptoki::object::AttributeType;
use cryptoki::session::UserType;
use cryptoki::types::AuthPin;
use std::collections::HashMap;
use std::env;
let mut pkcs11 = Pkcs11::new(
env::var("PKCS11_SOFTHSM2_MODULE")
.unwrap_or_else(|_| "/usr/local/lib/softhsm/libsofthsm2.so".to_string()),
)
.unwrap();
pkcs11.initialize(CInitializeArgs::OsThreads).unwrap();
let slot = pkcs11.get_slots_with_token().unwrap().remove(0);
let session = pkcs11.open_ro_session(slot).unwrap();
session.login(UserType::User, Some(&AuthPin::new("fedcba".into())));
let empty_attrib= vec![];
if let Some(object) = session.find_objects(&empty_attrib).unwrap().get(0) {
let attribute_types = vec![
AttributeType::Token,
AttributeType::Private,
AttributeType::Modulus,
AttributeType::KeyType,
AttributeType::Verify,];
let attribute_info = session.get_attribute_info(*object, &attribute_types).unwrap();
let hash = attribute_types
.iter()
.zip(attribute_info.iter())
.collect::<HashMap<_, _>>();
}
Alternatively, you can call Session::get_attribute_info_map, found below.
sourcepub fn get_attribute_info_map(
&self,
object: ObjectHandle,
attributes: Vec<AttributeType>
) -> Result<HashMap<AttributeType, AttributeInfo>>
pub fn get_attribute_info_map( &self, object: ObjectHandle, attributes: Vec<AttributeType> ) -> Result<HashMap<AttributeType, AttributeInfo>>
Get the attribute info of an object: if the attribute is present and its size.
§Arguments
object
- The ObjectHandle used to reference the objectattributes
- The list of attributes to get the information of
§Returns
This function will return a HashMap of AttributeType and AttributeInfo enums that will either contain the size of the requested attribute, AttributeInfo::TypeInvalid if the attribute is not a valid type for the object, or AttributeInfo::Sensitive if the requested attribute is sensitive and will not be returned to the user.
sourcepub fn get_attributes(
&self,
object: ObjectHandle,
attributes: &[AttributeType]
) -> Result<Vec<Attribute>>
pub fn get_attributes( &self, object: ObjectHandle, attributes: &[AttributeType] ) -> Result<Vec<Attribute>>
Get the attributes values of an object. Ignore the unavailable one. One has to call the get_attribute_info method to check which ones are unavailable.
sourcepub fn update_attributes(
&self,
object: ObjectHandle,
template: &[Attribute]
) -> Result<()>
pub fn update_attributes( &self, object: ObjectHandle, template: &[Attribute] ) -> Result<()>
Sets the attributes of an object
source§impl Session
impl Session
sourcepub fn generate_random_slice(&self, random_data: &mut [u8]) -> Result<()>
pub fn generate_random_slice(&self, random_data: &mut [u8]) -> Result<()>
Generates a random number and sticks it in a slice
§Arguments
random_slice
- The slice to stick the random data into. The length of the slice represents the number of bytes to obtain from the RBG
sourcepub fn generate_random_vec(&self, random_len: u32) -> Result<Vec<u8>>
pub fn generate_random_vec(&self, random_len: u32) -> Result<Vec<u8>>
Generates random data and returns it as a Vec<u8>
. The length of the returned Vector will
be the amount of random requested, which is random_len
.
sourcepub fn seed_random(&self, seed: &[u8]) -> Result<()>
pub fn seed_random(&self, seed: &[u8]) -> Result<()>
Seeds the RNG
source§impl Session
impl Session
sourcepub fn login(&self, user_type: UserType, pin: Option<&AuthPin>) -> Result<()>
pub fn login(&self, user_type: UserType, pin: Option<&AuthPin>) -> Result<()>
Log a session in.
§Arguments
user_type
- The type of user to log in aspin
- The PIN to use, orNone
if you wish to use the protected authentication path
NOTE: By passing None
into login
, you must ensure that the
CKF_PROTECTED_AUTHENTICATION_PATH flag is set in the TokenFlags
.
sourcepub fn login_with_raw(
&self,
user_type: UserType,
pin: &RawAuthPin
) -> Result<()>
pub fn login_with_raw( &self, user_type: UserType, pin: &RawAuthPin ) -> Result<()>
Logs a session in using a slice of raw bytes as a PIN. Some dongle drivers allow non UTF-8 characters in the PIN and as a result, we aren’t guaranteed that we can pass in a UTF-8 string to login. Therefore, it’s useful to be able to pass in raw bytes rather than convert a UTF-8 string to bytes.
§Arguments
user_type
- The type of user to log in aspin
- The PIN to use
NOTE: By passing None
into login
, you must ensure that the
CKF_PROTECTED_AUTHENTICATION_PATH flag is set in the TokenFlags
.
sourcepub fn get_session_info(&self) -> Result<SessionInfo>
pub fn get_session_info(&self) -> Result<SessionInfo>
Returns the information about a session