Files
MeshTerm/meshterm/core/privatekey.py
Jean-Pierre MartineauandClaude Haiku 5.5 723f7bdfef The identity key shows, imports from a file, and imports on an SPI radio
Show private key drew its warning and no key in the menu since 0.10.0.
On the uConsole and the Cardputer Zero, MeshTerm now writes an imported
key into the node's identity.key and restarts the node. An import also
reads a file (hex text or raw bytes), expands a 32-byte seed, refuses a
key of the wrong length before the confirmation, and names a firmware
that has its import turned off. The run log no longer stores the key of
config import-key (a migration removes the stored ones), and an exported
key file is written with mode 0600. Refer to #26.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-10-12 23:51:03 -04:00

129 lines
4.8 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""The private key of our node: the forms that MeshTerm accepts, and the one form that it sends.
A MeshCore companion exports and imports its private key in one form only: 64 bytes, the
expanded Ed25519 key of the orlp library that the firmware uses (a 32-byte scalar, then a
32-byte nonce). In hex, this key has 128 digits.
A key can also exist in a shorter form: the 32-byte Ed25519 seed from which the 64 bytes
come. The node that MeshTerm runs on an SPI radio keeps such a seed in its ``identity.key``
when it makes its own key. A seed is the same identity, but a firmware companion does not
accept it. Thus MeshTerm expands a seed before it sends it (:func:`expand_seed`), in the
same way that the firmware makes its own key. The user can give either form, and the
device always gets the 64 bytes.
"""
from __future__ import annotations
import hashlib
import re
from pathlib import Path
__all__ = [
"KEY_BYTES",
"SEED_BYTES",
"expand_seed",
"normalize",
"parse_private_key",
"read_private_key_file",
]
#: The length of a private key in the form that a companion exports and imports.
KEY_BYTES = 64
#: The length of an Ed25519 seed, the short form from which a key comes.
SEED_BYTES = 32
#: The largest file that :func:`read_private_key_file` reads. A key in hex, with a line
#: break, is 129 bytes. Thus a larger file is not a key, and the function does not read a
#: large file that the user selected by mistake.
_MAX_FILE_BYTES = 4096
_HEX = re.compile(r"[0-9a-fA-F]*")
def expand_seed(seed: bytes) -> bytes:
"""The 64-byte private key that a 32-byte Ed25519 seed makes.
This is the key generation of the orlp Ed25519 library, which the MeshCore firmware
uses: the SHA-512 digest of the seed, with its first half clamped to make the scalar.
The result has the same public key as the seed, and a firmware companion accepts it.
Raises:
ValueError: If ``seed`` does not have 32 bytes.
"""
if len(seed) != SEED_BYTES:
raise ValueError(f"A seed has {SEED_BYTES} bytes, not {len(seed)}.")
digest = hashlib.sha512(seed).digest()
scalar = bytearray(digest[:32])
scalar[0] &= 0xF8
scalar[31] &= 0x3F
scalar[31] |= 0x40
return bytes(scalar) + digest[32:]
def normalize(raw: bytes) -> bytes:
"""``raw`` as a 64-byte key: a key stays as it is, and a seed is expanded.
Raises:
ValueError: If ``raw`` is neither a key nor a seed. The message is for the user.
"""
if len(raw) == KEY_BYTES:
return bytes(raw)
if len(raw) == SEED_BYTES:
return expand_seed(raw)
raise ValueError(
f"A private key has {KEY_BYTES} bytes ({KEY_BYTES * 2} hex digits), or "
f"{SEED_BYTES} for a seed. This one has {len(raw)}."
)
def parse_private_key(text: str) -> bytes:
"""The 64-byte key in ``text``, which the user typed or pasted as hex.
The function ignores spaces and line breaks, because a key that the user copies from a
terminal often has them where the terminal wrapped the line.
Raises:
ValueError: If ``text`` is not hex, or has the wrong length. The message is for the
user.
"""
digits = "".join(text.split())
if not digits or not _HEX.fullmatch(digits):
raise ValueError("A private key has hex digits only (0-9 and a-f).")
if len(digits) % 2:
raise ValueError(
f"A private key has an even number of hex digits. This one has {len(digits)}."
)
return normalize(bytes.fromhex(digits))
def read_private_key_file(path: Path) -> bytes:
"""The 64-byte key in the file at ``path``: hex text, or the raw bytes of a key or a seed.
``config export-key --out`` writes hex text. The ``identity.key`` of a node keeps raw
bytes. The function accepts the two forms. It reads the file as hex text first. A raw
key is random bytes, and the chance that all of them are hex digits is too small to
matter. But a hex seed that someone wrote into a key file as text is a real mistake,
and as raw bytes it would be read as a different key.
Raises:
OSError: If the file cannot be read.
ValueError: If the file does not hold a key. The message is for the user.
"""
if path.stat().st_size > _MAX_FILE_BYTES:
raise ValueError(f"{path.name} is too large to be a private key.")
data = path.read_bytes()
try:
digits = "".join(data.decode("ascii").split())
except UnicodeDecodeError:
digits = ""
if digits and _HEX.fullmatch(digits):
return parse_private_key(digits)
if len(data) in (KEY_BYTES, SEED_BYTES):
return normalize(data)
raise ValueError(
f"{path.name} does not hold a private key. A key file holds the key as hex "
f"text, or {KEY_BYTES} or {SEED_BYTES} raw bytes."
)