docs/generated/contracts.mdgenerated from code

Reference · 4 min read

api-keys

Contracts: api-keys.

Source: crates/lvcs-api/src/keys.rs.

ruston main
1/// `key.encryption`: the connection's peer's X25519 encryption public2/// key. The keyring derives it from that peer's Ed25519 signing key3/// (HPKE `DeriveKeyPair` for DHKEM(X25519, HKDF-SHA256) over4/// `SHA-256(ENCRYPTION_KEY_DOMAIN || seed)`), so its private half lives5/// exactly where the signing key does and is the same on every ask. A6/// `peer` (an id) other than the connection's own is refused7/// `INVALID_PARAMS`.8#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]9pub struct KeyEncryptionParams {10    #[serde(default, skip_serializing_if = "Option::is_none")]11    pub peer: Option<String>,12}1314/// `key.encryption` result: the 32-byte public key.15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]16pub struct KeyEncryptionResult {17    pub public: String,18}1920/// `key.open`: an HPKE (RFC 9180) base-mode single-shot open of21/// `ciphertext`, encapsulated as `enc`, with `info` and `aad`, under the22/// connection's peer's encryption key: DHKEM(X25519, HKDF-SHA256),23/// HKDF-SHA256, ChaCha20-Poly1305. A ciphertext over `KEY_OPEN_MAX_BYTES`24/// is refused `INVALID_PARAMS`; one that doesn't open is refused25/// `INVALID_PARAMS` with nothing more said. The plaintext is never kept26/// for a retry window (`key.open` is not retried).27#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]28pub struct KeyOpenParams {29    pub enc: String,30    pub ciphertext: String,31    #[serde(default)]32    pub info: String,33    #[serde(default)]34    pub aad: String,35}3637/// `key.open` result.38#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]39pub struct KeyOpenResult {40    pub plaintext: String,41}4243/// `key.endorse`: the connection's peer's Ed25519 signature over44/// [`endorsed_input`]`(domain, message)`, so a plugin can publish what45/// that peer vouches for itself (its encryption key) and every reader46/// checks it against the peer id. The input's prefix keeps it apart from47/// every signature core makes. `domain` is 1 to `ENDORSE_DOMAIN_MAX_BYTES`48/// of printable ASCII holding a `/` ([`endorse_domain_valid`]); `message`49/// decodes to at most `ENDORSE_MESSAGE_MAX_BYTES`. Signing, it takes a50/// signing token like every op that signs.51#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]52pub struct KeyEndorseParams {53    pub domain: String,54    pub message: String,55}5657/// `key.endorse` result: the 64-byte signature.58#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]59pub struct KeyEndorseResult {60    pub signature: String,61}6263/// `key.held`: the peers whose signing keys this daemon's keyring holds64/// for the hello'd project, its key directory read first: every local65/// peer, plugin and instance keys included, so a client can tell which66/// recipients this node acts as without saying `hello` as each.67#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]68pub struct KeyHeldParams {}6970/// `key.held` result: peer ids in `ID_ENCODING`, sorted.71#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]72pub struct KeyHeldResult {73    #[serde(default)]74    pub peers: Vec<String>,75}7677/// The first bytes of every `key.endorse` signature's input.78pub const ENDORSE_PREFIX: &[u8] = b"lvcs endorse v1\0";7980/// What the domain hashed with a peer's signing seed derives its81/// encryption key from.82pub const ENCRYPTION_KEY_DOMAIN: &[u8] = b"lvcs encryption key v1\0";8384/// The bytes `key.endorse` signs: [`ENDORSE_PREFIX`], `domain`, a zero85/// byte, then `message`. A verifier checks the signature over these.86#[must_use]87pub fn endorsed_input(domain: &str, message: &[u8]) -> Vec<u8> {88    let mut input = Vec::with_capacity(ENDORSE_PREFIX.len() + domain.len() + 1 + message.len());89    input.extend_from_slice(ENDORSE_PREFIX);90    input.extend_from_slice(domain.as_bytes());91    input.push(0);92    input.extend_from_slice(message);93    input94}9596/// `key.replaced` push (discussion:owner/768, revision: Issuing, Handing,97/// Revoking, Finishing; o-edge/8): plugin `plugin`'s key `old` is being98/// replaced by `new` in this project. Pushed to the live connections of99/// every enabled plugin whose manifest declares `handover`, again at each100/// retry until it answers. The old key's grants and key file stay until101/// every such plugin answered [`KeyHandedParams`] for the pair; one that102/// answers [`KeyHandoverBlockedParams`], or none by the handover's103/// deadline, keeps them, and the cutover says so in status.104#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]105pub struct KeyReplacedPush {106    pub plugin: String,107    pub old: String,108    pub new: String,109}110111/// `key.handed`: the calling plugin, as its own key, is ready for `old` to112/// go: nothing it keeps on this node needs `old` any more, `new` taking113/// its place.114#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]115pub struct KeyHandedParams {116    pub old: String,117    pub new: String,118}119120/// `key.handover_blocked`: the calling plugin can't be ready for `old` to121/// go on this node: `reason`, and `next`, the step that makes it so, both122/// shown in status. Neither ever holds a secret.123#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]124pub struct KeyHandoverBlockedParams {125    pub old: String,126    pub new: String,127    pub reason: String,128    pub next: String,129}130131/// `key.handed` and `key.handover_blocked` result: whether a cutover is132/// handing this pair now and took the answer.133#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]134pub struct KeyHandoverResult {135    pub taken: bool,136}137138/// Whether `domain` is one `key.endorse` signs in: 1 to139/// `ENDORSE_DOMAIN_MAX_BYTES` bytes of printable ASCII, holding a `/`.140#[must_use]141pub fn endorse_domain_valid(domain: &str) -> bool {142    !domain.is_empty()143        && domain.len() <= lvcs_vocab::security::ENDORSE_DOMAIN_MAX_BYTES144        && domain.contains('/')145        && domain.bytes().all(|byte| byte.is_ascii_graphic())146}