[−][src]Struct parsec_client::core::basic_client::BasicClient
Core client for Parsec service
The client exposes low-level functionality for using the Parsec service. Below you can see code examples for a few of the operations supported.
For all cryptographic operations an implicit provider is used which can be
changed between operations. The client starts with no such defined provider
and it is the responsibility of the user to identify and set an appropriate
one. As such, it is critical that before attempting to use cryptographic
operations users call list_providers
and list_opcodes
in order to figure out if their desired use case and provider are
available.
Creating a BasicClient
instance:
use parsec_client::auth::AuthenticationData; use parsec_client::BasicClient; use parsec_client::core::secrecy::Secret; let app_name = String::from("app-name"); let app_auth_data = AuthenticationData::AppIdentity(Secret::new(app_name)); let client: BasicClient = BasicClient::new(app_auth_data);
Performing a Ping operation helps to determine if the service is available and what wire protocol it supports. Currently only a version 1.0 of the wire protocol exists and new versions are expected to be extremely rare.
let res = client.ping(); if let Ok((wire_prot_v_maj, wire_prot_v_min)) = res { println!( "Success! Service wire protocol version is {}.{}", wire_prot_v_maj, wire_prot_v_min ); } else { panic!("Ping failed. Error: {:?}", res); }
Providers are abstracted representations of the secure elements that PARSEC offers abstraction over. Providers are the ones to execute the cryptographic operations requested by the user.
Checking for available providers:
use uuid::Uuid; let desired_provider_uuid = Uuid::parse_str("30e39502-eba6-4d60-a4af-c518b7f5e38f").unwrap(); let available_providers = client.list_providers().expect("Failed to list providers"); if available_providers .iter() .filter(|provider| provider.uuid == desired_provider_uuid) .count() == 0 { panic!("Did not find desired provider!"); }
Checking operations supported by the provider we're interested in is done
through the list_opcodes
method:
use parsec_client::core::interface::requests::Opcode; let desired_provider = ProviderID::Pkcs11; let provider_opcodes = client .list_opcodes(desired_provider) .expect("Failed to list opcodes"); assert!(provider_opcodes.contains(&Opcode::PsaGenerateKey)); assert!(provider_opcodes.contains(&Opcode::PsaSignHash)); assert!(provider_opcodes.contains(&Opcode::PsaDestroyKey)); client.set_implicit_provider(desired_provider);
Creating a key-pair for signing SHA256 digests with RSA PKCS#1 v1.5:
use parsec_client::core::interface::operations::psa_algorithm::{Algorithm, AsymmetricSignature, Hash}; use parsec_client::core::interface::operations::psa_key_attributes::{Attributes, Lifetime, Policy, Type, UsageFlags}; let key_name = String::from("rusty key 🔑"); let asym_sign_algo = AsymmetricSignature::RsaPkcs1v15Sign { hash_alg: Hash::Sha256.into(), }; let key_attrs = Attributes { lifetime: Lifetime::Persistent, key_type: Type::RsaKeyPair, bits: 2048, policy: Policy { usage_flags: UsageFlags { export: true, copy: true, cache: true, encrypt: false, decrypt: false, sign_message: true, verify_message: false, sign_hash: true, verify_hash: false, derive: false, }, permitted_algorithms: asym_sign_algo.into(), }, }; client .psa_generate_key(key_name.clone(), key_attrs) .expect("Failed to create key!");
Implementations
impl BasicClient
[src]
Main client functionality.
pub fn new(auth_data: AuthenticationData) -> Self
[src]
Create a new Parsec client given the authentication data of the app.
Before you can use this client for cryptographic operations, you first need to call
set_implicit_provider
. In order to get a list of
supported providers, call the list_providers
method.
pub fn set_auth_data(&mut self, auth_data: AuthenticationData)
[src]
Update the authentication data of the client.
pub fn auth_data(&self) -> AuthenticationData
[src]
Retrieve authentication data of the client.
pub fn set_implicit_provider(&mut self, provider: ProviderID)
[src]
Set the provider that the client will be implicitly working with.
pub fn implicit_provider(&self) -> Option<ProviderID>
[src]
Retrieve client's implicit provider.
pub fn list_opcodes(&self, provider: ProviderID) -> Result<HashSet<Opcode>>
[src]
[Core Operation] List the opcodes supported by the specified provider.
pub fn list_providers(&self) -> Result<Vec<ProviderInfo>>
[src]
[Core Operation] List the providers that are supported by the service.
pub fn list_authenticators(&self) -> Result<Vec<AuthenticatorInfo>>
[src]
[Core Operation] List the authenticators that are supported by the service.
pub fn ping(&self) -> Result<(u8, u8)>
[src]
[Core Operation] Send a ping request to the service.
This operation is intended for testing connectivity to the service and for retrieving the maximum wire protocol version it supports.
pub fn psa_generate_key(
&self,
key_name: String,
key_attributes: Attributes
) -> Result<()>
[src]
&self,
key_name: String,
key_attributes: Attributes
) -> Result<()>
[Cryptographic Operation] Generate a key.
Creates a new key with the given name within the namespace of the implicit client provider. Any UTF-8 string is considered a valid key name, however names must be unique per provider.
Persistence of keys is implemented at provider level, and currently all providers persist all the keys users create. However, no methods exist for discovering previously generated or imported keys, so users are responsible for keeping track of keys they have created.
Errors
If this method returns an error, no key will have been generated and the name used will still be available for another key.
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_destroy_key(&self, key_name: String) -> Result<()>
[src]
[Cryptographic Operation] Destroy a key.
Given that keys are namespaced at a provider level, it is
important to call psa_destroy_key
on the correct combination of
implicit client provider and key_name
.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_import_key(
&self,
key_name: String,
key_material: &[u8],
key_attributes: Attributes
) -> Result<()>
[src]
&self,
key_name: String,
key_material: &[u8],
key_attributes: Attributes
) -> Result<()>
[Cryptographic Operation] Import a key.
Creates a new key with the given name within the namespace of the implicit client provider using the user-provided data. Any UTF-8 string is considered a valid key name, however names must be unique per provider.
The key material should follow the appropriate binary format expressed
here.
Several crates (e.g. picky-asn1
)
can greatly help in dealing with binary encodings.
Persistence of keys is implemented at provider level, and currently all providers persist all the keys users create. However, no methods exist for discovering previously generated or imported keys, so users are responsible for keeping track of keys they have created.
Errors
If this method returns an error, no key will have been imported and the name used will still be available for another key.
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_export_public_key(&self, key_name: String) -> Result<Vec<u8>>
[src]
[Cryptographic Operation] Export a public key or the public part of a key pair.
The returned key material will follow the appropriate binary format expressed
here.
Several crates (e.g. picky-asn1
)
can greatly help in dealing with binary encodings.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_export_key(&self, key_name: String) -> Result<Vec<u8>>
[src]
[Cryptographic Operation] Export a key.
The returned key material will follow the appropriate binary format expressed
here.
Several crates (e.g. picky-asn1
)
can greatly help in dealing with binary encodings.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_sign_hash(
&self,
key_name: String,
hash: &[u8],
sign_algorithm: AsymmetricSignature
) -> Result<Vec<u8>>
[src]
&self,
key_name: String,
hash: &[u8],
sign_algorithm: AsymmetricSignature
) -> Result<Vec<u8>>
[Cryptographic Operation] Create an asymmetric signature on a pre-computed message digest.
The key intended for signing must have its sign_hash
flag set
to true
in its key policy.
The signature will be created with the algorithm defined in
sign_algorithm
, but only after checking that the key policy
and type conform with it.
hash
must be a hash pre-computed over the message of interest
with the algorithm specified within sign_algorithm
.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_verify_hash(
&self,
key_name: String,
hash: &[u8],
sign_algorithm: AsymmetricSignature,
signature: &[u8]
) -> Result<()>
[src]
&self,
key_name: String,
hash: &[u8],
sign_algorithm: AsymmetricSignature,
signature: &[u8]
) -> Result<()>
[Cryptographic Operation] Verify an existing asymmetric signature over a pre-computed message digest.
The key intended for signing must have its verify_hash
flag set
to true
in its key policy.
The signature will be verifyied with the algorithm defined in
sign_algorithm
, but only after checking that the key policy
and type conform with it.
hash
must be a hash pre-computed over the message of interest
with the algorithm specified within sign_algorithm
.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_asymmetric_encrypt(
&self,
key_name: String,
encrypt_alg: AsymmetricEncryption,
plaintext: &[u8],
salt: Option<&[u8]>
) -> Result<Vec<u8>>
[src]
&self,
key_name: String,
encrypt_alg: AsymmetricEncryption,
plaintext: &[u8],
salt: Option<&[u8]>
) -> Result<Vec<u8>>
[Cryptographic Operation] Encrypt a short message.
The key intended for encrypting must have its encrypt
flag set
to true
in its key policy.
The encryption will be performed with the algorithm defined in alg
,
but only after checking that the key policy and type conform with it.
salt
can be provided if supported by the algorithm. If the algorithm does not support salt, pass
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_asymmetric_decrypt(
&self,
key_name: String,
encrypt_alg: AsymmetricEncryption,
ciphertext: &[u8],
salt: Option<&[u8]>
) -> Result<Vec<u8>>
[src]
&self,
key_name: String,
encrypt_alg: AsymmetricEncryption,
ciphertext: &[u8],
salt: Option<&[u8]>
) -> Result<Vec<u8>>
[Cryptographic Operation] Decrypt a short message.
The key intended for decrypting must have its decrypt
flag set
to true
in its key policy.
salt
can be provided if supported by the algorithm. If the algorithm does not support salt, pass
The decryption will be performed with the algorithm defined in alg
,
but only after checking that the key policy and type conform with it.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_hash_compute(&self, alg: Hash, input: &[u8]) -> Result<Vec<u8>>
[src]
[Cryptographic Operation] Compute hash of a message.
The hash computation will be performed with the algorithm defined in alg
.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_hash_compare(
&self,
alg: Hash,
input: &[u8],
hash: &[u8]
) -> Result<()>
[src]
&self,
alg: Hash,
input: &[u8],
hash: &[u8]
) -> Result<()>
[Cryptographic Operation] Compute hash of a message and compare it with a reference value.
The hash computation will be performed with the algorithm defined in alg
.
If this operation returns no error, the hash was computed successfully and it matches the reference value.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_aead_encrypt(
&self,
key_name: String,
encrypt_alg: Aead,
nonce: &[u8],
additional_data: &[u8],
plaintext: &[u8]
) -> Result<Vec<u8>>
[src]
&self,
key_name: String,
encrypt_alg: Aead,
nonce: &[u8],
additional_data: &[u8],
plaintext: &[u8]
) -> Result<Vec<u8>>
[Cryptographic Operation] Authenticate and encrypt a short message.
The key intended for decrypting must have its encrypt
flag set
to true
in its key policy.
The encryption will be performed with the algorithm defined in alg
,
but only after checking that the key policy and type conform with it.
nonce
must be appropriate for the selected alg
.
For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the returned buffer will contain the encrypted data followed by the authentication data.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_aead_decrypt(
&self,
key_name: String,
encrypt_alg: Aead,
nonce: &[u8],
additional_data: &[u8],
ciphertext: &[u8]
) -> Result<Vec<u8>>
[src]
&self,
key_name: String,
encrypt_alg: Aead,
nonce: &[u8],
additional_data: &[u8],
ciphertext: &[u8]
) -> Result<Vec<u8>>
[Cryptographic Operation] Decrypt and authenticate a short message.
The key intended for decrypting must have its decrypt
flag set
to true
in its key policy.
The decryption will be performed with the algorithm defined in alg
,
but only after checking that the key policy and type conform with it.
nonce
must be appropriate for the selected alg
.
For algorithms where the encrypted data and the authentication tag are defined as separate inputs,
ciphertext
must contain the encrypted data followed by the authentication data.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_raw_key_agreement(
&self,
alg: RawKeyAgreement,
private_key_name: String,
peer_key: &[u8]
) -> Result<Vec<u8>>
[src]
&self,
alg: RawKeyAgreement,
private_key_name: String,
peer_key: &[u8]
) -> Result<Vec<u8>>
[Cryptographic Operation] Perform a raw key agreement.
The provided private key must have its derive
flag set
to true
in its key policy.
The raw_key_agreement will be performed with the algorithm defined in alg
,
but only after checking that the key policy and type conform with it.
peer_key
must be the peer public key to use in the raw key derivation. It must
be in a format supported by PsaImportKey
.
Errors
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
pub fn psa_generate_random(&self, nbytes: usize) -> Result<Vec<u8>>
[src]
[Cryptographic Operation] Generate some random bytes.
Generates a sequence of random bytes and returns them to the user.
Errors
If this method returns an error, no bytes will have been generated.
If the implicit client provider is ProviderID::Core
, a client error
of InvalidProvider
type is returned.
If the implicit client provider has not been set, a client error of
NoProvider
type is returned.
See the operation-specific response codes returned by the service here.
impl BasicClient
[src]
Configuration methods for controlling communication with the service.
pub fn set_request_body_converter(
&mut self,
content_converter: Box<dyn Convert + Send + Sync>
)
[src]
&mut self,
content_converter: Box<dyn Convert + Send + Sync>
)
Set the converter used for request bodies handled by this client.
By default Protobuf will be used for this.
pub fn set_response_body_converter(
&mut self,
accept_converter: Box<dyn Convert + Send + Sync>
)
[src]
&mut self,
accept_converter: Box<dyn Convert + Send + Sync>
)
Set the converter used for response bodies handled by this client.
By default Protobuf will be used for this.
impl BasicClient
[src]
Configuration methods for controlling IPC-level options.
pub fn set_max_body_size(&mut self, max_body_size: usize)
[src]
Set the maximum body size allowed for requests.
Defaults to the maximum value of usize
.
pub fn set_ipc_handler(&mut self, ipc_handler: Box<dyn Connect + Send + Sync>)
[src]
Set the IPC handler used for communication with the service.
By default the Unix domain socket client is used.
pub fn set_timeout(&mut self, timeout: Option<Duration>)
[src]
Set the timeout for operations on the IPC stream.
The value defaults to 1 second.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for BasicClient
impl Send for BasicClient
impl Sync for BasicClient
impl Unpin for BasicClient
impl !UnwindSafe for BasicClient
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,