first commit

docs/security-stack/crypto/crypto-rsa/src/pem/serialize-private.md

@@ -0,0 +1,43 @@
+# `pem/serialize-private`
+
+## Purpose
+
+Inverse of `parseRsaPrivateKeyPem`. Emits PEM textual encoding for an RSA
+private key in either PKCS#8 (`"PRIVATE KEY"`, the modern default) or
+PKCS#1 (`"RSA PRIVATE KEY"`, the legacy OpenSSL form) per RFC 7468 §3.
+
+## Features
+
+- 64-char body line emission.
+- Discriminated `format` option (`"pkcs8"` default | `"pkcs1"`).
+- Reuses the underlying DER serialisers.
+
+## Usage: Basic Example
+
+```ts
+import { serializeRsaPrivateKeyPem } from "@suaveplan/crypto-rsa/pem";
+
+const pem = serializeRsaPrivateKeyPem(key);
+// -----BEGIN PRIVATE KEY----- ...
+```
+
+## Usage: Advanced Example
+
+```ts
+import { serializeRsaPrivateKeyPem } from "@suaveplan/crypto-rsa/pem";
+
+const legacy = serializeRsaPrivateKeyPem(key, { format: "pkcs1" });
+// -----BEGIN RSA PRIVATE KEY----- ...
+```
+
+## API Reference
+
+### `serializeRsaPrivateKeyPem(key, options?: { format?: "pkcs8" | "pkcs1" }): string`
+
+Returns the PEM string with trailing newline.
+
+## Implementation Notes
+
+We default to PKCS#8 for the same reason `serialize-public` defaults to
+SPKI — modern PKI tooling, KMS providers, and JOSE libraries all consume
+PKCS#8. PKCS#1 remains for legacy OpenSSL and ssh-keygen interop.