diff --git a/README.md b/README.md index 3920f0e78..45f3b16a3 100644 --- a/README.md +++ b/README.md @@ -44,13 +44,13 @@ npm install @hpke/core Following extensions can be installed in the same manner: -- `@hpke/core` - `@hpke/chacha20poly1305` - `@hpke/dhkem-x25519` - `@hpke/dhkem-x448` - `@hpke/dhkem-secp256k1` - `@hpke/hybridkem-x25519-kyber768` - `@hpke/hybridkem-x-wing` +- `@hpke/ml-kem` Then, you can use it as follows: @@ -117,6 +117,7 @@ The hpke-js includes the following packages. | @hpke/dhkem-x448 | [![npm](https://img.shields.io/npm/v/@hpke/dhkem-x448?color=%23EE3214)](https://www.npmjs.com/package/@hpke/dhkem-x448)
[![JSR](https://jsr.io/badges/@hpke/dhkem-x448)](https://jsr.io/@hpke/dhkem-x448) | The HPKE module extension for DHKEM(X448, HKDF-SHA512).
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/dhkem-x448/README.md) / [samples](https://github.com/dajiaji/hpke-js/tree/main/packages/dhkem-x448/samples) | | hpke-js | [![npm](https://img.shields.io/npm/v/hpke-js?color=%23EE3214)](https://www.npmjs.com/package/hpke-js) | The HPKE module supporting all of the ciphersuites defined in [RFC9180](https://datatracker.ietf.org/doc/html/rfc9180), which consists of the above @hpke/{core, dhkem-x25519, dhkem-x448, chacha20poly1305} internally.
[README](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/README.md) / [samples](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/samples) | | @hpke/hpke-js | [![JSR](https://jsr.io/badges/@hpke/hpke-js)](https://jsr.io/@hpke/hpke-js) | The JSR version of the above `hpke-js`.
[README](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/README.md) / [samples](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/samples) | +| @hpke/ml-kem | [![npm](https://img.shields.io/npm/v/@hpke/ml-kem?color=%23EE3214)](https://www.npmjs.com/package/@hpke/ml-kem)
[![JSR](https://jsr.io/badges/@hpke/ml-kem)](https://jsr.io/@hpke/ml-kem) | **EXPERIMENTAL AND NOT STANDARDIZED**
The HPKE module extension for [ML-KEM](https://datatracker.ietf.org/doc/draft-connolly-cfrg-hpke-mlkem/).
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/ml-kem/README.md) / [samples](https://github.com/dajiaji/hpke-js/tree/main/packages/ml-kem/samples) | | @hpke/hybridkem-x-wing | [![npm](https://img.shields.io/npm/v/@hpke/hybridkem-x-wing?color=%23EE3214)](https://www.npmjs.com/package/@hpke/hybridkem-x-wing)
[![JSR](https://jsr.io/badges/@hpke/hybridkem-x-wing)](https://jsr.io/@hpke/hybridkem-x-wing) | **EXPERIMENTAL AND NOT STANDARDIZED**
The HPKE module extension for [X-Wing: general-purpose hybrid post-quantum KEM](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/).
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/hybridkem-x-wing/README.md) / [samples](https://github.com/dajiaji/hpke-js/tree/main/packages/hybridkem-x-wing/samples) | | @hpke/hybridkem-x25519-kyber768 | [![npm](https://img.shields.io/npm/v/@hpke/hybridkem-x25519-kyber768?color=%23EE3214)](https://www.npmjs.com/package/@hpke/hybridkem-x25519-kyber768)
[![JSR](https://jsr.io/badges/@hpke/hybridkem-x25519-kyber768)](https://jsr.io/@hpke/hybridkem-x25519-kyber768) | **EXPERIMENTAL AND NOT STANDARDIZED**
The HPKE module extension for the hybrid post-quantum KEM currently named [X25519Kyber768Draft00](https://datatracker.ietf.org/doc/draft-westerbaan-cfrg-hpke-xyber768d00/).
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/hybridkem-x25519-kyber768/README.md) / [samples](https://github.com/dajiaji/hpke-js/tree/main/packages/hybridkem-x25519-kyber768/samples) | | @hpke/dhkem-secp256k1 | [![npm](https://img.shields.io/npm/v/@hpke/dhkem-secp256k1?color=%23EE3214)](https://www.npmjs.com/package/@hpke/dhkem-secp256k1)
[![JSR](https://jsr.io/badges/@hpke/dhkem-secp256k1)](https://jsr.io/@hpke/dhkem-secp256k1) | **EXPERIMENTAL AND NOT STANDARDIZED**
The HPKE module extension for DHKEM(secp256k1, HKDF-SHA256).
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/dhkem-secp256k1/README.md) / [samples](https://github.com/dajiaji/hpke-js/tree/main/packages/dhkem-secp256k1/samples) | @@ -138,6 +139,9 @@ The hpke-js includes the following packages. | DHKEM (P-521, HKDF-SHA512) | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | DHKEM (X25519, HKDF-SHA256) | ✅
hpke-js
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/dhkem-x25519 | | DHKEM (X448, HKDF-SHA512) | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | +| ML-KEM-512 | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | +| ML-KEM-768 | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | +| ML-KEM-1024 | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | | X-Wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | | Hybrid KEM (X25519, Kyber768) | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | | DHKEM (secp256k1, HKDF-SHA256) | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | diff --git a/packages/ml-kem/CHANGES.md b/packages/ml-kem/CHANGES.md index b671f0bbc..016edc9af 100644 --- a/packages/ml-kem/CHANGES.md +++ b/packages/ml-kem/CHANGES.md @@ -1 +1,5 @@ # Changes + +Released 2024-11-10 + +- First public preview release. diff --git a/packages/ml-kem/README.md b/packages/ml-kem/README.md index 96f6e954e..50cdb598a 100644 --- a/packages/ml-kem/README.md +++ b/packages/ml-kem/README.md @@ -5,7 +5,7 @@
-A TypeScript Hybrid Public Key Encryption (HPKE) module extension for X-Wing: general-purpose hybrid post-quantum KEM. +A TypeScript Hybrid Public Key Encryption (HPKE) module extension for ML-KEM for HPKE.

@@ -34,23 +34,24 @@ async function doHpke() { const jwkPub = { kty: "AKP", kid: "01", - alg: "X-Wing", + alg: "ML-KEM-768", pub: - "4iNrNajCSzmxCqEyOpapGaLO2IQAYzp7BxMXE_wUsrWxnPw9pfoaksSfJVE-D9MNaxYRyauWNdcIZyekt9IdNCROZpac8Vs7KnhTKfYbCWsnfqA3ODR5prVW3nIx_kt_qcmsJMBpmgAYpSU0AbrPqQXKgWVz5WotLgZ-m3KHUzuhOpN97bMfpEus7UB2mSNhADSuMeYZoXAkUZmzxcOYZIWf4bTJcXoHwwSVvfuYoKACzPVsEobO9QQd7ePETPFr9WLHRIUYAms9i5lAaAq9OKFXX9J7WNoGO_rDLDnDCGk3TAXBrrGJi2swPMaL5FU0buCvaZY2IkoUjKKuoQRjERxwn2m2nHDOhTh0ZpjExgqa7wAwx5JM7sQqXTaBb1RerhMpNGCzrLN-oOE9cOSqeGhto5ioOXwI6vloghE_5Pe61NpAsFAeHHU-_nMFPIcBToZhwzCZr-i-3kFKWxqifYOSs-Ex6acMEFWHgkDK0PQNX-PN-FI26tl-KpdEg2OygIyq_VFs0lBSxcNiVDwlF-Ss0OYOwHFjAJtkJfwyJ3rO5xwkurU-2fKedMZqCjVklVmY12uWqai1DRY1pNemfrQt9WRNMwRXKTqAQvU8x6aSiPF-1Vgn6Cso6CZlqGoU-9lmReyoFywET4O8DYwLTIYmmFYxyoevgpBo8TWJY8szNmTKSCdjujs7sghXf5umrGLCX3ZZJ0O2S-UZMXcUy0ECy3svmiWytPBhXeMd7NnKVQJtbaC2URGxb-Uv7tikh-FERiptupNyj1ALb_xJ5RVWnvJf7Rev9SBQc2glNSWGD1i-O-YclkYEpqyBTmk1WWQCpSCkZws9KEMYhmWT0VpLsBw14-WH7gxn0ogNbyQH-3pwcSuDjeuWxde_K0S89gOMy-M_vPUaVKWE_pAIPJHHptQ9T7FfSMYML9ZuCoqtStZOXEK7iHfA6-wrXjh8ipiP3CO-ueFsh1d4HgoUmcYeE4wh8hbCnQdpeYccqmlCuvwJBUS-6ZtUsWy5qaNk1iRtn0LM5TxmtZxFyPmukpmnXRUYDDyVIVGpG3oQdyQp3Ey65vzGIvqAGMY0OfiQYwuZKNtrt_lDiuQGXtNNc9SG8_UvkPCAfciN_djHKOlU8aw1wGwADOQaBYJYDju1e2cpcokKxeeYjnhQZXEW8bV9CAmq7ewL7eGuFIFIMRxvfjFzRuUYn7jNY1uYb4wL3SdkHFhLd4s6kRqAvhyWkquOG7sSg5VzzOGd8YO0WDW7tVBS-fxmoWeO8qNt6nhBHmyNYFAbTmBZLRNpipQ7UJGF25EuLqEL4GFxI2syfHFxYJTJZKaLAzd_UToFvNmcHzRlg7sFKXehChKt_HWANOVhfaTBJ2WF5XdOHzuZeLCdDpxE07yGFRxDqtGFcScXNAIjrDgdIRUKBClOl7sTu9ohtaGCttqWnhmn_QcnN_qOiApTwkKOPQSbfSGXQFKW3bNhkSp7z0gnztYR0Men2hBN3kMiCVM59kph1bsQj_C_TXgMrlCfsiwlaRQZP_c0kEJYEjfVIoKIJO4739B_sD8flC0uoXn-ci8GzAPeW2mFntsG7_OJsn3OWYRFcCFiI1k9S6MtmrrIzQSQQO9lNA", + "PxuKXPWqDLFIz6x2ajCnggmjzpfLQnqegTJU4LapmuJTcLWDwnU1fOO01sYKr9oD6Zc04OmOulau74IekrjB20OUKnw3yZd9eZRv4EdN8nuc87EsqUuwZAHQkVBTC_gq38RiO9evl0JZhLjFP1GWnrwC2bQarOeVNuMoKvWt7bY2PUp727BqaeJMiSiI9nEAVbtkTbYLo7iEIEwDsHwqisoCSawp6td9XIeaeQoJuFClXvYUzHPPf3JyI7oNY1MpXACMmGqpIANJoKxQDjR-4XlaGoNpq2FRwnsTQcrOVoUu52xtPMuDMbI83osiSvmy3uQC2WBbv6hAGXZBnFerFoa9oJayjLZUzUpdt8MlmOAUkeIbjNVEl_YP4rwx14OSjjgr-_MzK3VM-WmxKqWPQ4tKVwZBKdRFYAmhcqWas7d8yEx2lEuZpTRFpSmsCmKtSQF0pHMkpdNLgaaCppwKjddfDek8IOQwJmwjsAxIafU8b9CFTtPK9FRJUrBe07Ow1so08PKX8umnwRh4BKN6Ehpq0qtQ2vR1qjol5smg1qKd72LL0pgFD1swfAU6XIg4tMM1fzN2ZTwzZvpv4QJdGWDHW6ZDJlwVeoTJFNVZ9UDGfsFYc5Sve9F4MNUInVBZBvqfdmqbk5CfW2YnzAWgshksv8InGwsi13oHzlUe2qZSLUArAAA3I8EVk2yX9UyIqlE0gqBVVMYo5pRI62oO9vNGNByAK9q5sDugryl9nouTi5yr76RnIkIaM4qHLZqIuIyfDuxGkyw2fMWLg1c9JgNqr1J25RWw8jBZtAyEj2OKzjcD7mwn2WaZDHcC7SOgzZukz2Fppmih8LtYawdmkuHCFXVP9nhL2RokjLkPAIo-ylmFLAV5ZpM6Goa24FsvrZGyi8YWSLBBp6wEargRK2rCy5APtcCYIdxLBxa1CeEi3JfG7XNC9vSftlVZcpw4R2O6LSu4z1auNvOyaZcKxUhBITskt5LJSfPHdecKyPfMU3Y_9jitxRE-xgB1waeSdspHPBE4MpVKviB76_DNBCbA4pczlHJWx3Vr-bUNghkaB_C6XVoVSwhm4pNHO0B2oemV-dCGpHLBGKwiwhaoOZIGYKMx7uGY31saFZUjnVeAzadfc8Z2WkauSqNAAZOd-tkvfhJKXyxiiyWd6VYLv0cMxpzGUtwpuTuoakmQ3OCvGkUkwZmmkmcMr3SNFmEv7tcR-IpQXVUqZECqBCJibxhfaSGoLvklCGAoroVi_HYQ4bFknvAJTZa1Bfu38RKJbvrA0ZKvRdkDrHmSu-m_MOJXfiRYHLxPc7GA0Epp9UCznhmkrjauxPIa3ndJZTkbyuvAr4actjYxMntCG-xnJmUbh1i_7nPFkSEtT_mB9mhMWLNZwtB_oeYB1sXL_clksxkJzKN__5YgT7VojZLKWoV1jPFg6bBu0YMgpLGwyOgZaudqb2IZctF6TWSn3wTFpMMzw7wayqs3cJFJo7jKCCqPvKEyaKGwIiMOLWMCcsuf8uZlWvFzJ_O5gHCV9YK-GL0_Tgu3I-ztabBYVimYZUjXIrA7W70Vesmd7hwKmqE", key_ops: [], }; const pk = await suite.kem.importKey("jwk", jwkPub, true); // In addition to importing keys from external sources, you can also generate keys as follows: // const rkp = await suite.kem.generateKeyPair(); - // const rkp = await suite.kem.deriveKeyPair(random32bytesValue); + // const rkp = await suite.kem.deriveKeyPair(random64bytesValue); const sender = await suite.createSenderContext({ recipientPublicKey: pk }); const jwkPriv = { kty: "AKP", kid: "01", - alg: "X-Wing", - priv: "f5wrpOiPgn1hYEVQdgWFPtc7gJP277yI6xpurPpm7yY", + alg: "ML-KEM-768", + priv: + "1pz8ZPhNTzPkxU4Wa3_5KDo5SYalObI5h6EPOdLZaJtt5i40ZaVcnHigfSZb6FQLPliwgBoSTQf_ErQ41SAuoA", key_ops: ["deriveBits"], }; const sk = await suite.kem.importKey("jwk", jwkPriv, false); @@ -188,7 +189,7 @@ async function doHpke() { const rkp = await suite.kem.generateKeyPair(); - // Note that the `ct` (ciphertext) resulting from X-Wing Encapsulate() is set to `sender.enc`. + // Note that the `ct` (ciphertext) resulting from ML-KEM::Encaps() is set to `sender.enc`. const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, }); @@ -198,7 +199,7 @@ async function doHpke() { const recipient = await suite.createRecipientContext({ recipientKey: rkp.privateKey, - enc: sender.enc, // == `ct` (ciphertext) in the context of X-Wing + enc: sender.enc, // == `ct` (ciphertext) in the context of ML-KEM }); // decrypt @@ -231,7 +232,7 @@ async function doHpke() { const rkp = await suite.kem.generateKeyPair(); - // Note that the `ct` (ciphertext) resulting from X-Wing::Encapsulate() is set to `sender.enc`. + // Note that the `ct` (ciphertext) resulting from ML-KEM::Encaps() is set to `sender.enc`. const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, }); @@ -241,7 +242,7 @@ async function doHpke() { const recipient = await suite.createRecipientContext({ recipientKey: rkp.privateKey, - enc: sender.enc, // == `ct` (ciphertext) in the context of X-Wing + enc: sender.enc, // == `ct` (ciphertext) in the context of ML-KEM }); // decrypt @@ -282,7 +283,7 @@ try { const rkp = await suite.kem.generateKeyPair(); - // Note that the `ct` resulting from X-Wing::Encapsulate() is set to `sender.enc`. + // Note that the `ct` (ciphertext) resulting from ML-KEM::Encaps() is set to `sender.enc`. const sender = await suite.createSenderContext({ recipientPublicKey: rkp.publicKey, }); @@ -293,7 +294,7 @@ try { const recipient = await suite.createRecipientContext({ recipientKey: rkp.privateKey, // rkp (CryptoKeyPair) is also acceptable. - enc: sender.enc, // == `ct` (ciphertext) in the context of X-Wing + enc: sender.enc, // == `ct` (ciphertext) in the context of ML-KEM }); // decrypt