Skip to main content

arweave_keygen/
lib.rs

1//! Generate and inspect Arweave JWK wallets.
2//!
3//! An Arweave wallet is an RSA-4096 key pair stored as a JSON Web Key (JWK).
4//! The public exponent must be 65537. The wallet address is
5//! `base64url(SHA-256(n))`, where `n` is the RSA modulus.
6
7use base64::engine::general_purpose::URL_SAFE_NO_PAD;
8use base64::Engine;
9use num_bigint_dig::prime::probably_prime;
10use rsa::traits::{PrivateKeyParts, PublicKeyParts};
11use rsa::{BigUint, RsaPrivateKey};
12use serde::{Deserialize, Serialize};
13use sha2::{Digest, Sha256};
14
15/// RSA modulus size required by Arweave.
16pub const KEY_BITS: usize = 4096;
17
18/// Public exponent required by Arweave (`65537`, JWK `e` = `"AQAB"`).
19pub const PUBLIC_EXPONENT: u64 = 65537;
20
21/// Arweave RSA private key in JWK form (RFC 7517 / RFC 7518).
22///
23/// Field order matches the canonical Arweave keyfile shape.
24#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
25pub struct Jwk {
26    pub kty: String,
27    pub e: String,
28    pub n: String,
29    pub d: String,
30    pub p: String,
31    pub q: String,
32    pub dp: String,
33    pub dq: String,
34    pub qi: String,
35}
36
37impl std::fmt::Debug for Jwk {
38    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
39        f.debug_struct("Jwk")
40            .field("kty", &self.kty)
41            .field("e", &self.e)
42            .field("n", &self.n)
43            .field("d", &"[REDACTED]")
44            .field("p", &"[REDACTED]")
45            .field("q", &"[REDACTED]")
46            .field("dp", &"[REDACTED]")
47            .field("dq", &"[REDACTED]")
48            .field("qi", &"[REDACTED]")
49            .finish()
50    }
51}
52
53/// A generated Arweave wallet: address plus JWK private key.
54#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
55pub struct Wallet {
56    pub address: String,
57    pub jwk: Jwk,
58}
59
60#[derive(Debug)]
61pub enum Error {
62    Rsa(rsa::Error),
63    Base64(base64::DecodeError),
64    Json(serde_json::Error),
65    InvalidKey(&'static str),
66}
67
68impl std::fmt::Display for Error {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        match self {
71            Error::Rsa(err) => write!(f, "RSA error: {err}"),
72            Error::Base64(err) => write!(f, "base64url error: {err}"),
73            Error::Json(err) => write!(f, "JSON error: {err}"),
74            Error::InvalidKey(msg) => write!(f, "invalid Arweave JWK: {msg}"),
75        }
76    }
77}
78
79impl std::error::Error for Error {}
80
81impl From<rsa::Error> for Error {
82    fn from(err: rsa::Error) -> Self {
83        Error::Rsa(err)
84    }
85}
86
87impl From<base64::DecodeError> for Error {
88    fn from(err: base64::DecodeError) -> Self {
89        Error::Base64(err)
90    }
91}
92
93impl From<serde_json::Error> for Error {
94    fn from(err: serde_json::Error) -> Self {
95        Error::Json(err)
96    }
97}
98
99impl Wallet {
100    /// Generate a new random Arweave wallet (RSA-4096, `e` = 65537).
101    ///
102    /// This typically takes 1–5 seconds.
103    pub fn generate() -> Result<Self, Error> {
104        let mut rng = rand::thread_rng();
105        let exp = BigUint::from(PUBLIC_EXPONENT);
106        let key = RsaPrivateKey::new_with_exp(&mut rng, KEY_BITS, &exp)?;
107        Self::from_rsa(key)
108    }
109
110    /// Parse a JWK JSON string and derive the wallet address.
111    pub fn from_jwk_json(json: &str) -> Result<Self, Error> {
112        let jwk: Jwk = serde_json::from_str(json)?;
113        Self::from_jwk(jwk)
114    }
115
116    /// Validate a JWK and derive its Arweave address.
117    pub fn from_jwk(jwk: Jwk) -> Result<Self, Error> {
118        if jwk.kty != "RSA" {
119            return Err(Error::InvalidKey("kty must be RSA"));
120        }
121        if jwk.e != "AQAB" {
122            return Err(Error::InvalidKey("public exponent e must be 65537 (AQAB)"));
123        }
124        let n = decode_jwk_integer(&jwk.n)?;
125        if n.bits() != KEY_BITS {
126            return Err(Error::InvalidKey("modulus must be 4096 bits"));
127        }
128        let d = decode_jwk_integer(&jwk.d)?;
129        let p = decode_jwk_integer(&jwk.p)?;
130        let q = decode_jwk_integer(&jwk.q)?;
131        let dp = decode_jwk_integer(&jwk.dp)?;
132        let dq = decode_jwk_integer(&jwk.dq)?;
133        let qi = decode_jwk_integer(&jwk.qi)?;
134        let one = BigUint::from(1u8);
135        let two = BigUint::from(2u8);
136        if d >= n || p <= two || q <= two || p == q || &p % &two != one || &q % &two != one {
137            return Err(Error::InvalidKey("invalid private RSA components"));
138        }
139        // from_components checks n = p*q and CRT relations, not primality.
140        if !probably_prime(&p, 20) || !probably_prime(&q, 20) {
141            return Err(Error::InvalidKey("RSA factors p and q must be prime"));
142        }
143        let key = RsaPrivateKey::from_components(n, BigUint::from(PUBLIC_EXPONENT), d, vec![p, q])?;
144        if key.dp() != Some(&dp)
145            || key.dq() != Some(&dq)
146            || key.crt_coefficient().as_ref() != Some(&qi)
147        {
148            return Err(Error::InvalidKey("CRT fields do not match the private key"));
149        }
150        let address = address_from_n(&jwk.n)?;
151        Ok(Self { address, jwk })
152    }
153
154    fn from_rsa(mut key: RsaPrivateKey) -> Result<Self, Error> {
155        key.precompute()?;
156
157        if key.n().bits() != KEY_BITS {
158            return Err(Error::InvalidKey("modulus must be 4096 bits"));
159        }
160        if key.e() != &BigUint::from(PUBLIC_EXPONENT) {
161            return Err(Error::InvalidKey("public exponent e must be 65537"));
162        }
163
164        let primes = key.primes();
165        if primes.len() < 2 {
166            return Err(Error::InvalidKey("RSA key is missing prime factors"));
167        }
168
169        let n = key.n();
170        let d = key.d();
171        let p = &primes[0];
172        let q = &primes[1];
173        let one = BigUint::from(1u8);
174        let two = BigUint::from(2u8);
175
176        let dp = key.dp().cloned().unwrap_or_else(|| d % (p - &one));
177        let dq = key.dq().cloned().unwrap_or_else(|| d % (q - &one));
178        // qi = q^{-1} mod p. For prime p this equals q^{p-2} mod p.
179        let qi = key
180            .crt_coefficient()
181            .unwrap_or_else(|| q.modpow(&(p - &two), p));
182
183        let jwk = Jwk {
184            kty: "RSA".to_string(),
185            e: b64url_encode(&key.e().to_bytes_be()),
186            n: b64url_encode(&n.to_bytes_be()),
187            d: b64url_encode(&d.to_bytes_be()),
188            p: b64url_encode(&p.to_bytes_be()),
189            q: b64url_encode(&q.to_bytes_be()),
190            dp: b64url_encode(&dp.to_bytes_be()),
191            dq: b64url_encode(&dq.to_bytes_be()),
192            qi: b64url_encode(&qi.to_bytes_be()),
193        };
194
195        let address = address_from_n(&jwk.n)?;
196        Ok(Self { address, jwk })
197    }
198
199    /// Pretty-printed JWK JSON, the usual Arweave keyfile contents.
200    pub fn to_jwk_json(&self) -> Result<String, Error> {
201        Ok(serde_json::to_string_pretty(&self.jwk)?)
202    }
203
204    /// Pretty-printed wallet JSON: `address` plus the JWK private key.
205    pub fn to_json(&self) -> Result<String, Error> {
206        Ok(serde_json::to_string_pretty(self)?)
207    }
208
209    /// Default keyfile name used by Arweave tooling.
210    pub fn default_filename(&self) -> String {
211        format!("arweave-keyfile-{}.json", self.address)
212    }
213}
214
215/// Base64URL-encode bytes without padding.
216pub fn b64url_encode(bytes: &[u8]) -> String {
217    URL_SAFE_NO_PAD.encode(bytes)
218}
219
220/// Base64URL-decode a string without padding.
221pub fn b64url_decode(value: &str) -> Result<Vec<u8>, Error> {
222    URL_SAFE_NO_PAD.decode(value).map_err(Error::from)
223}
224
225fn decode_jwk_integer(value: &str) -> Result<BigUint, Error> {
226    // Bound decoding and RSA arithmetic to the supported modulus size.
227    if value.len() > (KEY_BITS / 8 * 4).div_ceil(3) {
228        return Err(Error::InvalidKey("RSA component exceeds 4096 bits"));
229    }
230    let bytes = b64url_decode(value)?;
231    if bytes.is_empty() || bytes[0] == 0 {
232        return Err(Error::InvalidKey(
233            "RSA components must be positive, minimally encoded integers",
234        ));
235    }
236    Ok(BigUint::from_bytes_be(&bytes))
237}
238
239/// Wallet address from the JWK `n` field: `base64url(SHA-256(decode(n)))`.
240pub fn address_from_n(n_b64url: &str) -> Result<String, Error> {
241    let n = b64url_decode(n_b64url)?;
242    Ok(address_from_n_bytes(&n))
243}
244
245/// Wallet address from the raw RSA modulus bytes.
246pub fn address_from_n_bytes(n: &[u8]) -> String {
247    let digest = Sha256::digest(n);
248    b64url_encode(&digest)
249}
250
251#[cfg(test)]
252mod tests {
253    use super::*;
254
255    // Official sample from the Arweave HTTP API docs.
256    const SAMPLE_N: &str = "ovFF6EbOtXeg7VnojIgtChgxfU6GZ16JjVj5JFHh6NGHJnq4p059BnMphcDx1mqb3yxM73FxhEszSFLcJiPzway6eIDiXuYiT-Sf_0Wl6_wDLvEmlz43psp7WYJumwpaSyiI_1FWmOVQnTnoAIKaOYKVqzUlteiECQj7XjJl0MZH16RlEfVqVpJ_8Ier4_QXIJ8Y3pe2KF3Lg9UANFU97nuvEM94CSzX-0WIju6Lykt3DBb2YtFFg4bJjOFv3T38nCZmDh8lYjm25_1qILalsB0XRoDxQy9FLxWb4zd09JsDhL0EYAQ_hNfOnQFVOBtYEHVYMCHYH6GoTcNgxmUkZPk4AfpAqZmjDzKfVJrw4Fr68pPTEQOQEzBcIWp61P21BSkhqO4QuFinkQsSH6NdTB_3FpbhYf34Hjf-iH7hdpdWo4aoRLb8eZeZcqBRZoRmlhQnOD-PVxQR_vb9rjXSjGkCWwRbsurVLWdBh_FQn0S9Q6EHqiV8nbW-R0Rk2E76JwgMFkqGUtZj8DeEqXJ2jlAvuzp56fXeAViPEtvUj1HheO8O3LxdVYCiapWWKq4qQVoRzdiyvydYSmbztgFUhekvmjNkxLNKOh71i3hFtoXycegqZ6izrUGoF2oD24lsTKsV5lV5pwfmUjVvxtHZm54bJIMfUDYbOV6yeDjYBb8";
257    const SAMPLE_ADDRESS: &str = "GRQ7swQO1AMyFgnuAPI7AvGQlW3lzuQuwlJbIpWV7xk";
258
259    #[test]
260    fn sample_n_hashes_to_documented_address() {
261        assert_eq!(address_from_n(SAMPLE_N).unwrap(), SAMPLE_ADDRESS);
262        assert_eq!(SAMPLE_ADDRESS.len(), 43);
263    }
264
265    #[test]
266    fn exponent_65537_encodes_as_aqab() {
267        let e = BigUint::from(PUBLIC_EXPONENT);
268        assert_eq!(b64url_encode(&e.to_bytes_be()), "AQAB");
269    }
270
271    fn jwk_int(value: &str) -> BigUint {
272        BigUint::from_bytes_be(&b64url_decode(value).unwrap())
273    }
274
275    fn sample_wallet() -> Wallet {
276        static WALLET: std::sync::OnceLock<Wallet> = std::sync::OnceLock::new();
277        WALLET
278            .get_or_init(|| Wallet::generate().expect("RSA-4096 keygen"))
279            .clone()
280    }
281
282    #[test]
283    fn rejects_corrupt_import_components() {
284        let wallet = sample_wallet();
285        let original = serde_json::to_value(&wallet.jwk).unwrap();
286        for field in ["n", "d", "p", "q", "dp", "dq", "qi"] {
287            for invalid in ["", "!", "AA", "AQ", "Ag", "AQI=", "AAE"] {
288                let mut value = original.clone();
289                value[field] = invalid.into();
290                assert!(
291                    Wallet::from_jwk_json(&value.to_string()).is_err(),
292                    "accepted {field}={invalid}"
293                );
294            }
295            let mut value = original.clone();
296            let changed = jwk_int(original[field].as_str().unwrap()) + BigUint::from(2u8);
297            value[field] = b64url_encode(&changed.to_bytes_be()).into();
298            assert!(
299                Wallet::from_jwk_json(&value.to_string()).is_err(),
300                "accepted inconsistent {field}"
301            );
302        }
303        let mut jwk = wallet.jwk.clone();
304        jwk.e = "Aw".into();
305        assert!(Wallet::from_jwk(jwk).is_err());
306        let mut jwk = wallet.jwk.clone();
307        jwk.p = jwk.q.clone();
308        assert!(Wallet::from_jwk(jwk).is_err());
309        let mut jwk = wallet.jwk;
310        jwk.d = "A".repeat(684);
311        assert!(Wallet::from_jwk(jwk).is_err());
312    }
313
314    fn gcd(mut a: BigUint, mut b: BigUint) -> BigUint {
315        let zero = BigUint::from(0u8);
316        while b != zero {
317            let r = &a % &b;
318            a = b;
319            b = r;
320        }
321        a
322    }
323
324    /// Composite p, q with matching n, d and CRT fields so the old import
325    /// checks would accept the key.
326    fn composite_jwk() -> Jwk {
327        use num_bigint_dig::traits::ModInverse;
328
329        let e = BigUint::from(PUBLIC_EXPONENT);
330        let zero = BigUint::from(0u8);
331        for p_shift in 2040..=2050 {
332            for q_shift in 2040..=2050 {
333                for p_add in 1u32..30 {
334                    for q_add in 1u32..30 {
335                        if p_add % 2 == 0 || q_add % 2 == 0 {
336                            continue;
337                        }
338                        let p = BigUint::from(9u8)
339                            * ((BigUint::from(1u8) << p_shift) + BigUint::from(p_add));
340                        let q = BigUint::from(25u8)
341                            * ((BigUint::from(1u8) << q_shift) + BigUint::from(q_add));
342                        if p == q {
343                            continue;
344                        }
345                        let n = &p * &q;
346                        if n.bits() != KEY_BITS {
347                            continue;
348                        }
349                        let pm1 = &p - 1u8;
350                        let qm1 = &q - 1u8;
351                        if &pm1 % &e == zero || &qm1 % &e == zero {
352                            continue;
353                        }
354                        let g = gcd(pm1.clone(), qm1.clone());
355                        let lambda = &pm1 / g * &qm1;
356                        let Some(d) = e.clone().mod_inverse(&lambda).and_then(|v| v.to_biguint())
357                        else {
358                            continue;
359                        };
360                        let Some(qi) = q.clone().mod_inverse(&p).and_then(|v| v.to_biguint())
361                        else {
362                            continue;
363                        };
364                        let dp = &d % &pm1;
365                        let dq = &d % &qm1;
366                        return Jwk {
367                            kty: "RSA".into(),
368                            e: "AQAB".into(),
369                            n: b64url_encode(&n.to_bytes_be()),
370                            d: b64url_encode(&d.to_bytes_be()),
371                            p: b64url_encode(&p.to_bytes_be()),
372                            q: b64url_encode(&q.to_bytes_be()),
373                            dp: b64url_encode(&dp.to_bytes_be()),
374                            dq: b64url_encode(&dq.to_bytes_be()),
375                            qi: b64url_encode(&qi.to_bytes_be()),
376                        };
377                    }
378                }
379            }
380        }
381        panic!("failed to construct a 4096-bit composite RSA JWK");
382    }
383
384    #[test]
385    fn rejects_composite_import_factors() {
386        let err = Wallet::from_jwk(composite_jwk()).unwrap_err();
387        assert!(err.to_string().contains("prime"), "unexpected error: {err}");
388    }
389
390    #[test]
391    fn debug_redacts_private_components() {
392        let wallet = sample_wallet();
393        for output in [
394            format!("{:?}", wallet.jwk),
395            format!("{:#?}", wallet.jwk),
396            format!("{:?}", wallet),
397            format!("{:#?}", wallet),
398        ] {
399            for secret in [
400                &wallet.jwk.d,
401                &wallet.jwk.p,
402                &wallet.jwk.q,
403                &wallet.jwk.dp,
404                &wallet.jwk.dq,
405                &wallet.jwk.qi,
406            ] {
407                assert!(!output.contains(secret));
408            }
409            assert!(output.contains("[REDACTED]"));
410        }
411    }
412
413    #[test]
414    fn base64_requires_no_padding() {
415        assert_eq!(b64url_decode("AQI").unwrap(), vec![1, 2]);
416        assert!(b64url_decode("AQI=").is_err());
417    }
418
419    #[test]
420    fn generate_wallet_is_valid_arweave_jwk() {
421        let wallet = sample_wallet();
422
423        assert_eq!(wallet.jwk.kty, "RSA");
424        assert_eq!(wallet.jwk.e, "AQAB");
425        assert_eq!(wallet.address.len(), 43);
426        assert_eq!(address_from_n(&wallet.jwk.n).unwrap(), wallet.address);
427
428        let n = jwk_int(&wallet.jwk.n);
429        let e = jwk_int(&wallet.jwk.e);
430        let d = jwk_int(&wallet.jwk.d);
431        let p = jwk_int(&wallet.jwk.p);
432        let q = jwk_int(&wallet.jwk.q);
433        let dp = jwk_int(&wallet.jwk.dp);
434        let dq = jwk_int(&wallet.jwk.dq);
435        let qi = jwk_int(&wallet.jwk.qi);
436        let one = BigUint::from(1u8);
437
438        assert_eq!(n.bits(), KEY_BITS);
439        assert_eq!(n, &p * &q);
440        assert_eq!(e, BigUint::from(PUBLIC_EXPONENT));
441        assert_eq!(dp, &d % (&p - &one));
442        assert_eq!(dq, &d % (&q - &one));
443        assert_eq!((&q * &qi) % &p, one);
444
445        RsaPrivateKey::from_components(n, e, d, vec![p, q])
446            .unwrap()
447            .validate()
448            .unwrap();
449
450        let json = wallet.to_jwk_json().unwrap();
451        let reloaded = Wallet::from_jwk_json(&json).unwrap();
452        assert_eq!(reloaded.address, wallet.address);
453        assert_eq!(reloaded.jwk, wallet.jwk);
454
455        let wallet_json: serde_json::Value =
456            serde_json::from_str(&wallet.to_json().unwrap()).unwrap();
457        assert_eq!(wallet_json["address"], wallet.address);
458        assert_eq!(wallet_json["jwk"]["kty"], "RSA");
459        assert_eq!(wallet_json["jwk"]["e"], "AQAB");
460        assert_eq!(
461            wallet.default_filename(),
462            format!("arweave-keyfile-{}.json", wallet.address)
463        );
464    }
465
466    #[test]
467    fn rejects_non_rsa_kty() {
468        let err = Wallet::from_jwk(Jwk {
469            kty: "EC".into(),
470            e: "AQAB".into(),
471            n: SAMPLE_N.into(),
472            d: "x".into(),
473            p: "x".into(),
474            q: "x".into(),
475            dp: "x".into(),
476            dq: "x".into(),
477            qi: "x".into(),
478        })
479        .unwrap_err();
480        assert!(err.to_string().contains("RSA"));
481    }
482}