Skip to content

encrypted key file: atomic re-encryption and clear errors - #101

Open
EnzinoBB wants to merge 5 commits into
CREDITSCOM:masterfrom
CreditsCommunity:official/node-key-salt
Open

EnzinoBB wants to merge 5 commits into
CREDITSCOM:masterfrom
CreditsCommunity:official/node-key-salt

Conversation

@EnzinoBB

@EnzinoBB EnzinoBB commented Nov 4, 2026

Copy link
Copy Markdown

Why this PR

When the node encrypts or re-encrypts its private key file (--encryptkey, the "[1] Encrypt with password" choice at the first start, or the change of password offered at start), several things can go wrong:

  • The file is truncated in place and write errors are ignored, so a crash or a full disk at that moment can lose the key while the log still reports success.
  • A failed encryption writes an empty file.
  • When reading, a failed key derivation is not checked.
  • A file of an unexpected length goes to the password prompt instead of being refused.

This PR makes that handling safer. The file format does not change: files written by this version and by earlier versions are identical and interchangeable.

What changes

  • client/config/keyfilecrypt.{hpp,cpp} (new): cs::keyfile::encrypt and cs::keyfile::decrypt write and read the format of cscrypto's PrivateKey::getEncrypted / readFromEncrypted byte for byte: the same salt, the same Argon2id derivation, the same crypto_aead_chacha20poly1305 and the same 88-byte layout. They differ only in their checks:
    • a failed allocation or derivation is an error (an empty result), not a null dereference;
    • any length other than 88 is refused before decryption;
    • the KDF identifiers are pinned (crypto_pwhash_ALG_ARGON2ID13, argon2id OPSLIMIT/MEMLIMIT_SENSITIVE) to the values of the generic aliases used before.
  • client/config/config.cpp:
    • Atomic re-encryption: the key file is written to NodePrivate.txt.tmp (mode 0600), flushed, renamed over the target and the folder flushed; on Windows MoveFileEx(REPLACE_EXISTING | WRITE_THROUGH). Every return value is checked. On failure the previous file stays and an error is logged instead of the success line.
    • A failed encryption no longer writes an empty key file.
    • A decoded length other than 64 (plain key) or 88 (encrypted) stops the node once with Bad private key file in ... (N bytes), before any prompt. This is also a robustness fix: on a longer file, cscrypto's reader zeroes its 64-byte output buffer with the input's length when the tag check fails, which ends the process.
    • A file used as the password is read directly into its buffer and wiped after use.
    • Prompts, retries and the file-as-password mode are otherwise unchanged.
  • cscrypto is not changed (no submodule bump).
  • tests/csnode/keyfilecrypt_tests.cpp runs as its own ctest entry (keyfilecrypt_tests), because each derivation takes 1 GiB and a few seconds. It checks:
    • a file written by cscrypto opens, and re-encrypting its key with the same password and nonce gives the same bytes;
    • cscrypto's reader opens what the new code writes, and the new code opens what cscrypto writes;
    • a wrong password, a changed byte, other lengths and a failed derivation are refused.

Compatibility

Full. The key file format is unchanged, so existing encrypted key files keep working, and a file encrypted by this version opens with earlier versions.

Effect on the network

None. Only the local key file is concerned: nothing on the wire, in storage or in consensus changes.

Tests

Built with GCC 13 and Boost 1.83 on 4a95aaa plus the test fixes of #77 (needed for the test suite to build on GCC 13): https://github.com/CreditsCommunity/node/actions/runs/41904789637 (keyfilecrypt_tests passes).

By hand, the community build with this change and a build of 4a95aaa open each other's encrypted key files in both directions, and the files stay byte-for-byte unchanged.

Same change in the community fork: CreditsCommunity#170.

🤖 Generated with Claude Code

EnzinoBB and others added 5 commits November 4, 2026 17:45
A new encryption of NodePrivate.txt (--encryptkey, "[1] Encrypt with password" at the first
start, the change of password at start) writes base58(salt (16 random bytes) || nonce (8 random
bytes) || crypto_aead_chacha20poly1305 ciphertext and tag), 104 bytes decoded, the key derived
with the same crypto_pwhash parameters and the file's own salt.

Reading tells the formats apart by length: 88 bytes (files written by earlier versions) are
opened by cscrypto's PrivateKey::readFromEncrypted as before and never rewritten; 104 bytes is
the new format; any other length does not open. Prompts and the file-as-password mode are
unchanged. cscrypto is not changed. A failed encryption no longer writes an empty key file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…vations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ked derivation

- The private key file is written to NAME.tmp (0600, O_NOFOLLOW), fsync'ed, renamed over NAME
  and the folder fsync'ed; on Windows CreateFile, FlushFileBuffers and MoveFileEx
  (REPLACE_EXISTING | WRITE_THROUGH). Every return value is checked: on failure the old file
  stays and an error is logged instead of the success line.
- crypto_pwhash_ALG_ARGON2ID13 with the argon2id OPSLIMIT/MEMLIMIT_SENSITIVE: the values the
  generic aliases have today, no format change.
- A decoded length other than 64, 88 or 104 stops once with "Bad private key file in ...
  (N bytes)" before any prompt.
- The 88-byte format is read in keyfilecrypt.cpp with the same derivation and cipher, the key
  allocation and the derivation checked, so a failed derivation is an error; such files are
  still never rewritten.
- A file used as password is read straight into its buffer and wiped after use.
- Tests: a changed ciphertext byte of a 104-byte file, and a failed derivation in both
  directions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The node writes and reads only the 88-byte format of cscrypto's PrivateKey::getEncrypted /
readFromEncrypted, as before. The other format of the previous commits is removed: never written,
never read.

cs::keyfile::encrypt / decrypt implement that same format (same salt, same Argon2id derivation
with pinned identifiers of the same values, same cipher and layout) so that a failed allocation
or derivation is an error instead of a null dereference; encryptWithNonce lets the tests prove
the bytes identical to cscrypto's.

Kept: atomic re-encryption (tmp, fsync, rename, every return value checked, no false success
line), no empty key file when encryption fails, "Bad private key file in ... (N bytes)" for a
length other than 64 or 88 before any prompt, the file-as-password buffer wiped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant