@owf/x509 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @owf/x509
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@owf/x509)](https://npmjs.com/package/@owf/x509)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE)
+
+Environment agnostic X.509 certificates and certificate revocation lists (RFC 5280): parse, create, verify and check
+revocation.
+
+The package is pure TypeScript on top of [`@peculiar/asn1-x509`](https://www.npmjs.com/package/@peculiar/asn1-x509) and
+[`asn1js`](https://www.npmjs.com/package/asn1js). It uses neither Node.js built-ins, global crypto nor
+`reflect-metadata`, so it runs on servers, in browsers and in React Native. Signing and signature verification are
+callbacks, so private keys never enter the package and can stay in WebCrypto, a KMS or an HSM.
+
+Profiles such as [`@owf/eudi-access-certificate`](../eudi-access-certificate) (ETSI TS 119 411-8) are built on top of it.
+
+## Installation
+
+```bash
+npm install @owf/x509
+```
+
+## Certificates
+
+### Parsing
+
+```typescript
+import { parseCertificate } from '@owf/x509'
+
+const cert = parseCertificate(pem) // PEM, base64 DER or DER bytes
+
+cert.subject.commonName
+cert.subject.rfc4514          // 'CN=Example,O=Example GmbH,C=DE'
+cert.serialNumber             // lowercase hex
+cert.notBefore / cert.notAfter
+cert.publicKey.jwk            // EC (P-256/384/521) and RSA keys as JWK
+cert.policies                 // [{ oid, cpsUris, userNotices }]
+cert.subjectAlternativeNames  // { dnsNames, uris, emails, ipAddresses, directoryNames, otherNames }
+cert.keyUsage, cert.extendedKeyUsage, cert.basicConstraints
+cert.subjectKeyIdentifier, cert.authorityKeyIdentifier
+cert.crlDistributionPoints, cert.ocspUrls, cert.caIssuersUrls
+cert.qcStatements             // RFC 3739 / ETSI EN 319 412-5
+cert.extensions               // every extension as { oid, critical, value }
+```
+
+### Verifying a signature
+
+```typescript
+import { verifyCertificateSignature } from '@owf/x509'
+
+const ok = await verifyCertificateSignature(cert, issuerPem, async ({ data, signatureP1363, publicKey }) => {
+  const key = await crypto.subtle.importKey('jwk', publicKey.jwk!, { name: 'ECDSA', namedCurve: 'P-256' }, false, [
+    'verify',
+  ])
+  return crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, key, signatureP1363, data)
+})
+```
+
+The verifier receives the signed bytes, the signature both as encoded (DER for ECDSA) and as IEEE P1363 (`r || s`, what
+WebCrypto expects), and the issuer public key as SPKI and JWK. Issuer name and key identifiers have to match as well.
+This checks a single link. Path building to a trust anchor is up to the caller.
+
+### Creating
+
+```typescript
+import { createCertificate, stringOtherName, ATTRIBUTE_TYPES } from '@owf/x509'
+import { digest } from '@owf/crypto'
+
+const cert = await createCertificate({
+  subject: [
+    ['countryName', 'DE'],
+    ['organizationName', 'Example GmbH'],
+    ['commonName', 'Example Service'],
+  ],
+  subjectPublicKey: publicJwk, // or SPKI bytes; private JWKs are rejected
+  issuerCertificate: caPem,    // omit for a self-signed certificate
+  serialNumber: randomSerialHex,
+  notBefore: new Date(),
+  notAfter: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
+  signatureAlgorithm: 'ES256', // ES256, ES384, ES512, RS256, RS384, RS512
+  certificatePolicies: [{ oid: '1.2.3.4', cpsUris: ['https://ca.example.com/cps'] }],
+  subjectAlternativeNames: {
+    dnsNames: ['service.example.com'],
+    otherNames: [stringOtherName(ATTRIBUTE_TYPES.telephoneNumber, '+4930123456')],
+  },
+  crlDistributionPoints: ['https://ca.example.com/crl'],
+  hasher: digest, // optional: subject key identifier (RFC 7093 method 1)
+  signer: async (tbs) => new Uint8Array(await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, caKey, tbs)),
+  signatureEncoding: 'ieee-p1363', // default (WebCrypto); use 'der' for most KMS / HSM APIs
+})
+```
+
+Defaults: `basicConstraints` `cA=false` and `keyUsage` `digitalSignature` for end-entity certificates, and
+`keyCertSign, crlSign` for CAs. Both are marked critical. The authority key identifier is taken from the issuer
+certificate. Custom extensions can be appended through `extensions`.
+
+For keys in a separate system, split creation into two steps:
+
+```typescript
+const prepared = await prepareCertificate(template)
+const signature = await remoteSigningService.sign(prepared.tbs)
+const cert = assembleCertificate(prepared, signature, 'der')
+```
+
+## CRLs
+
+### Parsing and checking revocation
+
+```typescript
+import { checkRevocation, parseCrl } from '@owf/x509'
+
+// Fetch the CRL yourself, e.g. from cert.crlDistributionPoints
+const crl = parseCrl(new Uint8Array(await (await fetch(cert.crlDistributionPoints[0])).arrayBuffer()))
+
+const status = await checkRevocation({ certificate: cert, crl, crlIssuerCertificate: issuerPem, verifier })
+// { status: 'good' }
+// { status: 'revoked', revocationDate, reason?, invalidityDate? }
+// { status: 'unknown', reason, message }
+```
+
+`checkRevocation` verifies the CRL signature first. The CRL issuer's key usage has to allow `cRLSign` if it is present.
+Then it returns `unknown` instead of guessing in these cases:
+
+| Reason | When |
+|--------|------|
+| `invalid_signature` | The CRL signature does not verify, or the CRL is not issued by the given certificate |
+| `issuer_mismatch` | The CRL is not issued by the certificate issuer, or is signed by a different key |
+| `crl_not_yet_valid` / `crl_expired` | `now` is before `thisUpdate` or after `nextUpdate` |
+| `out_of_scope` | The issuing distribution point excludes the certificate (user/CA/attribute only, different distribution point, only some reasons) |
+| `delta_crl` | The CRL is a delta CRL, which needs its base CRL |
+| `unsupported_critical_extension` | The CRL or the matching entry has a critical extension this package does not understand |
+
+Indirect CRLs (with `certificateIssuer` entries) are supported. Entries with reason `removeFromCRL` count as not
+revoked. `getRevocationStatus(cert, crl)` performs the same lookup without checking the signature, for CRLs you have
+already verified.
+
+`parseCrl` limits the number of entries to 100 000 by default, to protect against resource exhaustion by untrusted
+input. Raise it with `parseCrl(input, { maxEntries })`.
+
+### Creating
+
+```typescript
+import { createCrl } from '@owf/x509'
+
+const crl = await createCrl({
+  issuerCertificate: caPem,
+  thisUpdate: new Date(),
+  nextUpdate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+  crlNumber: 42n,
+  signatureAlgorithm: 'ES256',
+  revokedCertificates: [{ serialNumber: '0badc0de', revocationDate: new Date(), reason: 'keyCompromise' }],
+  issuingDistributionPoint: { distributionPointUris: ['https://ca.example.com/crl'], onlyContainsUserCerts: true },
+  signer,
+})
+
+crl.pem // -----BEGIN X509 CRL-----
+```
+
+`prepareCrl` / `assembleCrl` provide the same two-step flow as for certificates.
+
+## Out of scope
+
+- Certification path building and validation (RFC 5280 clause 6)
+- OCSP
+- Certificate signing requests