NodeCert

NodeCert: a cluster node's certificate (distributed-deploys build step 11a).

A certificate names one node, the protocol roles it may play and the raw primitives it may use, and is signed (ed25519) by the cluster's OPERATOR key. Nodes present certificates in the cert-mode handshake (NetKernel.handshake_auth); each side verifies the other's against the operator public key and the clock, then proves it holds the key the certificate names. See specs/lang/clustering.md, "Node certificates".

Names are SPIFFE-style URIs, so a service mesh can carry the same identities later (SPIFFE itself is not implemented): node spiffe://<trust-domain>/pool/<pool>/node/<name> issuer spiffe://<trust-domain>/operator/<first 16 hex digits of the operator key>

Roles are "Proto.Role:offer" / "Proto.Role:initiate"; the one flag so far is "raw_send". Step 11b checks them: roles at session formation (SessionAP.authorize, from SessionNode's access points and direct runner), raw_send on every raw send and registry lookup (ClusterNode, NodeSend, NodeCall). See specs/lang/clustering.md, "Authorization".

Wire form. The body is the canonical MessagePack array ["march-node-cert-v1", node, [role...], [flag...], not_after, issuer, pubkey_hex, serial] (Msgpack.encode's smallest-form encoding; forge's cluster cert writes the same bytes), and a signed certificate is [Bin(body), Bin(signature)]; its text form (MARCH_NODE_CERT, forge cluster cert's .cert file) is that, base64. The signature covers the body bytes exactly as sent, so verification never re-encodes. not_after is unix SECONDS, inclusive.

A revocation is signed by the same operator key: body ["march-revocation-v1", node, serial, issued_at] revoking one certificate (serial != "") or every certificate of a node (serial == ""). Revocations are gossiped between nodes (ClusterNode).

Types

typeCertCert = { node : String, roles : List(String), flags : List(String), not_after : Int,#

typeSignedSigned = { cert : Cert, body : List(Int), signature : Bytes }#

typeRevocationRevocation = { node : String, serial : String, issued_at : Int }#

typeSignedRevocationSignedRevocation = { rev : Revocation, body : List(Int), signature : Bytes }#

typeCredentialsCredentials = { signed : Signed, secret_key : Bytes, operator_pubkey : Bytes,#

Functions

fncert_versioncert_version() : String do "march-node-cert-v1" end#

fndecodedecode(bytes : List(Int)) : Result(Cert, String)#

Decode a canonical body.

fndecode_revocationdecode_revocation(bytes : List(Int)) : Result(Revocation, String)#

fnencodeencode(c : Cert) : List(Int)#

The canonical MessagePack body of [c] (what the operator signs).

fnencode_revocationencode_revocation(r : Revocation) : List(Int)#

fnexpiredexpired(c : Cert, now : Int) : Bool do now > c.not_after end#

Has [c] expired at [now] (unix seconds)?

fnfrom_bytesfrom_bytes(bytes : List(Int)) : Result(Signed, String)#

Parse wire bytes (does NOT verify: see verify).

fnfrom_textfrom_text(t : String) : Result(Signed, String)#

Parse the text form (does NOT verify).

fnhas_flaghas_flag(c : Cert, flag : String) : Bool do List.member(c.flags, flag) end#

Does [c] carry [flag] (e.g. \

fnhas_rolehas_role(c : Cert, role : String) : Bool do List.member(c.roles, role) end#

Does [c] let its node play role [role] (\

fnis_revokedis_revoked(c : Cert, rs : List(Revocation)) : Bool#

Is [c] revoked by any of [rs]?

fnissued_msissued_ms(c : Cert) : Option(Int)#

When [c] was issued (unix ms), if its serial says (ordered_serial); None for a serial with no order.

fnissuer_uriissuer_uri(trust_domain : String, operator_pub_hex : String) : String#

The issuer URI for an operator public key (hex): its first 16 hex digits.

fnkey_from_hexkey_from_hex(s : String, len : Int) : Result(Bytes, String)#

A key (or signature) from its hex text, checking its length in bytes.

fnkeypairkeypair() : Bytes do ed25519_seed_keypair(Crypto.random_bytes(32)) end#

A fresh ed25519 secret key (64 bytes: seed || public key).

fnkeypair_from_seedkeypair_from_seed(seed : Bytes) : Bytes do ed25519_seed_keypair(seed) end#

The secret key a 32-byte [seed] determines (RFC 8032); empty Bytes for a wrong length.

fnnode_namenode_name(uri : String) : String#

The node name a certificate's URI ends in (the segment after the last "/node/"), or "" when the URI has no node segment. The handshake requires it to equal the name the peer announces.

fnnode_urinode_uri(trust_domain : String, pool : String, name : String) : String#

The SPIFFE-style URI of node [name] in [pool] under [trust_domain].

fnorder_problemorder_problem(next : Cert, held : Cert) : Option(String)#

Why [next] may not replace [held] (supersedes), if it may not.

fnordered_serialordered_serial(issued_ms : Int, rest : String) : String do int_to_string(issued_ms) ++ "-" ++ rest end#

A serial carrying issue time [issued_ms] (unix ms): \

fnpublic_keypublic_key(sk : Bytes) : Bytes do Bytes.slice(sk, 32, 32) end#

The 32-byte public key inside a 64-byte secret key.

fnrevocation_from_bytesrevocation_from_bytes(bytes : List(Int)) : Result(SignedRevocation, String)#

fnrevocation_from_textrevocation_from_text(t : String) : Result(SignedRevocation, String)#

fnrevocation_idrevocation_id(r : Revocation) : String#

A short identity for a revocation: the first 16 hex digits of the sha256 of its canonical body. Two copies of one revocation (from a release, from a peer's gossip, from MARCH_CLUSTER_REVOCATIONS) have the same id, so a node's report of the revocations it knows can be matched against a release's (Control, step 12b).

fnrevocation_to_bytesrevocation_to_bytes(s : SignedRevocation) : List(Int)#

fnrevocation_to_textrevocation_to_text(s : SignedRevocation) : String#

The text form of a signed revocation (base64): what forge cluster revoke prints.

fnrevocation_versionrevocation_version() : String do "march-revocation-v1" end#

fnrevokesrevokes(r : Revocation, c : Cert) : Bool#

Does [r] revoke [c]: the same serial, or (serial \

fnsignsign(c : Cert, operator_sk : Bytes) : Signed#

Sign [c] with the operator secret key [operator_sk].

fnsign_revocationsign_revocation(r : Revocation, operator_sk : Bytes) : SignedRevocation#

Sign a revocation with the operator secret key.

fnsupersedessupersedes(next : Cert, held : Cert) : Bool#

May [next] replace [held], by issue order? Refused when [held] carries an issue time and [next] was issued before it, or carries none (a certificate from before ordered serials cannot replace one after). When [held] has no issue time there is no order to keep and the answer is yes (the release floor guards that case, Control). The same certificate again is yes.

fnto_bytesto_bytes(s : Signed) : List(Int)#

The signed certificate's wire bytes: [Bin(body), Bin(signature)].

fnto_textto_text(s : Signed) : String do Bytes.encode_base64(Bytes.from_list(to_bytes(s))) end#

The text form (base64 of to_bytes): MARCH_NODE_CERT and forge's .cert files.

fnverifyverify(s : Signed, operator_pubkey : Bytes, now : Int) : Result(Cert, String)#

Verify a signed certificate against [operator_pubkey] (32 bytes) at [now] (unix seconds): the signature must cover the body, and [now] must not be past not_after. Returns the certificate, or why it is refused.

fnverify_revocationverify_revocation(s : SignedRevocation, operator_pubkey : Bytes) : Result(Revocation, String)#

Verify a signed revocation against the operator key (a member cannot revoke another).