NTP-12: Sharded Certificate Storage for the Norsh Ecosystem

Status: DRAFT
Version: 1.0.0
Author: Danthur Lice
Date: 2025-09-06
License: NCL-11

1. Scope

This technical specification defines a deterministic and scalable sharded file system structure for storing issued certificates (PEM, OCSP, JSON metadata) in the Norsh Public Key Infrastructure (PKI). It ensures optimal lookup, long-term maintainability, and balanced directory distribution.

2. Certificate Issuance Policy

2.1 Validity Period

Each address certificate is valid from UTC now - 1 minute until 31/12/YYYY 23:59:59.999Z + 1 day, where YYYY is the year of issuance.

No certificate shall exceed a validity window beyond 12 months.

2.2 Renewal Cadence

New certificates are deterministically issued per calendar year.

Issuance for a new year always begins on 01/01/YYYY 00:00:00.000Z.

If a certificate is created in the last instant of an odd year (e.g., 31/12/2025 23:59:59.999Z), it will still be valid until 01/01/2026 23:59:59.999Z, preventing rejection due to certificate expiration in early transactions.

3. Folder Structure

3.1 Sharding Strategy

The address (hex string) is deterministically used to shard the filesystem.

Given address:

982a4ef85778c45e7cb348967373037a3a840489cedc4aa68d4cc3cf804cac0039e31e7e19a9b367493bbca09626f9ff

The folder is resolved using the first 6 hex characters split into 3/3:

/issued/982/a4e/

3.2 File Naming Convention

The full file is named using the entire hex address, plus a hyphen and the year of issuance:

982a4ef85778c45e7cb348967373037a3a840489cedc4aa68d4cc3cf804cac0039e31e7e19a9b367493bbca09626f9ff-2025.pem

3.3 Associated Files

*.pem: PEM-encoded X.509 certificate

*.json: Metadata (see section 4)

*.ocsp: OCSP response (optional)

3.4 Folder Example

/pki.norsh.org/issued/982/a4e/
└── 982a4e...ff-2025.pem

4. Metadata Schema (JSON)

{
  "address": "982a4ef857...",
  "year": 2025,
  "notBefore": "2025-09-06T13:00:00.000Z",
  "notAfter": "2026-01-01T23:59:59.999Z",
  "issuer": "CN=Norsh Prod CA,O=Norsh LLC,C=US",
  "alg": "ECDSA-SHA3-512",
  "curve": "secp521r1",
  "aki": "<hex_authorityKeyIdentifier>",
  "ski": "<hex_subjectKeyIdentifier>",
  "folder": "982/a4e",
  "file": "982a4e...-2025",
  "pem": "https://pki.norsh.org/issued/98/2a/4e/982a4e...-2025.pem",
  "json": "https://pki.norsh.org/issued/98/2a/4e/982a4e...-2025.json"
}

5. Considerations

The sharded layout ensures that even with billions of addresses, no folder exceeds manageable limits (2^16 = 65,536).

By using the full address in filenames, there is no risk of certificate collision.

The folder depth (3 levels) maintains a balance between performance and filesystem overhead.

6. Conclusion

This sharded certificate storage model provides deterministic, scalable, and stateless organization of address-based certificates in the Norsh ecosystem. It simplifies lookup, supports efficient distribution of files, and aligns with cryptographic best practices for per-address identity. With an enforced issuance cadence and clean metadata structure, the PKI layer of Norsh remains auditable, secure, and future-proof for millions of participants.

Future NTPs may define:

Revocation strategies

OCSP signing structure and lifecycle

Automation APIs for issuance and renewal

Integration with address resolution and Smart Elements

NTP-12: Sharded Certificate Storage for the Norsh Ecosystem

1. Scope#

2. Certificate Issuance Policy#

2.1 Validity Period#

2.2 Renewal Cadence#

3. Folder Structure#

3.1 Sharding Strategy#

3.2 File Naming Convention#

3.3 Associated Files#

3.4 Folder Example#

4. Metadata Schema (JSON)#

5. Considerations#

6. Conclusion#