cert.rs 93.4%

170 of 182 lines run, 20 of 40 functions · run #308 on main · run missed

//! Certificates for short-lived keys (spec §14.7, oxygenhub#241,
//! oxygenhub docs/keyless.md). An issuer, a hub's key, binds a fresh key
//! to the identity that proved itself (an OIDC subject) for minutes: a Flow
//! job or an agent signs with that key and throws it away. The certificate
//! is signed with the issuer's composite key, so it is post-quantum like
//! every other signature in Oxygen.
//!
//! Whether to trust an issuer, and for which subjects, is the trust
//! policy's (§14.5); whether a signature was made inside the certificate's
//! window needs time the signer does not choose, which the caller passes
//! in (a host's acceptance now, the transparency log's later).

use crate::cbor::{self, Value};
use crate::hash::{hash_object, KeyId, ObjectRef, ObjectType};
use crate::identity::{verify, Domain, Identity, Scope, SecretKey, Signature};
use crate::objects::{array, bytes, check_version, field, map, oref, text, uint, ObjectError};

/// The longest a certificate may be valid. Jobs get ten minutes; an hour
/// leaves room for an issuer that rounds up, and no more.
pub const MAX_LIFETIME_MS: u64 = 60 * 60 * 1000;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Certificate {
    /// The short-lived key's public identity.
    pub key: Identity,
    /// The issuer's KeyId (a hub's key).
    pub issuer: KeyId,
    /// Who proved it: `repo:OWNER/NAME:bookmark:B`, `agent:NAME@ACCOUNT`.
    pub subject: String,
    /// What else the proof said (environment, run, job), sorted by name.
    pub claims: Vec<(String, String)>,
    /// What the key may sign: changes, refs, seals.
    pub scope: Scope,
    /// Valid from and until, in wall milliseconds.
    pub not_before: u64,
    pub expires: u64,
}

impl Certificate {
    pub fn to_value(&self) -> Value {
        let mut claims = self.claims.clone();
        claims.sort();
        Value::map([
            (0, Value::Uint(1)),
            (1, Value::Bytes(self.key.encode())),
            (2, Value::Bytes(self.issuer.0.to_vec())),
            (3, Value::Text(self.subject.clone())),
            (
                4,
                Value::Array(
                    claims
                        .into_iter()
                        .map(|(k, v)| Value::Array(vec![Value::Text(k), Value::Text(v)]))
                        .collect(),
                ),
            ),
            (
                5,
                Value::Array(
                    self.scope
                        .names()
                        .into_iter()
                        .map(|n| Value::Text(n.to_string()))
                        .collect(),
                ),
            ),
            (6, Value::Uint(self.not_before)),
            (7, Value::Uint(self.expires)),
        ])
    }

    pub fn encode(&self) -> Vec<u8> {
        cbor::encode(&self.to_value())
    }

    pub fn hash(&self) -> ObjectRef {
        hash_object(ObjectType::Certificate, &self.encode())
    }

    /// The short-lived key's KeyId: what its signatures name.
    pub fn key_id(&self) -> KeyId {
        self.key.hash()
    }

    pub fn decode(b: &[u8]) -> Result<Certificate, ObjectError> {
        let v = cbor::decode(b)?;
        let m = map(&v, "certificate")?;
        check_version(m)?;
        let key = Identity::decode(bytes(field(m, 1, "key")?, "key")?)?;
        let mut claims = Vec::new();
        for c in array(field(m, 4, "claims")?, "claims")? {
            let pair = array(c, "claim")?;
            if pair.len() != 2 {
                return Err(ObjectError::Schema("claim: expected [name, value]".into()));
            }
            claims.push((
                text(&pair[0], "claim name")?.to_owned(),
                text(&pair[1], "claim value")?.to_owned(),
            ));
        }
        let mut scope = Scope::NONE;
        for n in array(field(m, 5, "scope")?, "scope")? {
            let n = text(n, "scope")?;
            scope = scope
                | Scope::named(n).ok_or_else(|| {
                    ObjectError::Schema(format!("certificate: unknown scope {n:?}"))
                })?;
        }
        Ok(Certificate {
            key,
            issuer: oref(field(m, 2, "issuer")?, "issuer")?,
            subject: text(field(m, 3, "subject")?, "subject")?.to_owned(),
            claims,
            scope,
            not_before: uint(field(m, 6, "not_before")?, "not_before")?,
            expires: uint(field(m, 7, "expires")?, "expires")?,
        })
    }

    /// Whether the key may sign within `scope` at `at_ms`, a time the
    /// signer did not choose.
    pub fn covers(&self, scope: Scope, at_ms: u64) -> bool {
        !scope.is_empty()
            && self.scope.has(scope)
            && self.not_before <= at_ms
            && at_ms <= self.expires
    }

    /// The claim called `name`, if the certificate has one.
    pub fn claim(&self, name: &str) -> Option<&str> {
        self.claims
            .iter()
            .find(|(k, _)| k == name)
            .map(|(_, v)| v.as_str())
    }
}

#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum CertError {
    #[error("the certificate names issuer {0}, not this one")]
    WrongIssuer(String),
    #[error("the issuer's signature does not verify: {0}")]
    BadSignature(String),
    #[error("the certificate is valid for no time, or for longer than an hour")]
    BadLifetime,
    #[error("the certificate gives no scope")]
    NoScope,
    #[error("{0}")]
    Schema(String),
}

impl From<ObjectError> for CertError {
    fn from(e: ObjectError) -> Self {
        CertError::Schema(e.to_string())
    }
}

/// A certificate with its issuer's signature over its ObjectRef.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SignedCertificate {
    pub cert: Certificate,
    pub sig: Signature,
}

impl SignedCertificate {
    /// Issue `cert`, signed by the issuer `issuer` holds the secret of.
    pub fn sign(mut cert: Certificate, issuer: &Identity, sk: &SecretKey) -> SignedCertificate {
        // Claims in their canonical order, as encoded.
        cert.claims.sort();
        let sig = sk.sign(Domain::Certificate, &issuer.hash(), &cert.hash());
        SignedCertificate { cert, sig }
    }

    /// Signed by `issuer`, which it names, and well formed. Whether to
    /// trust the issuer for its subject is the policy's question.
    pub fn verify(&self, issuer: &Identity) -> Result<(), CertError> {
        let c = &self.cert;
        if issuer.hash() != c.issuer || self.sig.key != c.issuer {
            return Err(CertError::WrongIssuer(c.issuer.short(12)));
        }
        verify(issuer, &self.sig, Domain::Certificate, &c.hash())
            .map_err(|e| CertError::BadSignature(e.to_string()))?;
        if c.expires <= c.not_before || c.expires - c.not_before > MAX_LIFETIME_MS {
            return Err(CertError::BadLifetime);
        }
        if c.scope.is_empty() {
            return Err(CertError::NoScope);
        }
        Ok(())
    }

    /// `[certificate bytes, signature]`.
    pub fn encode(&self) -> Vec<u8> {
        cbor::encode(&Value::Array(vec![
            Value::Bytes(self.cert.encode()),
            self.sig.to_value(),
        ]))
    }

    pub fn decode(b: &[u8]) -> Result<SignedCertificate, CertError> {
        let v = cbor::decode(b).map_err(ObjectError::from)?;
        let a = array(&v, "signed certificate")?;
        if a.len() != 2 {
            return Err(CertError::Schema(
                "signed certificate: expected [certificate, signature]".into(),
            ));
        }
        Ok(SignedCertificate {
            cert: Certificate::decode(bytes(&a[0], "certificate")?)?,
            sig: Signature::from_value(&a[1])?,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn issue(
        issuer_sk: &SecretKey,
        issuer: &Identity,
        minutes: u64,
    ) -> (SecretKey, SignedCertificate) {
        let job_sk = SecretKey::generate();
        let cert = Certificate {
            key: job_sk.identity("job 12 build", "[email protected]", 1_000),
            issuer: issuer.hash(),
            subject: "repo:andy/demo:bookmark:main".into(),
            claims: vec![
                ("run".into(), "12".into()),
                ("environment".into(), "prod".into()),
            ],
            scope: Scope::CHANGES | Scope::REFS,
            not_before: 1_000,
            expires: 1_000 + minutes * 60_000,
        };
        (job_sk, SignedCertificate::sign(cert, issuer, issuer_sk))
    }

    #[test]
    fn a_certificate_round_trips_and_verifies_with_its_issuer_only() {
        let hub_sk = SecretKey::generate();
        let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
        let (_, sc) = issue(&hub_sk, &hub, 10);
        let back = SignedCertificate::decode(&sc.encode()).unwrap();
        assert_eq!(back, sc);
        assert_eq!(back.cert.claims[0].0, "environment", "claims kept sorted");
        assert_eq!(back.cert.claim("run"), Some("12"));
        assert!(back.verify(&hub).is_ok());
        let other_sk = SecretKey::generate();
        let other = other_sk.identity("elsewhere", "[email protected]", 1);
        assert!(matches!(
            back.verify(&other),
            Err(CertError::WrongIssuer(_))
        ));
        // Changed after signing: the signature no longer covers it.
        let mut forged = back.clone();
        forged.cert.subject = "repo:andy/demo:bookmark:release".into();
        assert!(matches!(
            forged.verify(&hub),
            Err(CertError::BadSignature(_))
        ));
        // Signed by another key in the issuer's name.
        let mut stolen = back.clone();
        stolen.sig = other_sk.sign(Domain::Certificate, &hub.hash(), &back.cert.hash());
        assert!(matches!(
            stolen.verify(&hub),
            Err(CertError::BadSignature(_))
        ));
    }

    #[test]
    fn it_covers_its_scope_and_window_only() {
        let hub_sk = SecretKey::generate();
        let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
        let (_, sc) = issue(&hub_sk, &hub, 10);
        let c = &sc.cert;
        assert!(c.covers(Scope::CHANGES, 1_000) && c.covers(Scope::REFS, 1_000 + 10 * 60_000));
        assert!(!c.covers(Scope::SEAL, 2_000), "not a scope it gives");
        assert!(!c.covers(Scope::CHANGES, 999), "before it");
        assert!(
            !c.covers(Scope::CHANGES, 1_000 + 10 * 60_000 + 1),
            "after it"
        );
        assert!(!c.covers(Scope::NONE, 2_000));
        let (_, long) = issue(&hub_sk, &hub, 61);
        assert_eq!(long.verify(&hub), Err(CertError::BadLifetime));
    }

    #[test]
    fn a_signature_by_the_short_lived_key_names_it() {
        let hub_sk = SecretKey::generate();
        let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
        let (job_sk, sc) = issue(&hub_sk, &hub, 10);
        let target = ObjectRef([5; 32]);
        let sig = job_sk.sign(Domain::Change, &sc.cert.key_id(), &target);
        assert_eq!(sig.key, sc.cert.key_id());
        assert!(verify(&sc.cert.key, &sig, Domain::Change, &target).is_ok());
    }
}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1		//! Certificates for short-lived keys (spec §14.7, oxygenhub#241,
2		//! oxygenhub docs/keyless.md). An issuer, a hub's key, binds a fresh key
3		//! to the identity that proved itself (an OIDC subject) for minutes: a Flow
4		//! job or an agent signs with that key and throws it away. The certificate
5		//! is signed with the issuer's composite key, so it is post-quantum like
6		//! every other signature in Oxygen.
7		//!
8		//! Whether to trust an issuer, and for which subjects, is the trust
9		//! policy's (§14.5); whether a signature was made inside the certificate's
10		//! window needs time the signer does not choose, which the caller passes
11		//! in (a host's acceptance now, the transparency log's later).
12
13		use crate::cbor::{self, Value};
14		use crate::hash::{hash_object, KeyId, ObjectRef, ObjectType};
15		use crate::identity::{verify, Domain, Identity, Scope, SecretKey, Signature};
16		use crate::objects::{array, bytes, check_version, field, map, oref, text, uint, ObjectError};
17
18		/// The longest a certificate may be valid. Jobs get ten minutes; an hour
19		/// leaves room for an issuer that rounds up, and no more.
20		pub const MAX_LIFETIME_MS: u64 = 60 * 60 * 1000;
21
22		#[derive(Clone, Debug, PartialEq, Eq)]
23		pub struct Certificate {
24		/// The short-lived key's public identity.
25		pub key: Identity,
26		/// The issuer's KeyId (a hub's key).
27		pub issuer: KeyId,
28		/// Who proved it: `repo:OWNER/NAME:bookmark:B`, `agent:NAME@ACCOUNT`.
29		pub subject: String,
30		/// What else the proof said (environment, run, job), sorted by name.
31		pub claims: Vec<(String, String)>,
32		/// What the key may sign: changes, refs, seals.
33		pub scope: Scope,
34		/// Valid from and until, in wall milliseconds.
35		pub not_before: u64,
36		pub expires: u64,
37		}
38
39		impl Certificate {
40	10×	pub fn to_value(&self) -> Value {
41	10×	let mut claims = self.claims.clone();
42	10×	claims.sort();
43	10×	Value::map([
44	10×	(0, Value::Uint(1)),
45	10×	(1, Value::Bytes(self.key.encode())),
46	10×	(2, Value::Bytes(self.issuer.0.to_vec())),
47	10×	(3, Value::Text(self.subject.clone())),
48		(
49		4,
50		Value::Array(
51	10×	claims
52	10×	.into_iter()
53	20×	.map(\|(k, v)\| Value::Array(vec![Value::Text(k), Value::Text(v)]))
54	10×	.collect(),
55		),
56		),
57		(
58		5,
59		Value::Array(
60	10×	self.scope
61	10×	.names()
62	10×	.into_iter()
63	20×	.map(\|n\| Value::Text(n.to_string()))
64	10×	.collect(),
65		),
66		),
67	10×	(6, Value::Uint(self.not_before)),
68	10×	(7, Value::Uint(self.expires)),
69		])
70	10×	}
71
72	10×	pub fn encode(&self) -> Vec<u8> {
73	10×	cbor::encode(&self.to_value())
74	10×	}
75
76	9×	pub fn hash(&self) -> ObjectRef {
77	9×	hash_object(ObjectType::Certificate, &self.encode())
78	9×	}
79
80		/// The short-lived key's KeyId: what its signatures name.
81	2×	pub fn key_id(&self) -> KeyId {
82	2×	self.key.hash()
83	2×	}
84
85	1×	pub fn decode(b: &[u8]) -> Result<Certificate, ObjectError> {
86	1×	let v = cbor::decode(b)?;
87	1×	let m = map(&v, "certificate")?;
88	1×	check_version(m)?;
89	1×	let key = Identity::decode(bytes(field(m, 1, "key")?, "key")?)?;
90	1×	let mut claims = Vec::new();
91	2×	for c in array(field(m, 4, "claims")?, "claims")? {
92	2×	let pair = array(c, "claim")?;
93	2×	if pair.len() != 2 {
94	0×	return Err(ObjectError::Schema("claim: expected [name, value]".into()));
95	2×	}
96	2×	claims.push((
97	2×	text(&pair[0], "claim name")?.to_owned(),
98	2×	text(&pair[1], "claim value")?.to_owned(),
99		));
100		}
101	1×	let mut scope = Scope::NONE;
102	2×	for n in array(field(m, 5, "scope")?, "scope")? {
103	2×	let n = text(n, "scope")?;
104	2×	scope = scope
105	2×	\| Scope::named(n).ok_or_else(\|\| {
106	0×	ObjectError::Schema(format!("certificate: unknown scope {n:?}"))
107	0×	})?;
108		}
109		Ok(Certificate {
110	1×	key,
111	1×	issuer: oref(field(m, 2, "issuer")?, "issuer")?,
112	1×	subject: text(field(m, 3, "subject")?, "subject")?.to_owned(),
113	1×	claims,
114	1×	scope,
115	1×	not_before: uint(field(m, 6, "not_before")?, "not_before")?,
116	1×	expires: uint(field(m, 7, "expires")?, "expires")?,
117		})
118	1×	}
119
120		/// Whether the key may sign within `scope` at `at_ms`, a time the
121		/// signer did not choose.
122	6×	pub fn covers(&self, scope: Scope, at_ms: u64) -> bool {
123	6×	!scope.is_empty()
124	5×	&& self.scope.has(scope)
125	4×	&& self.not_before <= at_ms
126	3×	&& at_ms <= self.expires
127	6×	}
128
129		/// The claim called `name`, if the certificate has one.
130	1×	pub fn claim(&self, name: &str) -> Option<&str> {
131	1×	self.claims
132	1×	.iter()
133	2×	.find(\|(k, _)\| k == name)
134	1×	.map(\|(_, v)\| v.as_str())
135	1×	}
136		}
137
138		#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
139		pub enum CertError {
140		#[error("the certificate names issuer {0}, not this one")]
141		WrongIssuer(String),
142		#[error("the issuer's signature does not verify: {0}")]
143		BadSignature(String),
144		#[error("the certificate is valid for no time, or for longer than an hour")]
145		BadLifetime,
146		#[error("the certificate gives no scope")]
147		NoScope,
148		#[error("{0}")]
149		Schema(String),
150		}
151
152		impl From<ObjectError> for CertError {
153	0×	fn from(e: ObjectError) -> Self {
154	0×	CertError::Schema(e.to_string())
155	0×	}
156		}
157
158		/// A certificate with its issuer's signature over its ObjectRef.
159		#[derive(Clone, Debug, PartialEq, Eq)]
160		pub struct SignedCertificate {
161		pub cert: Certificate,
162		pub sig: Signature,
163		}
164
165		impl SignedCertificate {
166		/// Issue `cert`, signed by the issuer `issuer` holds the secret of.
167	4×	pub fn sign(mut cert: Certificate, issuer: &Identity, sk: &SecretKey) -> SignedCertificate {
168		// Claims in their canonical order, as encoded.
169	4×	cert.claims.sort();
170	4×	let sig = sk.sign(Domain::Certificate, &issuer.hash(), &cert.hash());
171	4×	SignedCertificate { cert, sig }
172	4×	}
173
174		/// Signed by `issuer`, which it names, and well formed. Whether to
175		/// trust the issuer for its subject is the policy's question.
176	5×	pub fn verify(&self, issuer: &Identity) -> Result<(), CertError> {
177	5×	let c = &self.cert;
178	5×	if issuer.hash() != c.issuer \|\| self.sig.key != c.issuer {
179	1×	return Err(CertError::WrongIssuer(c.issuer.short(12)));
180	4×	}
181	4×	verify(issuer, &self.sig, Domain::Certificate, &c.hash())
182	4×	.map_err(\|e\| CertError::BadSignature(e.to_string()))?;
183	2×	if c.expires <= c.not_before \|\| c.expires - c.not_before > MAX_LIFETIME_MS {
184	1×	return Err(CertError::BadLifetime);
185	1×	}
186	1×	if c.scope.is_empty() {
187	0×	return Err(CertError::NoScope);
188	1×	}
189	1×	Ok(())
190	5×	}
191
192		/// `[certificate bytes, signature]`.
193	1×	pub fn encode(&self) -> Vec<u8> {
194	1×	cbor::encode(&Value::Array(vec![
195	1×	Value::Bytes(self.cert.encode()),
196	1×	self.sig.to_value(),
197	1×	]))
198	1×	}
199
200	1×	pub fn decode(b: &[u8]) -> Result<SignedCertificate, CertError> {
201	1×	let v = cbor::decode(b).map_err(ObjectError::from)?;
202	1×	let a = array(&v, "signed certificate")?;
203	1×	if a.len() != 2 {
204	0×	return Err(CertError::Schema(
205	0×	"signed certificate: expected [certificate, signature]".into(),
206	0×	));
207	1×	}
208		Ok(SignedCertificate {
209	1×	cert: Certificate::decode(bytes(&a[0], "certificate")?)?,
210	1×	sig: Signature::from_value(&a[1])?,
211		})
212	1×	}
213		}
214
215		#[cfg(test)]
216		mod tests {
217		use super::*;
218
219	4×	fn issue(
220	4×	issuer_sk: &SecretKey,
221	4×	issuer: &Identity,
222	4×	minutes: u64,
223	4×	) -> (SecretKey, SignedCertificate) {
224	4×	let job_sk = SecretKey::generate();
225	4×	let cert = Certificate {
226	4×	key: job_sk.identity("job 12 build", "[email protected]", 1_000),
227	4×	issuer: issuer.hash(),
228	4×	subject: "repo:andy/demo:bookmark:main".into(),
229	4×	claims: vec![
230	4×	("run".into(), "12".into()),
231	4×	("environment".into(), "prod".into()),
232	4×	],
233	4×	scope: Scope::CHANGES \| Scope::REFS,
234	4×	not_before: 1_000,
235	4×	expires: 1_000 + minutes * 60_000,
236	4×	};
237	4×	(job_sk, SignedCertificate::sign(cert, issuer, issuer_sk))
238	4×	}
239
240		#[test]
241	1×	fn a_certificate_round_trips_and_verifies_with_its_issuer_only() {
242	1×	let hub_sk = SecretKey::generate();
243	1×	let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
244	1×	let (_, sc) = issue(&hub_sk, &hub, 10);
245	1×	let back = SignedCertificate::decode(&sc.encode()).unwrap();
246	1×	assert_eq!(back, sc);
247	1×	assert_eq!(back.cert.claims[0].0, "environment", "claims kept sorted");
248	1×	assert_eq!(back.cert.claim("run"), Some("12"));
249	1×	assert!(back.verify(&hub).is_ok());
250	1×	let other_sk = SecretKey::generate();
251	1×	let other = other_sk.identity("elsewhere", "[email protected]", 1);
252	1×	assert!(matches!(
253	1×	back.verify(&other),
254		Err(CertError::WrongIssuer(_))
255		));
256		// Changed after signing: the signature no longer covers it.
257	1×	let mut forged = back.clone();
258	1×	forged.cert.subject = "repo:andy/demo:bookmark:release".into();
259	1×	assert!(matches!(
260	1×	forged.verify(&hub),
261		Err(CertError::BadSignature(_))
262		));
263		// Signed by another key in the issuer's name.
264	1×	let mut stolen = back.clone();
265	1×	stolen.sig = other_sk.sign(Domain::Certificate, &hub.hash(), &back.cert.hash());
266	1×	assert!(matches!(
267	1×	stolen.verify(&hub),
268		Err(CertError::BadSignature(_))
269		));
270	1×	}
271
272		#[test]
273	1×	fn it_covers_its_scope_and_window_only() {
274	1×	let hub_sk = SecretKey::generate();
275	1×	let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
276	1×	let (_, sc) = issue(&hub_sk, &hub, 10);
277	1×	let c = &sc.cert;
278	1×	assert!(c.covers(Scope::CHANGES, 1_000) && c.covers(Scope::REFS, 1_000 + 10 * 60_000));
279	1×	assert!(!c.covers(Scope::SEAL, 2_000), "not a scope it gives");
280	1×	assert!(!c.covers(Scope::CHANGES, 999), "before it");
281	1×	assert!(
282	1×	!c.covers(Scope::CHANGES, 1_000 + 10 * 60_000 + 1),
283		"after it"
284		);
285	1×	assert!(!c.covers(Scope::NONE, 2_000));
286	1×	let (_, long) = issue(&hub_sk, &hub, 61);
287	1×	assert_eq!(long.verify(&hub), Err(CertError::BadLifetime));
288	1×	}
289
290		#[test]
291	1×	fn a_signature_by_the_short_lived_key_names_it() {
292	1×	let hub_sk = SecretKey::generate();
293	1×	let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
294	1×	let (job_sk, sc) = issue(&hub_sk, &hub, 10);
295	1×	let target = ObjectRef([5; 32]);
296	1×	let sig = job_sk.sign(Domain::Change, &sc.cert.key_id(), &target);
297	1×	assert_eq!(sig.key, sc.cert.key_id());
298	1×	assert!(verify(&sc.cert.key, &sig, Domain::Change, &target).is_ok());
299	1×	}
300		}

Coverage / crates/oxy-core/src/cert.rs 93.4%

Keyboard