first commit

docs/security-stack/crypto/crypto-rsa/src/keys/serialize-pkcs8.md

@@ -0,0 +1,49 @@
+# `keys/serialize-pkcs8`
+
+## Purpose
+
+Inverse of `parseRsaPrivateKeyPkcs8`. Wraps a serialised PKCS#1
+`RSAPrivateKey` in a DER `PrivateKeyInfo` per RFC 5208 §5, emitting the
+canonical `version 0` form (RFC 5958 `version 1` requires the optional
+`publicKey [1]` field which Stage 1 does not emit).
+
+## Features
+
+- Standard PKCS#8 emission with `version 0`.
+- Reuses `serializeRsaPrivateKeyPkcs1` so the inner OCTET STRING body
+  matches the PKCS#1 output bit-for-bit.
+- RFC 3279 §2.3.1 conformant `NULL` algorithm parameters.
+
+## Usage: Basic Example
+
+```ts
+import { serializeRsaPrivateKeyPkcs8 } from "@suaveplan/crypto-rsa";
+
+const pkcs8 = serializeRsaPrivateKeyPkcs8(key);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    parseRsaPrivateKeyPkcs8,
+    serializeRsaPrivateKeyPkcs8,
+} from "@suaveplan/crypto-rsa";
+
+const roundTripped = parseRsaPrivateKeyPkcs8(
+    serializeRsaPrivateKeyPkcs8(key)
+);
+```
+
+## API Reference
+
+### `serializeRsaPrivateKeyPkcs8(key: RsaPrivateKey): Uint8Array`
+
+Returns the DER-encoded `PrivateKeyInfo`.
+
+## Implementation Notes
+
+We emit `version 0` (RFC 5208) rather than `version 1` (RFC 5958) because
+Stage 1 does not have a public-key derivation pipeline yet. Stage 4 may
+add a `version 1` emission path that includes the `[1] publicKey` field
+for ecosystems (cosign, sigstore) that prefer the OneAsymmetricKey form.