tor_interface/
tor_crypto.rs

1// standard
2use std::convert::TryInto;
3use std::str;
4
5// extern crates
6use curve25519_dalek::Scalar;
7use data_encoding::{BASE32_NOPAD, BASE64};
8use data_encoding_macro::new_encoding;
9#[cfg(any(feature = "legacy-tor-provider", feature = "arti-tor-provider"))]
10use rand::distr::Alphanumeric;
11#[cfg(any(feature = "legacy-tor-provider", feature = "arti-tor-provider"))]
12use rand::Rng;
13use sha3::{Digest, Sha3_256};
14use static_assertions::const_assert_eq;
15use tor_llcrypto::pk::keymanip::*;
16use tor_llcrypto::*;
17
18/// Represents various errors that can occur in the tor_crypto module.
19#[derive(thiserror::Error, Debug)]
20pub enum Error {
21    /// A error encountered converting a String to a tor_crypto type
22    #[error("{0}")]
23    ParseError(String),
24
25    /// An error encountered converting between tor_crypto types
26    #[error("{0}")]
27    ConversionError(String),
28
29    /// An error encountered converting from a raw byte representation
30    #[error("invalid key")]
31    KeyInvalid,
32}
33
34/// The number of bytes in an ed25519 secret key
35/// cbindgen:ignore
36pub const ED25519_PRIVATE_KEY_SIZE: usize = 64;
37/// The number of bytes in an ed25519 public key
38/// cbindgen:ignore
39pub const ED25519_PUBLIC_KEY_SIZE: usize = 32;
40/// The number of bytes in an ed25519 signature
41/// cbindgen:ignore
42pub const ED25519_SIGNATURE_SIZE: usize = 64;
43/// The number of bytes needed to store onion service id as an ASCII c-string (not including null-terminator)
44pub const V3_ONION_SERVICE_ID_STRING_LENGTH: usize = 56;
45/// The number of bytes needed to store onion service id as an ASCII c-string (including null-terminator)
46pub const V3_ONION_SERVICE_ID_STRING_SIZE: usize = 57;
47const_assert_eq!(
48    V3_ONION_SERVICE_ID_STRING_SIZE,
49    V3_ONION_SERVICE_ID_STRING_LENGTH + 1
50);
51/// The number of bytes needed to store base64 encoded ed25519 private key as an ASCII c-string (not including null-terminator)
52pub const ED25519_PRIVATE_KEYBLOB_BASE64_LENGTH: usize = 88;
53/// key klob header string
54const ED25519_PRIVATE_KEY_KEYBLOB_HEADER: &str = "ED25519-V3:";
55/// The number of bytes needed to store the keyblob header
56pub const ED25519_PRIVATE_KEY_KEYBLOB_HEADER_LENGTH: usize = 11;
57const_assert_eq!(
58    ED25519_PRIVATE_KEY_KEYBLOB_HEADER_LENGTH,
59    ED25519_PRIVATE_KEY_KEYBLOB_HEADER.len()
60);
61/// The number of bytes needed to store ed25519 private keyblob as an ASCII c-string (not including a null terminator)
62pub const ED25519_PRIVATE_KEY_KEYBLOB_LENGTH: usize = 99;
63const_assert_eq!(
64    ED25519_PRIVATE_KEY_KEYBLOB_LENGTH,
65    ED25519_PRIVATE_KEY_KEYBLOB_HEADER_LENGTH + ED25519_PRIVATE_KEYBLOB_BASE64_LENGTH
66);
67/// The number of bytes needed to store ed25519 private keyblob as an ASCII c-string (including a null terminator)
68pub const ED25519_PRIVATE_KEY_KEYBLOB_SIZE: usize = 100;
69const_assert_eq!(
70    ED25519_PRIVATE_KEY_KEYBLOB_SIZE,
71    ED25519_PRIVATE_KEY_KEYBLOB_LENGTH + 1
72);
73// number of bytes in an onion service id after base32 decode
74const V3_ONION_SERVICE_ID_RAW_SIZE: usize = 35;
75// byte index of the start of the public key checksum
76const V3_ONION_SERVICE_ID_CHECKSUM_OFFSET: usize = 32;
77// byte index of the v3 onion service version
78const V3_ONION_SERVICE_ID_VERSION_OFFSET: usize = 34;
79/// The number of bytes in a v3 service id's truncated checksum
80const TRUNCATED_CHECKSUM_SIZE: usize = 2;
81/// The number of bytes in an x25519 private key
82/// cbindgen:ignore
83pub const X25519_PRIVATE_KEY_SIZE: usize = 32;
84/// The number of bytes in an x25519 publickey
85/// cbindgen:ignore
86pub const X25519_PUBLIC_KEY_SIZE: usize = 32;
87/// The number of bytes needed to store base64 encoded x25519 private key as an ASCII c-string (not including null-terminator)
88pub const X25519_PRIVATE_KEY_BASE64_LENGTH: usize = 44;
89/// The number of bytes needed to store base64 encoded x25519 private key as an ASCII c-string (including a null terminator)
90pub const X25519_PRIVATE_KEY_BASE64_SIZE: usize = 45;
91const_assert_eq!(
92    X25519_PRIVATE_KEY_BASE64_SIZE,
93    X25519_PRIVATE_KEY_BASE64_LENGTH + 1
94);
95/// The number of bytes needed to store base32 encoded x25519 public key as an ASCII c-string (not including null-terminator)
96pub const X25519_PUBLIC_KEY_BASE32_LENGTH: usize = 52;
97/// The number of bytes needed to store base32 encoded x25519 public key as an ASCII c-string (including a null terminator)
98pub const X25519_PUBLIC_KEY_BASE32_SIZE: usize = 53;
99const_assert_eq!(
100    X25519_PUBLIC_KEY_BASE32_SIZE,
101    X25519_PUBLIC_KEY_BASE32_LENGTH + 1
102);
103
104const ONION_BASE32: data_encoding::Encoding = new_encoding! {
105    symbols: "abcdefghijklmnopqrstuvwxyz234567",
106    padding: '=',
107};
108
109// Free functions
110
111// securely generate password using CautionsRng
112#[cfg(any(feature = "legacy-tor-provider", feature = "arti-tor-provider"))]
113pub(crate) fn generate_password(length: usize) -> String {
114    let password: String = std::iter::repeat(())
115        .map(|()| tor_llcrypto::rng::CautiousRng.sample(Alphanumeric))
116        .map(char::from)
117        .take(length)
118        .collect();
119
120    password
121}
122
123// Struct deinitions
124
125/// An ed25519 private key.
126///
127/// This key type is used with [`crate::tor_provider::TorProvider`] trait for hosting onion-services and can be convertd to an [`Ed25519PublicKey`]. It can also be used to sign messages and create an [`Ed25519Signature`].
128pub struct Ed25519PrivateKey {
129    expanded_keypair: pk::ed25519::ExpandedKeypair,
130}
131
132/// An ed25519 public key.
133///
134/// This key type is derived from [`Ed25519PrivateKey`] and can be converted to a [`V3OnionServiceId`]. It can also be used to verify a [`Ed25519Signature`].
135#[derive(Clone)]
136pub struct Ed25519PublicKey {
137    public_key: pk::ed25519::PublicKey,
138}
139
140/// An ed25519 cryptographic signature
141#[derive(Clone)]
142pub struct Ed25519Signature {
143    signature: pk::ed25519::Signature,
144}
145
146/// An x25519 private key
147#[derive(Clone)]
148pub struct X25519PrivateKey {
149    secret_key: pk::curve25519::StaticSecret,
150}
151
152/// An x25519 public key
153#[derive(Clone, PartialEq, Eq)]
154pub struct X25519PublicKey {
155    public_key: pk::curve25519::PublicKey,
156}
157
158/// A v3 onion-service id
159#[derive(Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
160pub struct V3OnionServiceId {
161    data: [u8; V3_ONION_SERVICE_ID_STRING_LENGTH],
162}
163
164/// An enum representing a single bit
165#[derive(Clone, Copy)]
166pub enum SignBit {
167    Zero,
168    One,
169}
170
171impl From<SignBit> for u8 {
172    fn from(signbit: SignBit) -> Self {
173        match signbit {
174            SignBit::Zero => 0u8,
175            SignBit::One => 1u8,
176        }
177    }
178}
179
180impl From<SignBit> for bool {
181    fn from(signbit: SignBit) -> Self {
182        match signbit {
183            SignBit::Zero => false,
184            SignBit::One => true,
185        }
186    }
187}
188
189impl From<bool> for SignBit {
190    fn from(signbit: bool) -> Self {
191        if signbit {
192            SignBit::One
193        } else {
194            SignBit::Zero
195        }
196    }
197}
198
199// which validation method to use when constructing an ed25519 expanded key from
200// a byte array
201enum FromRawValidationMethod {
202    // expanded ed25519 keys coming from legacy c-tor daemon; the scalar portion
203    // is clamped, but not reduced
204    #[cfg(feature = "legacy-tor-provider")]
205    LegacyCTor,
206    // expanded ed25519 keys coming from ed25519-dalek crate; the scalar portion
207    // has been clamped AND reduced
208    Ed25519Dalek,
209}
210
211/// A wrapper around `tor_llcrypto::pk::ed25519::ExpandedKeypair`.
212impl Ed25519PrivateKey {
213    /// Securely generate a new `Ed25519PrivateKey`.
214    pub fn generate() -> Ed25519PrivateKey {
215        let csprng = &mut tor_llcrypto::rng::CautiousRng;
216        let keypair = pk::ed25519::Keypair::generate(csprng);
217
218        Ed25519PrivateKey {
219            expanded_keypair: pk::ed25519::ExpandedKeypair::from(&keypair),
220        }
221    }
222
223    fn from_raw_impl(
224        raw: &[u8; ED25519_PRIVATE_KEY_SIZE],
225        method: FromRawValidationMethod,
226    ) -> Result<Ed25519PrivateKey, Error> {
227        // see: https://gitlab.torproject.org/tpo/core/arti/-/issues/1343
228        match method {
229            #[cfg(feature = "legacy-tor-provider")]
230            FromRawValidationMethod::LegacyCTor => {
231                // Verify the scalar portion of the expanded key has been clamped
232                // see: https://gitlab.torproject.org/tpo/core/arti/-/issues/1021
233                if !(raw[0] == raw[0] & 248 && raw[31] == (raw[31] & 63) | 64) {
234                    return Err(Error::KeyInvalid);
235                }
236            }
237            FromRawValidationMethod::Ed25519Dalek => {
238                // Verify the scalar is non-zero and it has been reduced
239                let scalar: [u8; 32] = raw[..32].try_into().unwrap();
240                if scalar.iter().all(|&x| x == 0x00u8) {
241                    return Err(Error::KeyInvalid);
242                }
243                let reduced_scalar = Scalar::from_bytes_mod_order(scalar).to_bytes();
244                if scalar != reduced_scalar {
245                    return Err(Error::KeyInvalid);
246                }
247            }
248        }
249
250        if let Some(expanded_keypair) = pk::ed25519::ExpandedKeypair::from_secret_key_bytes(*raw) {
251            Ok(Ed25519PrivateKey { expanded_keypair })
252        } else {
253            Err(Error::KeyInvalid)
254        }
255    }
256
257    /// Attempt to create an `Ed25519PrivateKey` from an array of bytes. Not all byte buffers of the required size can create a valid `Ed25519PrivateKey`. Only buffers derived from [`Ed25519PrivateKey::to_bytes()`] are required to convert correctly.
258    ///
259    /// To securely generate a valid `Ed25519PrivateKey`, use [`Ed25519PrivateKey::generate()`].
260    pub fn from_raw(raw: &[u8; ED25519_PRIVATE_KEY_SIZE]) -> Result<Ed25519PrivateKey, Error> {
261        Self::from_raw_impl(raw, FromRawValidationMethod::Ed25519Dalek)
262    }
263
264    fn from_key_blob_impl(
265        key_blob: &str,
266        method: FromRawValidationMethod,
267    ) -> Result<Ed25519PrivateKey, Error> {
268        if key_blob.len() != ED25519_PRIVATE_KEY_KEYBLOB_LENGTH {
269            return Err(Error::ParseError(format!(
270                "expects string of length '{}'; received string with length '{}'",
271                ED25519_PRIVATE_KEY_KEYBLOB_LENGTH,
272                key_blob.len()
273            )));
274        }
275
276        if !key_blob.starts_with(ED25519_PRIVATE_KEY_KEYBLOB_HEADER) {
277            return Err(Error::ParseError(format!(
278                "expects string that begins with '{}'; received '{}'",
279                &ED25519_PRIVATE_KEY_KEYBLOB_HEADER, &key_blob
280            )));
281        }
282
283        let base64_key: &str = &key_blob[ED25519_PRIVATE_KEY_KEYBLOB_HEADER.len()..];
284        let private_key_data = match BASE64.decode(base64_key.as_bytes()) {
285            Ok(private_key_data) => private_key_data,
286            Err(_) => {
287                return Err(Error::ParseError(format!(
288                    "could not parse '{}' as base64",
289                    base64_key
290                )))
291            }
292        };
293        let private_key_data_len = private_key_data.len();
294        let private_key_data_raw: [u8; ED25519_PRIVATE_KEY_SIZE] = match private_key_data.try_into()
295        {
296            Ok(private_key_data) => private_key_data,
297            Err(_) => {
298                return Err(Error::ParseError(format!(
299                    "expects decoded private key length '{}'; actual '{}'",
300                    ED25519_PRIVATE_KEY_SIZE, private_key_data_len
301                )))
302            }
303        };
304
305        Ed25519PrivateKey::from_raw_impl(&private_key_data_raw, method)
306    }
307
308    /// Create an `Ed25519PrivateKey` from a [`String`] in the legacy c-tor daemon key blob format used in the `ADD_ONION` control-port command. From the c-tor control [specification](https://spec.torproject.org/control-spec/commands.html#add_onion):
309    /// > For a "ED25519-V3" key is the Base64 encoding of the concatenation of the 32-byte ed25519 secret scalar in little-endian and the 32-byte ed25519 PRF secret.
310    ///
311    /// Only key blob strings created by the legacy c-tor daemon are required to convert correctly using this function. An `Ed25519PrivateKey` created using this method will seriaise to a different (but cryptographically equivalent) scalar-reduced key blob string using the [`Ed25519PrivateKey::to_key_blob()`] function.
312    #[cfg(feature = "legacy-tor-provider")]
313    pub fn from_key_blob_legacy(key_blob: &str) -> Result<Ed25519PrivateKey, Error> {
314        Self::from_key_blob_impl(key_blob, FromRawValidationMethod::LegacyCTor)
315    }
316
317    /// Create an `Ed25519PrivateKey` from a [`String`] in the legacy c-tor daemon key blob format used in the `ADD_ONION` control-port command. From the c-tor control [specification](https://spec.torproject.org/control-spec/commands.html#add_onion):
318    /// > For a "ED25519-V3" key is the Base64 encoding of the concatenation of the 32-byte ed25519 secret scalar in little-endian and the 32-byte ed25519 PRF secret.
319    ///
320    /// Only key blob strings derived from [`Ed25519PrivateKey::to_key_blob()`] are required to convert correctly using this function.
321    pub fn from_key_blob(key_blob: &str) -> Result<Ed25519PrivateKey, Error> {
322        Self::from_key_blob_impl(key_blob, FromRawValidationMethod::Ed25519Dalek)
323    }
324
325    /// Construct an `Ed25519PrivateKEy` from an [`X25519PrivateKey`].
326    pub fn from_private_x25519(
327        x25519_private: &X25519PrivateKey,
328    ) -> Result<(Ed25519PrivateKey, SignBit), Error> {
329        if let Some((result, signbit)) =
330            convert_curve25519_to_ed25519_private(&x25519_private.secret_key)
331        {
332            Ok((
333                Ed25519PrivateKey {
334                    expanded_keypair: result,
335                },
336                match signbit {
337                    0u8 => SignBit::Zero,
338                    1u8 => SignBit::One,
339                    invalid_signbit => {
340                        return Err(Error::ConversionError(format!(
341                            "convert_curve25519_to_ed25519_private() returned invalid signbit: {}",
342                            invalid_signbit
343                        )))
344                    }
345                },
346            ))
347        } else {
348            Err(Error::ConversionError(
349                "could not convert x25519 private key to ed25519 private key".to_string(),
350            ))
351        }
352    }
353
354    /// Write `Ed25519PrivateKey` to a c-tor key blob formatted [`String`].
355    pub fn to_key_blob(&self) -> String {
356        let mut key_blob = ED25519_PRIVATE_KEY_KEYBLOB_HEADER.to_string();
357        key_blob.push_str(&BASE64.encode(&self.expanded_keypair.to_secret_key_bytes()));
358
359        key_blob
360    }
361
362    /// Sign the provided message and return an [`Ed25519Signature`].
363    /// ## ⚠ Warning ⚠
364    ///Only ever sign messages the private key owner controls the contents of!
365    pub fn sign_message(&self, message: &[u8]) -> Ed25519Signature {
366        let signature = self.expanded_keypair.sign(message);
367        Ed25519Signature { signature }
368    }
369
370    /// Convert this private key to an array of bytes.
371    pub fn to_bytes(&self) -> [u8; ED25519_PRIVATE_KEY_SIZE] {
372        self.expanded_keypair.to_secret_key_bytes()
373    }
374
375    #[cfg(feature = "arti-client-tor-provider")]
376    pub(crate) fn inner(&self) -> &pk::ed25519::ExpandedKeypair {
377        &self.expanded_keypair
378    }
379}
380
381impl PartialEq for Ed25519PrivateKey {
382    fn eq(&self, other: &Self) -> bool {
383        self.to_bytes().eq(&other.to_bytes())
384    }
385}
386
387impl Clone for Ed25519PrivateKey {
388    fn clone(&self) -> Ed25519PrivateKey {
389        match Ed25519PrivateKey::from_raw(&self.to_bytes()) {
390            Ok(ed25519_private_key) => ed25519_private_key,
391            Err(_) => unreachable!(),
392        }
393    }
394}
395
396impl std::fmt::Debug for Ed25519PrivateKey {
397    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
398        write!(f, "--- ed25519 private key ---")
399    }
400}
401
402/// A wrapper around `tor_llcrypto::pk::ed25519::PublicKey`
403impl Ed25519PublicKey {
404    /// Construct an `Ed25519PublicKey` from an array of bytes. Not all byte buffers of the required size can create a valid `Ed25519PublicKey`. Only buffers derived from [`Ed25519PublicKey::as_bytes()`] are required to convert correctly.
405    pub fn from_raw(raw: &[u8; ED25519_PUBLIC_KEY_SIZE]) -> Result<Ed25519PublicKey, Error> {
406        Ok(Ed25519PublicKey {
407            public_key: match pk::ed25519::PublicKey::from_bytes(raw) {
408                Ok(public_key) => public_key,
409                Err(_) => return Err(Error::KeyInvalid),
410            },
411        })
412    }
413
414    /// Construct an `Ed25519PublicKey` from a [`V3OnionServiceId`].
415    pub fn from_service_id(service_id: &V3OnionServiceId) -> Result<Ed25519PublicKey, Error> {
416        // decode base32 encoded service id
417        let mut decoded_service_id = [0u8; V3_ONION_SERVICE_ID_RAW_SIZE];
418        let decoded_byte_count =
419            match ONION_BASE32.decode_mut(service_id.as_bytes(), &mut decoded_service_id) {
420                Ok(decoded_byte_count) => decoded_byte_count,
421                Err(_) => {
422                    return Err(Error::ConversionError(format!(
423                        "failed to decode '{}' as V3OnionServiceId",
424                        service_id
425                    )))
426                }
427            };
428        if decoded_byte_count != V3_ONION_SERVICE_ID_RAW_SIZE {
429            return Err(Error::ConversionError(format!(
430                "decoded byte count is '{}', expected '{}'",
431                decoded_byte_count, V3_ONION_SERVICE_ID_RAW_SIZE
432            )));
433        }
434
435        Ed25519PublicKey::from_raw(
436            decoded_service_id[0..ED25519_PUBLIC_KEY_SIZE]
437                .try_into()
438                .unwrap(),
439        )
440    }
441
442    /// Construct an `Ed25519PublicKey` from an [`Ed25519PrivateKey`].
443    pub fn from_private_key(private_key: &Ed25519PrivateKey) -> Ed25519PublicKey {
444        Ed25519PublicKey {
445            public_key: *private_key.expanded_keypair.public(),
446        }
447    }
448
449    fn from_public_x25519(
450        public_x25519: &X25519PublicKey,
451        signbit: SignBit,
452    ) -> Result<Ed25519PublicKey, Error> {
453        match convert_curve25519_to_ed25519_public(&public_x25519.public_key, signbit.into()) {
454            Some(public_key) => Ok(Ed25519PublicKey { public_key }),
455            None => Err(Error::ConversionError(
456                "failed to create ed25519 public key from x25519 public key and signbit"
457                    .to_string(),
458            )),
459        }
460    }
461
462    /// View this public key as an array of bytes
463    pub fn as_bytes(&self) -> &[u8; ED25519_PUBLIC_KEY_SIZE] {
464        self.public_key.as_bytes()
465    }
466}
467
468impl PartialEq for Ed25519PublicKey {
469    fn eq(&self, other: &Self) -> bool {
470        self.public_key.eq(&other.public_key)
471    }
472}
473
474impl std::fmt::Debug for Ed25519PublicKey {
475    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
476        self.public_key.fmt(f)
477    }
478}
479
480/// A wrapper around `tor_llcrypto::pk::ed25519::Signature`
481impl Ed25519Signature {
482    /// Construct an `Ed25519Signature` from an array of bytes.
483    pub fn from_raw(raw: &[u8; ED25519_SIGNATURE_SIZE]) -> Result<Ed25519Signature, Error> {
484        // todo: message cannot fail so should not return a Result<>
485        Ok(Ed25519Signature {
486            signature: pk::ed25519::Signature::from_bytes(raw),
487        })
488    }
489
490    /// Verify this `Ed25519Signature` for the given message and [`Ed25519PublicKey`].
491    pub fn verify(&self, message: &[u8], public_key: &Ed25519PublicKey) -> bool {
492        public_key
493            .public_key
494            .verify(message, &self.signature)
495            .is_ok()
496    }
497
498    /// Verify this `Ed25519Signature` for the given message, [`X25519PublicKey`], and [`SignBit`]. This signature must have been created by first converting an [`X25519PrivateKey`] to a [`Ed25519PrivateKey`] and [`SignBit`], and then signing the message using this [`Ed25519PrivateKey`]. This method verifies the signature using the [`Ed25519PublicKey`] derived from the provided  [`X25519PublicKey`] and [`SignBit`].
499    pub fn verify_x25519(
500        &self,
501        message: &[u8],
502        public_key: &X25519PublicKey,
503        signbit: SignBit,
504    ) -> bool {
505        if let Ok(public_key) = Ed25519PublicKey::from_public_x25519(public_key, signbit) {
506            return self.verify(message, &public_key);
507        }
508        false
509    }
510
511    /// Convert this signature to an array of bytes
512    pub fn to_bytes(&self) -> [u8; ED25519_SIGNATURE_SIZE] {
513        self.signature.to_bytes()
514    }
515}
516
517impl PartialEq for Ed25519Signature {
518    fn eq(&self, other: &Self) -> bool {
519        self.signature.eq(&other.signature)
520    }
521}
522
523impl std::fmt::Debug for Ed25519Signature {
524    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
525        self.signature.fmt(f)
526    }
527}
528
529/// A wrapper around `tor_llcrypto::pk::curve25519::StaticSecret`
530impl X25519PrivateKey {
531    /// Securely generate a new `X25519PrivateKey`
532    pub fn generate() -> X25519PrivateKey {
533        let csprng = &mut tor_llcrypto::rng::CautiousRng;
534        X25519PrivateKey {
535            secret_key: pk::curve25519::StaticSecret::random_from_rng(csprng),
536        }
537    }
538
539    /// Attempt to create an `X25519PrivateKey` from an array of bytes. Not all byte buffers of the required size can create a valid `X25519PrivateKey`. Only buffers derived from [`X25519PrivateKey::to_bytes()`] are required to convert correctly.
540    ///
541    /// To securely generate a valid `X25519PrivateKey`, use [`X25519PrivateKey::generate()`].
542    pub fn from_raw(raw: &[u8; X25519_PRIVATE_KEY_SIZE]) -> Result<X25519PrivateKey, Error> {
543        // see: https://docs.rs/x25519-dalek/2.0.0-pre.1/src/x25519_dalek/x25519.rs.html#197
544        if raw[0] == raw[0] & 240 && raw[31] == (raw[31] & 127) | 64 {
545            Ok(X25519PrivateKey {
546                secret_key: pk::curve25519::StaticSecret::from(*raw),
547            })
548        } else {
549            Err(Error::KeyInvalid)
550        }
551    }
552
553    /// Create an `X25519PrivateKey` from a [`String`] in the legacy c-tor daemon key blob format used in the `ONION_CLIENT_AUTH_ADD` control-port command. From the c-tor control [specification](https://spec.torproject.org/control-spec/commands.html#onion_client_auth_add):
554    /// > ```text
555    /// > PrivateKeyBlob = base64 encoding of x25519 key
556    /// > ```
557    ///
558    /// Only key blob strings derived from [`X25519PrivateKey::to_base64()`] are required to convert correctly.
559    pub fn from_base64(base64: &str) -> Result<X25519PrivateKey, Error> {
560        // todo: see if this should be from/to key blob like with ed25519 rather than base64
561        if base64.len() != X25519_PRIVATE_KEY_BASE64_LENGTH {
562            return Err(Error::ParseError(format!(
563                "expects string of length '{}'; received string with length '{}'",
564                X25519_PRIVATE_KEY_BASE64_LENGTH,
565                base64.len()
566            )));
567        }
568
569        let private_key_data = match BASE64.decode(base64.as_bytes()) {
570            Ok(private_key_data) => private_key_data,
571            Err(_) => {
572                return Err(Error::ParseError(format!(
573                    "could not parse '{}' as base64",
574                    base64
575                )))
576            }
577        };
578        let private_key_data_len = private_key_data.len();
579        let private_key_data_raw: [u8; X25519_PRIVATE_KEY_SIZE] = match private_key_data.try_into()
580        {
581            Ok(private_key_data) => private_key_data,
582            Err(_) => {
583                return Err(Error::ParseError(format!(
584                    "expects decoded private key length '{}'; actual '{}'",
585                    X25519_PRIVATE_KEY_SIZE, private_key_data_len
586                )))
587            }
588        };
589
590        X25519PrivateKey::from_raw(&private_key_data_raw)
591    }
592
593    /// Sign the provided message and return an [`Ed25519Signature`] and [`SignBit`].
594    ///
595    /// This method first converts this `X25519PrivateKey` to an [`Ed25519PrivateKey`] and [`SignBit`]. Then, the message is signed using the derived [`Ed25519PrivateKey`]. To verify the signature, both the [`X25519PublicKey`] and this calculated [`SignBit`] are required.
596    ///
597    /// ## ⚠ Warning ⚠
598    ///Only ever sign messages the private key owner controls the contents of!
599    pub fn sign_message(&self, message: &[u8]) -> Result<(Ed25519Signature, SignBit), Error> {
600        let (ed25519_private, signbit) = Ed25519PrivateKey::from_private_x25519(self)?;
601        Ok((ed25519_private.sign_message(message), signbit))
602    }
603
604    /// Write `X25519PrivateKey` to a base64 encocded [`String`].
605    pub fn to_base64(&self) -> String {
606        BASE64.encode(&self.secret_key.to_bytes())
607    }
608
609    /// Convert this private key to an array of bytes.
610    pub fn to_bytes(&self) -> [u8; X25519_PRIVATE_KEY_SIZE] {
611        self.secret_key.to_bytes()
612    }
613
614    #[cfg(feature = "arti-client-tor-provider")]
615    pub(crate) fn inner(&self) -> &pk::curve25519::StaticSecret {
616        &self.secret_key
617    }
618}
619
620impl PartialEq for X25519PrivateKey {
621    fn eq(&self, other: &Self) -> bool {
622        self.secret_key.to_bytes() == other.secret_key.to_bytes()
623    }
624}
625
626impl std::fmt::Debug for X25519PrivateKey {
627    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
628        write!(f, "--- x25519 private key ---")
629    }
630}
631
632/// A wrapper around `tor_llcrypto::pk::curve25519::PublicKey`
633impl X25519PublicKey {
634    /// Construct an `X25519PublicKey` from an [`X25519PrivateKey`].
635    pub fn from_private_key(private_key: &X25519PrivateKey) -> X25519PublicKey {
636        X25519PublicKey {
637            public_key: pk::curve25519::PublicKey::from(&private_key.secret_key),
638        }
639    }
640
641    /// Construct an `X25519PublicKey` from an array of bytes.
642    pub fn from_raw(raw: &[u8; X25519_PUBLIC_KEY_SIZE]) -> X25519PublicKey {
643        X25519PublicKey {
644            public_key: pk::curve25519::PublicKey::from(*raw),
645        }
646    }
647
648    /// Create an `X25519PublicKey` from a [`String`] in the legacy c-tor daemon key base32 format used in the `ADD_ONION` control-port command. From the c-tor control [specification](https://spec.torproject.org/control-spec/commands.html#add_onion):
649    /// > ```text
650    /// > V3Key = The client's base32-encoded x25519 public key, using only the key
651    /// >         part of rend-spec-v3.txt section G.1.2 (v3 only).
652    /// > ```
653    ///
654    /// Only key base32 strings derived from [`X25519PublicKey::to_base32()`] are required to convert correctly.
655    pub fn from_base32(base32: &str) -> Result<X25519PublicKey, Error> {
656        if base32.len() != X25519_PUBLIC_KEY_BASE32_LENGTH {
657            return Err(Error::ParseError(format!(
658                "expects string of length '{}'; received '{}' with length '{}'",
659                X25519_PUBLIC_KEY_BASE32_LENGTH,
660                base32,
661                base32.len()
662            )));
663        }
664
665        let public_key_data = match BASE32_NOPAD.decode(base32.as_bytes()) {
666            Ok(public_key_data) => public_key_data,
667            Err(_) => {
668                return Err(Error::ParseError(format!(
669                    "failed to decode '{}' as X25519PublicKey",
670                    base32
671                )))
672            }
673        };
674        let public_key_data_len = public_key_data.len();
675        let public_key_data_raw: [u8; X25519_PUBLIC_KEY_SIZE] = match public_key_data.try_into() {
676            Ok(public_key_data) => public_key_data,
677            Err(_) => {
678                return Err(Error::ParseError(format!(
679                    "expects decoded public key length '{}'; actual '{}'",
680                    X25519_PUBLIC_KEY_SIZE, public_key_data_len
681                )))
682            }
683        };
684
685        Ok(X25519PublicKey::from_raw(&public_key_data_raw))
686    }
687
688    /// Write `X25519PublicKey` to a base32 encocded [`String`].
689    pub fn to_base32(&self) -> String {
690        BASE32_NOPAD.encode(self.public_key.as_bytes())
691    }
692
693    /// View this public key as an array of bytes
694    pub fn as_bytes(&self) -> &[u8; X25519_PUBLIC_KEY_SIZE] {
695        self.public_key.as_bytes()
696    }
697
698    #[cfg(feature = "arti-client-tor-provider")]
699    pub(crate) fn inner(&self) -> &pk::curve25519::PublicKey {
700        &self.public_key
701    }
702}
703
704impl std::fmt::Debug for X25519PublicKey {
705    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
706        write!(f, "{}", self.to_base32())
707    }
708}
709
710/// Strongly-typed representation of a v3 onion-service id
711impl V3OnionServiceId {
712    // see https://github.com/torproject/torspec/blob/main/rend-spec-v3.txt#L2143
713    fn calc_truncated_checksum(
714        public_key: &[u8; ED25519_PUBLIC_KEY_SIZE],
715    ) -> [u8; TRUNCATED_CHECKSUM_SIZE] {
716        let mut hasher = Sha3_256::new();
717
718        // calculate checksum
719        hasher.update(b".onion checksum");
720        hasher.update(public_key);
721        hasher.update([0x03u8]);
722        let hash_bytes = hasher.finalize();
723
724        [hash_bytes[0], hash_bytes[1]]
725    }
726
727    /// Create a `V3OnionServiceId` from a [`String`] in the version 3 onion service digest format. From the tor address [specification](https://spec.torproject.org/address-spec.html#onion):
728    /// > ```text
729    /// > onion_address = base32(PUBKEY | CHECKSUM | VERSION)
730    /// > CHECKSUM = H(".onion checksum" | PUBKEY | VERSION)[:2]
731    /// >
732    /// > where:
733    /// > - PUBKEY is the 32 bytes ed25519 master pubkey of the onion service.
734    /// > - VERSION is a one byte version field (default value '\x03')
735    /// > - ".onion checksum" is a constant string
736    /// > - H is SHA3-256
737    /// > - CHECKSUM is truncated to two bytes before inserting it in onion_address
738    /// > ```
739    pub fn from_string(service_id: &str) -> Result<V3OnionServiceId, Error> {
740        if !V3OnionServiceId::is_valid(service_id) {
741            return Err(Error::ParseError(format!(
742                "'{}' is not a valid v3 onion service id",
743                service_id
744            )));
745        }
746        Ok(V3OnionServiceId {
747            data: service_id.as_bytes().try_into().unwrap(),
748        })
749    }
750
751    /// Create a `V3OnionServiceId` from an [`Ed25519PublicKey`].
752    pub fn from_public_key(public_key: &Ed25519PublicKey) -> V3OnionServiceId {
753        let mut raw_service_id = [0u8; V3_ONION_SERVICE_ID_RAW_SIZE];
754
755        raw_service_id[..ED25519_PUBLIC_KEY_SIZE].copy_from_slice(&public_key.as_bytes()[..]);
756        let truncated_checksum = Self::calc_truncated_checksum(public_key.as_bytes());
757        raw_service_id[V3_ONION_SERVICE_ID_CHECKSUM_OFFSET] = truncated_checksum[0];
758        raw_service_id[V3_ONION_SERVICE_ID_CHECKSUM_OFFSET + 1] = truncated_checksum[1];
759        raw_service_id[V3_ONION_SERVICE_ID_VERSION_OFFSET] = 0x03u8;
760
761        let mut service_id = [0u8; V3_ONION_SERVICE_ID_STRING_LENGTH];
762        // panics on wrong buffer size, but given our constant buffer sizes should be fine
763        ONION_BASE32.encode_mut(&raw_service_id, &mut service_id);
764
765        V3OnionServiceId { data: service_id }
766    }
767
768    /// Create a `V3OnionServiceId` from an [`Ed25519PrivateKey`].
769    pub fn from_private_key(private_key: &Ed25519PrivateKey) -> V3OnionServiceId {
770        Self::from_public_key(&Ed25519PublicKey::from_private_key(private_key))
771    }
772
773    /// Determine if the provided string is a valid representation of a `V3OnionServiceId`
774    pub fn is_valid(service_id: &str) -> bool {
775        if service_id.len() != V3_ONION_SERVICE_ID_STRING_LENGTH {
776            return false;
777        }
778
779        let mut decoded_service_id = [0u8; V3_ONION_SERVICE_ID_RAW_SIZE];
780        match ONION_BASE32.decode_mut(service_id.as_bytes(), &mut decoded_service_id) {
781            Ok(decoded_byte_count) => {
782                // ensure right size
783                if decoded_byte_count != V3_ONION_SERVICE_ID_RAW_SIZE {
784                    return false;
785                }
786                // ensure correct version
787                if decoded_service_id[V3_ONION_SERVICE_ID_VERSION_OFFSET] != 0x03 {
788                    return false;
789                }
790                // copy public key into own buffer
791                let mut public_key = [0u8; ED25519_PUBLIC_KEY_SIZE];
792                public_key[..].copy_from_slice(&decoded_service_id[..ED25519_PUBLIC_KEY_SIZE]);
793                // ensure checksum is correct
794                let truncated_checksum = Self::calc_truncated_checksum(&public_key);
795                if truncated_checksum[0] != decoded_service_id[V3_ONION_SERVICE_ID_CHECKSUM_OFFSET]
796                    || truncated_checksum[1]
797                        != decoded_service_id[V3_ONION_SERVICE_ID_CHECKSUM_OFFSET + 1]
798                {
799                    return false;
800                }
801                true
802            }
803            Err(_) => false,
804        }
805    }
806
807    /// View this service id as an array of bytes
808    pub fn as_bytes(&self) -> &[u8; V3_ONION_SERVICE_ID_STRING_LENGTH] {
809        &self.data
810    }
811}
812
813impl std::fmt::Display for V3OnionServiceId {
814    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
815        unsafe { write!(f, "{}", str::from_utf8_unchecked(&self.data)) }
816    }
817}
818
819impl std::fmt::Debug for V3OnionServiceId {
820    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
821        unsafe { write!(f, "{}", str::from_utf8_unchecked(&self.data)) }
822    }
823}
tor_interface/tor_crypto.rs

tor_interface/
tor_crypto.rs
