willow25 0.4.0

A ready-to-use implementation of the Willow specifications.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

use core::fmt;

#[cfg(feature = "dev")]
use arbitrary::Arbitrary;

use ed25519_dalek::SigningKey;
use rand_core::CryptoRngCore;
use signature::{Keypair, Signer};

use crate::prelude::*;

wrapper! {
    /// A secret key corresponding to a [`NamespaceId`] — see the [`NamespaceId`] docs for an overview, and see the [`authentication`](crate::authorisation) docs for how to use the secret for authentication.
    ///
    /// You can randomly generate namespace secrets and their corresponding namespace ids with the [`randomly_generate_namespace`], [`randomly_generate_communal_namespace`], and [`randomly_generate_owned_namespace`] function.
    ///
    /// This type is a fairly thin wrapper around [`SigningKey`], use the [`From`] implementations to convert between the two.
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::prelude::*;
    ///
    /// let mut csprng = OsRng; // cryptographically secure pseudo-random number generator
    ///
    /// let (namespace_id1, _secret1) = randomly_generate_communal_namespace(&mut csprng);
    /// assert!(namespace_id1.is_communal());
    ///
    /// let (namespace_id2, _secret2) = randomly_generate_owned_namespace(&mut csprng);
    /// assert!(namespace_id2.is_owned());
    /// ```
    #[derive(PartialEq, Eq, Clone)]
    NamespaceSecret; SigningKey
}

impl fmt::Debug for NamespaceSecret {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

impl NamespaceSecret {
    /// Computes the [`NamespaceId`] corresponding to `self`, i.e., the [`NamespaceId`] which can be used to verify [`NamespaceSignatures`](super::NamespaceSignature) issued by `self`.
    ///
    /// ```
    /// use rand::rngs::OsRng;
    /// use willow25::prelude::*;
    ///
    /// let mut csprng = OsRng; // cryptographically secure pseudo-random number generator
    ///
    /// let (namespace_id, secret) = randomly_generate_namespace(&mut csprng);
    ///
    /// assert_eq!(secret.corresponding_namespace_id(), namespace_id);
    /// ```
    pub fn corresponding_namespace_id(&self) -> NamespaceId {
        NamespaceId::from_ed25519_verifying_key(self.0.verifying_key())
    }
}

#[cfg(feature = "dev")]
impl<'a> Arbitrary<'a> for NamespaceSecret {
    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
        Ok(Self(SigningKey::from_bytes(&Arbitrary::arbitrary(u)?)))
    }
}

/// Randomly generate a [`NamespaceSecret`] and the corresponding [`NamespaceId`].
///
/// See also [`randomly_generate_communal_namespace`] and [`randomly_generate_owned_namespace`] if you need control over whether to generate an [owned namespace](https://willowprotocol.org/specs/meadowcap/#owned_namespace) or a [communal namespace](https://willowprotocol.org/specs/meadowcap/#communal_namespace).
///
/// ```
/// use rand::rngs::OsRng;
/// use willow25::prelude::*;
///
/// let mut csprng = OsRng; // cryptographically secure pseudo-random number generator
///
/// let (_namespace_id, _secret) = randomly_generate_namespace(&mut csprng);
/// ```
pub fn randomly_generate_namespace<R: CryptoRngCore + ?Sized>(
    csprng: &mut R,
) -> (NamespaceId, NamespaceSecret) {
    let signing_key = SigningKey::generate(csprng);
    let verifying_key = signing_key.verifying_key();

    (
        NamespaceId::from_ed25519_verifying_key(verifying_key),
        NamespaceSecret(signing_key),
    )
}

/// Randomly generate a [`NamespaceSecret`] for a [communal namespace](https://willowprotocol.org/specs/meadowcap/#communal_namespace) and the corresponding [`NamespaceId`].
///
/// ```
/// use rand::rngs::OsRng;
/// use willow25::prelude::*;
///
/// let mut csprng = OsRng; // cryptographically secure pseudo-random number generator
///
/// let (namespace_id, _secret) = randomly_generate_communal_namespace(&mut csprng);
/// assert!(namespace_id.is_communal());
/// ```
pub fn randomly_generate_communal_namespace<R: CryptoRngCore + ?Sized>(
    csprng: &mut R,
) -> (NamespaceId, NamespaceSecret) {
    loop {
        let (pk, sk) = randomly_generate_namespace(csprng);

        if pk.is_communal() {
            return (pk, sk);
        }
    }
}

/// Randomly generate a [`NamespaceSecret`] for an [owned namespace](https://willowprotocol.org/specs/meadowcap/#owned_namespace) and the corresponding [`NamespaceId`].
///
/// ```
/// use rand::rngs::OsRng;
/// use willow25::prelude::*;
///
/// let mut csprng = OsRng; // cryptographically secure pseudo-random number generator
///
/// let (namespace_id, _secret) = randomly_generate_owned_namespace(&mut csprng);
/// assert!(namespace_id.is_owned());
/// ```
pub fn randomly_generate_owned_namespace<R: CryptoRngCore + ?Sized>(
    csprng: &mut R,
) -> (NamespaceId, NamespaceSecret) {
    loop {
        let (pk, sk) = randomly_generate_namespace(csprng);

        if !pk.is_communal() {
            return (pk, sk);
        }
    }
}

impl Keypair for NamespaceSecret {
    type VerifyingKey = NamespaceId;

    fn verifying_key(&self) -> Self::VerifyingKey {
        self.corresponding_namespace_id()
    }
}

impl Signer<NamespaceSignature> for NamespaceSecret {
    fn try_sign(&self, msg: &[u8]) -> Result<NamespaceSignature, signature::Error> {
        self.0.try_sign(msg).map(Into::into)
    }
}