From eec1b6250914a6047e0c2801cff6b220942efade Mon Sep 17 00:00:00 2001
From: Paul Miller <paul@paulmillr.com>
Date: Thu, 19 Oct 2023 17:07:30 +0000
Subject: [PATCH] Readme: upgrades from micro-aes-gcm

---
 README.md | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c73730c..b81795d 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,7 @@ import { xchacha20poly1305 } from '@noble/ciphers/chacha';
   - [AES internals and block modes](#aes-internals-and-block-modes)
 - [Security](#security)
 - [Speed](#speed)
+- [Upgrading](#upgrading)
 - [Contributing & testing](#contributing--testing)
 - [Resources](#resources)
 
@@ -447,9 +448,9 @@ Use low-level libraries & languages. Nonetheless we're targetting algorithmic co
 We're deferring to built-in
 [crypto.getRandomValues](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)
 which is considered cryptographically secure (CSPRNG).
-In the past, browsers had bugs that made it weak: it may happen again.
 
-Implementing a userspace CSPRNG to get resilient to getRandomValues weakness
+In the past, browsers had bugs that made it weak: it may happen again.
+Implementing a userspace CSPRNG to get resilient to the weakness
 is even worse: there is no reliable userspace source of quality entropy.
 
 ## Speed
@@ -570,6 +571,36 @@ gcm-256 (encrypt, 1MB)
 └─noble x 74 ops/sec @ 13ms/op
 ```
 
+## Upgrading
+
+Upgrade from `micro-aes-gcm` package is simple:
+
+```js
+// prepare
+const key = Uint8Array.from([
+  64, 196, 127, 247, 172, 2, 34, 159, 6, 241, 30,
+  174, 183, 229, 41, 114, 253, 122, 119, 168, 177,
+  243, 155, 236, 164, 159, 98, 72, 162, 243, 224, 195,
+]);
+const message = 'Hello world';
+
+// previous
+import * as aes from 'micro-aes-gcm';
+const ciphertext = await aes.encrypt(key, aes.utils.utf8ToBytes(message));
+const plaintext = await aes.decrypt(key, ciphertext);
+console.log(aes.utils.bytesToUtf8(plaintext) === message);
+
+// became =>
+
+import { gcm } from '@noble/ciphers/aes';
+import { bytesToUtf8, utf8ToBytes } from '@noble/ciphers/utils';
+import { managedNonce } from '@noble/ciphers/webcrypto/utils';
+const aes = managedNonce(gcm)(key);
+const ciphertext = aes.encrypt(utf8ToBytes(message));
+const plaintext = aes.decrypt(key, ciphertext);
+console.log(bytesToUtf8(plaintext) === message);
+```
+
 ## Contributing & testing
 
 1. Clone the repository