credibil_infosec/
lib.rs

1//! # Data Security for Credibil
2//!
3//! This crate provides common utilities for the Credibil project and is not
4//! intended to be used directly.
5
6pub mod cose;
7pub mod jose;
8pub mod proof;
9
10use std::future::{Future, IntoFuture};
11
12use anyhow::Result;
13use serde::{Deserialize, Serialize};
14
15pub use crate::jose::jwa::Algorithm;
16pub use crate::jose::jwe::{PublicKey, SecretKey, SharedSecret};
17pub use crate::jose::jwk::PublicKeyJwk;
18pub use crate::jose::jws::Jws;
19pub use crate::jose::jwt::Jwt;
20
21/// Signer is used by implementers to provide signing functionality for
22/// Verifiable Credential issuance and Verifiable Presentation submissions.
23pub trait Signer: Send + Sync {
24    /// Sign is a convenience method for infallible Signer implementations.
25    fn sign(&self, msg: &[u8]) -> impl Future<Output = Vec<u8>> + Send {
26        let v = async { self.try_sign(msg).await.expect("should sign") };
27        v.into_future()
28    }
29
30    /// `TrySign` is the fallible version of Sign.
31    fn try_sign(&self, msg: &[u8]) -> impl Future<Output = Result<Vec<u8>>> + Send;
32
33    /// The verifying key (public key) from the signing keypair.
34    ///
35    /// The possibility of key rotation mean this key should only be referenced
36    /// at the point of verifying a signature.
37    fn verifying_key(&self) -> impl Future<Output = Result<Vec<u8>>> + Send;
38
39    /// Signature algorithm used by the signer.
40    fn algorithm(&self) -> Algorithm;
41
42    /// The verification method the verifier should use to verify the signer's
43    /// signature. This is typically a DID URL + # + verification key ID.
44    ///
45    /// Async and fallible because the client may need to access key information
46    /// to construct the method reference.
47    fn verification_method(&self) -> impl Future<Output = Result<String>> + Send;
48}
49
50/// A Receiver (Recipient) is required to decrypt an encrypted message.
51pub trait Receiver: Send + Sync {
52    /// The Receiver's public key identifier used to identify the recipient in
53    /// a multi-recipient JWE
54    ///
55    /// For example, `did:example:alice#key-id`.
56    fn key_id(&self) -> String;
57
58    /// Derive the receiver's shared secret used for decrypting (or direct use)
59    /// for the Content Encryption Key.
60    ///
61    /// `[SecretKey]` wraps the receiver's private key to provide the key
62    /// derivation functionality using ECDH-ES. The resultant `[SharedSecret]`
63    /// is used in decrypting the JWE ciphertext.
64    ///
65    /// `[SecretKey]` supports both X25519 and secp256k1 private keys.
66    ///
67    /// # Errors
68    /// LATER: document errors
69    ///
70    /// # Example
71    ///
72    /// This example derives a shared secret from an X25519 private key.
73    ///
74    /// ```rust,ignore
75    /// use rand::rngs::OsRng;
76    /// use x25519_dalek::{StaticSecret, PublicKey};
77    ///
78    /// struct KeyStore {
79    ///     secret: StaticSecret,
80    /// }
81    ///
82    /// impl KeyStore {
83    ///     fn new() -> Self {
84    ///         Self {
85    ///             secret: StaticSecret::random_from_rng(OsRng),
86    ///         }
87    ///     }
88    /// }
89    ///
90    /// impl Receiver for KeyStore {
91    ///    fn key_id(&self) -> String {
92    ///         "did:example:alice#key-id".to_string()
93    ///    }
94    ///
95    /// async fn shared_secret(&self, sender_public: PublicKey) -> Result<SharedSecret> {
96    ///     let secret_key = SecretKey::from(self.secret.to_bytes());
97    ///     secret_key.shared_secret(sender_public)
98    /// }
99    /// ```
100    fn shared_secret(
101        &self, sender_public: PublicKey,
102    ) -> impl Future<Output = Result<SharedSecret>> + Send;
103}
104
105/// Cryptographic key type.
106#[derive(Clone, Debug, Default, Deserialize, Serialize, Eq, PartialEq)]
107pub enum KeyType {
108    /// Octet key pair (Edwards curve)
109    #[default]
110    #[serde(rename = "OKP")]
111    Okp,
112
113    /// Elliptic curve key pair
114    #[serde(rename = "EC")]
115    Ec,
116
117    /// Octet string
118    #[serde(rename = "oct")]
119    Oct,
120}
121
122/// Cryptographic curve type.
123#[derive(Clone, Debug, Default, Deserialize, Serialize, Eq, PartialEq)]
124pub enum Curve {
125    /// Ed25519 signature (DSA) key pairs.
126    #[default]
127    Ed25519,
128
129    /// X25519 function (encryption) key pairs.
130    X25519,
131
132    /// secp256k1 curve.
133    #[serde(rename = "ES256K", alias = "secp256k1")]
134    Es256K,
135}
credibil_infosec/lib.rs

credibil_infosec/
lib.rs
