first commit

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

@@ -0,0 +1,55 @@
+# `keys/parse-pkcs8`
+
+## Purpose
+
+Parses a PKCS#8 `PrivateKeyInfo` per RFC 5208 §5 — also accepts the
+RFC 5958 `OneAsymmetricKey` shape, which adds optional `[0] attributes`
+and `[1] publicKey` trailing fields. The inner `privateKey OCTET STRING`
+carries a PKCS#1 `RSAPrivateKey` which is delegated to the PKCS#1 parser.
+
+PKCS#8 is the canonical wire format for any private key persisted to
+disk (OpenSSL `PRIVATE KEY` PEM, PKCS#12 / PFX `EncryptedData` payloads
+after decryption, JWE `kty: RSA` private-form decryption keys).
+
+## Features
+
+- DER outer SEQUENCE → version → AlgorithmIdentifier → OCTET STRING walk.
+- Algorithm OID equality against `OID_RSA_ENCRYPTION`.
+- RFC 5958 `[0] attributes` and `[1] publicKey` tolerant — both consumed
+  and discarded.
+- Delegates to `parseRsaPrivateKeyPkcs1` for the inner RSAPrivateKey body.
+
+## Usage: Basic Example
+
+```ts
+import { parseRsaPrivateKeyPkcs8 } from "@suaveplan/crypto-rsa";
+
+const key = parseRsaPrivateKeyPkcs8(pkcs8DerBytes);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { parseRsaPrivateKeyPkcs8 } from "@suaveplan/crypto-rsa";
+
+// RFC 5958 OneAsymmetricKey form with optional trailing publicKey [1].
+const key = parseRsaPrivateKeyPkcs8(oneAsymmetricKeyBytes);
+```
+
+## API Reference
+
+### `parseRsaPrivateKeyPkcs8(bytes: Uint8Array): RsaPrivateKey`
+
+Throws `CryptoRsaError(CRYPTO_RSA.UNSUPPORTED_FORMAT)` for non-RSA OIDs.
+Throws `CryptoRsaError(CRYPTO_RSA.INVALID_KEY)` on structural problems
+(unsupported `version`, missing fields, trailing non-context-specific bytes).
+
+## Implementation Notes
+
+PKCS#8 `version` is `0` for RFC 5208 and `1` for the RFC 5958 successor
+(the version bumps when `publicKey` is present). Both are accepted; the
+RFC 5958 trailing fields are walked through as opaque context-specific
+TLVs without attempting to parse them, because Stage 1 has no need for
+the public-key cross-check or the attribute set. Stage 4 may add a
+verification that the `[1] publicKey` matches the inner PKCS#1
+`(n, e)`.