Initial Commit

packages/security-stack/crypto/crypto-rsa/src/pem/labels.md

@@ -0,0 +1,49 @@
+# `pem/labels`
+
+## Purpose
+
+Centralised PEM textual labels per RFC 7468 §5/§10/§11 used by the public
+and private PEM parsers and serialisers in this package. Keeping the labels
+in one file means the parser whitelist and serialiser emission share a
+single source of truth.
+
+## Features
+
+- `PEM_LABEL_PUBLIC_KEY` — `"PUBLIC KEY"` (SPKI body).
+- `PEM_LABEL_RSA_PUBLIC_KEY` — `"RSA PUBLIC KEY"` (PKCS#1 public body).
+- `PEM_LABEL_PRIVATE_KEY` — `"PRIVATE KEY"` (PKCS#8 body).
+- `PEM_LABEL_RSA_PRIVATE_KEY` — `"RSA PRIVATE KEY"` (PKCS#1 private body).
+- `PEM_LINE_LENGTH = 64` — RFC 7468 §3 maximum body line length.
+
+## Usage: Basic Example
+
+```ts
+import { PEM_LABEL_PUBLIC_KEY } from "@suaveplan/crypto-rsa/pem";
+
+const armor = `-----BEGIN ${PEM_LABEL_PUBLIC_KEY}-----`;
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    PEM_LABEL_PRIVATE_KEY,
+    PEM_LABEL_RSA_PRIVATE_KEY,
+} from "@suaveplan/crypto-rsa/pem";
+
+function classifyPrivatePem(label: string): "pkcs8" | "pkcs1" | "unknown" {
+    if (label === PEM_LABEL_PRIVATE_KEY) return "pkcs8";
+    if (label === PEM_LABEL_RSA_PRIVATE_KEY) return "pkcs1";
+    return "unknown";
+}
+```
+
+## API Reference
+
+All exports are `string` constants.
+
+## Implementation Notes
+
+RFC 7468 §3 fixes the body line length at 64 base64 characters. Some legacy
+emitters use 76 (the historic RFC 1421 PEM length); we accept both on parse
+but always emit 64.