swaitsandClaude Opus 4.7
9232c16f7c
A frozen spec is only meaningful if it's paired with the corpus that was current at release time — otherwise a v0.1.0 reader follows "see corpus/payloads/ack/" and lands on a file whose test vectors may have changed since v0.1.0 was cut. Three changes: 1. `cut-version` now copies BOTH src/ AND corpus/ into the snapshot directory. A release is the pair, not just the text. 2. The corpus URL rewriting in cut-version now retargets /tree/main/corpus -> /tree/main/versions/<v>/corpus (and the blob variant). This lets the link resolve on GitHub from main alone — no git tag required, since the frozen copy is a real path under main. Downgrades the "tag is REQUIRED" message from last commit back to "optionally tag the commit". 3. The frozen corpus's spec_ref fields get rewritten too: from `src/04-payload-ack.md` to `versions/<v>/04-payload-ack.md`, so a reader following a test vector lands on the spec text the vector was paired with at release time. versions/v0.1.0/ regenerated from scratch via `just cut-version v0.1.0` to pick up the corpus snapshot + the new sed patterns. The release is now self-consistent: v0.1.0 spec links go to v0.1.0 corpus, which links back to v0.1.0 spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
# MeshCore Protocol Specification
|
|
|
|
## Section 15: Identity
|
|
|
|
### Overview
|
|
|
|
Every MeshCore node has an Ed25519 key pair. The 32-byte public key serves as
|
|
the node's identity. Hashes used in routing are truncated prefixes of the public
|
|
key. Shared secrets for encryption are computed via ECDH key exchange using
|
|
X25519 (Ed25519 keys transposed to Curve25519).
|
|
|
|
### Key Types
|
|
|
|
| Type | Size | Description |
|
|
|------|------|-------------|
|
|
| Public Key | 32 bytes (PUB_KEY_SIZE) | Ed25519 public key |
|
|
| Private Key | 64 bytes (PRV_KEY_SIZE) | Ed25519 private key (seed + public) |
|
|
| Signature | 64 bytes (SIGNATURE_SIZE) | Ed25519 signature |
|
|
| Shared Secret | 32 bytes (PUB_KEY_SIZE) | ECDH shared secret |
|
|
|
|
### Hash Derivation
|
|
|
|
A node's routing hash is simply a prefix of its public key:
|
|
|
|
```
|
|
hash = pub_key[0..hash_size-1]
|
|
```
|
|
|
|
Where `hash_size` is 1, 2, or 3 bytes depending on the protocol version and
|
|
path encoding (see [Section 3](03-path.md)).
|
|
|
|
For V1, `PATH_HASH_SIZE` is 1, meaning a node's hash is the first byte of its
|
|
public key. This gives only 256 unique hash values, so hash collisions are
|
|
common and expected. The protocol handles this by attempting decryption with all
|
|
peers matching a given hash.
|
|
|
|
### Hash Matching
|
|
|
|
To check if a hash matches a node's identity:
|
|
|
|
```
|
|
match = memcmp(hash, pub_key, hash_size) == 0
|
|
```
|
|
|
|
### Ed25519 Signing
|
|
|
|
Used for advertisement signatures (see [Section 5](05-payload-advert.md)):
|
|
|
|
1. Construct the message to sign (e.g., pub_key || timestamp || app_data).
|
|
2. Sign using the Ed25519 private key.
|
|
3. The 64-byte signature is included in the advertisement payload.
|
|
|
|
Verification:
|
|
|
|
1. Extract the public key and signature from the payload.
|
|
2. Reconstruct the message.
|
|
3. Verify the signature using Ed25519 verification.
|
|
4. Receivers MUST discard the packet if verification fails.
|
|
|
|
### ECDH Key Exchange (X25519)
|
|
|
|
To compute a shared secret between two nodes:
|
|
|
|
1. Convert the Ed25519 keys to X25519 (Curve25519) format.
|
|
2. Perform X25519 Diffie-Hellman: `shared_secret = X25519(my_private, their_public)`.
|
|
3. The resulting 32-byte shared secret is used for:
|
|
- AES-128 key: `shared_secret[0..15]`
|
|
- HMAC-SHA256 key: `shared_secret[0..31]`
|
|
|
|
### Identity Serialization
|
|
|
|
Identities can be serialized for storage:
|
|
|
|
- **Public Identity**: 32 bytes (public key only)
|
|
- **Local Identity**: 64 bytes (private key) + 32 bytes (public key) = 96 bytes
|
|
|
|
Hex representation uses uppercase characters with 2 hex digits per byte.
|
|
|
|
### Cross-References
|
|
|
|
- [Section 3: Path](03-path.md) — Hash size in path encoding
|
|
- [Section 5: Advertisement](05-payload-advert.md) — Signature usage
|
|
- [Section 14: Cryptography](14-crypto.md) — Shared secret usage
|
|
- Test vectors: [`corpus/crypto/ed25519/`](https://github.com/swaits/meshcore-spec/tree/main/versions/v0.1.0/corpus/crypto/ed25519/), [`corpus/crypto/ecdh/`](https://github.com/swaits/meshcore-spec/tree/main/versions/v0.1.0/corpus/crypto/ecdh/)
|
|
|
|
### Reference Implementation
|
|
|
|
- `Identity` class in `src/Identity.h` — Public key and verification
|
|
- `LocalIdentity` class in `src/Identity.h` — Key pair, signing, ECDH
|
|
- `Identity::copyHashTo()` — Hash derivation (prefix copy)
|
|
- `Identity::isHashMatch()` — Hash comparison
|
|
- `LocalIdentity::calcSharedSecret()` — ECDH key exchange
|