Skip to content

Commit 41b387b

Browse files
committed
docs: fix key-rotation framing and Unreleased release-notes headers
Key rotation: the page claimed the rotation procedure was "two fold... performed independently" but only ever documented one step (adding a key) — removal was cut when it was found unsupported, but the "two fold" framing and the orphaned "1." numbering were never cleaned up. Reframed the page around what's actually supported: adding a new key. Removal still isn't supported, so this isn't full rotation yet, but it's real, useful, working operator guidance and worth keeping. Release notes: the Unreleased section used Markdown-style "## New features" / "## Security" headers, which don't render as headings in RST (Sphinx renders them as literal text) and don't match every other section in the file, which uses proper underlined RST headers. Assisted by AI Claude-Session: https://claude.ai/code/session_01VJiY69SPaAf1mxERAWK1SG
1 parent 78eb53c commit 41b387b

2 files changed

Lines changed: 14 additions & 12 deletions

File tree

docs/pages/operations/key-rotation.rst

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,12 @@ Key rotation procedure
55

66
To minimize the impact of stolen/leaked keys, private keys should be rotated at a regular, scheduled interval.
77
This applies to any private key used for a longer period of time.
8-
The node aids this procedure by supporting operations to add to DID documents.
9-
Removal of keys is currently not supported. Newer keys are automatically used for cryptographic operations.
8+
The node currently only supports the "add" half of rotation: adding a new key to a DID document.
9+
Removing an existing key is not supported — once added, a key remains part of the DID document indefinitely.
10+
Newer keys are automatically used for cryptographic operations.
1011

11-
Procedure
12-
*********
13-
14-
The procedure to rotate a key is two fold. The two procedures can be performed independently.
12+
Adding a new key
13+
*****************
1514

1615
Given a period of time, eg. every month when issuing a lot of credentials or every year when issuing only a few, a new key should be added to the DID document.
1716

@@ -20,10 +19,7 @@ Given a period of time, eg. every month when issuing a lot of credentials or eve
2019
The current API doesn't support finding VCs based on validity period or specific key.
2120
The only possibility is to find all and loop over the results to check the validity period and the key used to sign the VC.
2221

23-
1. Add a new key
24-
================
25-
26-
Then, you add a new key which generates a new key pair in your crypto storage and adds it to the DID document:
22+
You add a new key, which generates a new key pair in your crypto storage and adds it to the DID document:
2723

2824
.. code-block:: shell
2925

docs/pages/release_notes.rst

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,20 @@ Release notes
66
Unreleased
77
****************
88

9-
## New features
9+
============
10+
New Features
11+
============
12+
1013
* #4063: Enable ``storage.debug`` flag to log go-leia performance issues (full table scans, suboptimal index usage) by @reinkrul in https://github.com/nuts-foundation/nuts-node/pull/4064
1114
* #4078: Allow policy profiles to define a ``service_provider`` PresentationDefinition for the OAuth client (RFC 7523 ``jwt-bearer`` flow) by @stevenvegt in https://github.com/nuts-foundation/nuts-node/pull/4226
1215
* #4078: Add the experimental RFC 7523 ``jwt-bearer`` two-VP token request flow, gated behind ``auth.experimental.jwtbearerclient`` (default ``false``, subject to change) by @stevenvegt in https://github.com/nuts-foundation/nuts-node/pull/4227
1316
* #4078: Expose the experimental two-VP flow on ``POST /internal/auth/v2/{subjectID}/request-service-access-token`` via the optional ``service_provider_subject_id`` body field by @stevenvegt in https://github.com/nuts-foundation/nuts-node/pull/4228
1417
* #4233: ``request-credential`` API gains an optional ``credential_request_params`` JSON object overlaid on top of the OpenID4VCI Credential Request body sent to the issuer. Lets the wallet talk to issuers that accept additional fields, or to override the credential request entirely.
1518

16-
## Security
19+
========
20+
Security
21+
========
22+
1723
* #4441: Inbound HTTP request bodies are now limited to 1MB on both the public and internal interfaces; larger requests are rejected with HTTP 413 (Request Entity Too Large). Previously no limit was enforced, contrary to what the deployment documentation stated. The heaviest legitimate requests (OAuth POSTs carrying Verifiable Presentations) stay well below this limit, and it matches the ``client_max_body_size 1M`` reverse proxy configuration the documentation recommends. By @stevenvegt in https://github.com/nuts-foundation/nuts-node/pull/4441
1824
* #4439: Helm chart (version 0.0.9): default ``verbosity`` changed from ``debug`` to ``info``, matching the node's own default. Debug verbosity produces far more log output than production needs and increases the impact of any log-hygiene issue. Set ``nuts.config.verbosity: debug`` in your own values to restore the old behavior. By @stevenvegt in https://github.com/nuts-foundation/nuts-node/pull/4439
1925
* #4440: In strictmode, ``http.log: metadata-and-body`` is no longer honored: the node resets it to ``metadata`` at startup and logs a warning. Full body logging wrote OAuth token endpoint request and response bodies (client assertions, VP tokens, authorization codes and issued access tokens) to the log at Info severity. Non-strictmode deployments are unaffected. By @stevenvegt in https://github.com/nuts-foundation/nuts-node/pull/4440

0 commit comments

Comments
 (0)