# `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)`.