docs: document the +cric cryptosuite that replaced +crub in Ames and Jael

content/hoon/cryptography.md

@@ -21,12 +21,52 @@ Documentation for [Insecure Hashing](stdlib/2e.md) and the [SHA Hash Family](std
 
 ## Summary {#summary}
 
-`zuse` contains several cryptosuites. The ones utilized by Ames are [`+ed:crypto`](#ed), [`+aes:crypto`](#aes), and [`+crub:crypto`](#crub), with the latter being the only one which is implemented as an [`+acru:ames`](../urbit-os/kernel/ames/cryptography.md#crypto-core)-shaped core.
+`zuse` contains several cryptosuites. The ones utilized by Ames are [`+ed:crypto`](#ed), [`+aes:crypto`](#aes), and [`+cric:crypto`](#cric).
+
+[`+crub:crypto`](#crub) is the older suite and still exists in `zuse`, but Ames no longer uses it: at the current kernel there are no references to `+crub` anywhere in `sys/vane/ames.hoon`. Jael likewise builds keys through `+cric` (`pit:nu:cric:crypto`, `nol:nu:cric:crypto`).
+
+## `+cric:crypto` {#cric}
+
+`+cric:crypto` is the cryptosuite Ames and Jael use. Unlike `+crub`, which is
+fixed to Suite B, `+cric` is a door over a tagged payload and can carry either
+suite:
+
+```hoon
+++  cric
+  |_  $%  $:  suite=%b
+              pub=[cry=@ sgn=@ ~]
+              sek=$@(~ [sed=@ cry=@ sgn=@])
+          ==
+          $:  suite=%c
+              pub=[cry=@ sgn=@ tw=[ugn=@ dat=@ xtr=@]]
+              sek=$@(~ [sed=@ cry=@ sgn=@])
+          ==
+      ==
+```
+
+The `%b` case corresponds to [Suite B Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography),
+as `+crub` did; the `%c` case carries the additional `tw` material for Suite C.
+
+It contains four sub-cores:
+
+- `+as:cric` — asymmetric operations: `+sign`, `+sigh`, `+sure`, `+safe`, `+seal`, `+tear`.
+- `+ex:cric` — extraction: `+fig`, `+pac`, `+pub`, `+sec`, `+ven`, `+ded`, `+saf`, `+cry`, `+sgn`, `+num`.
+- `+nu:cric` — construction: `+pit` (create keypair), `+nol` (activate secret), `+com` (activate public).
+- `+cyf:cric` — symmetric encryption: `+de`, `+dy`, `+en`.
+
+Note that the symmetric arms live under `+cyf`, where `+crub` had them at the
+top level: what was `+en:crub:crypto` is now `+en:cyf:cric:crypto`.
+
+The suite in use for a given ship's keys is recorded on Azimuth as the
+`crypto-suite` field of [`$key-update:point`](../urbit-os/kernel/jael/data-types.md#key-updatepoint).
 
 ## `+crub:crypto` {#crub}
 
 `+crub:crypto` implements an [`+acru:ames`](../urbit-os/kernel/ames/cryptography.md#crypto-core) core that implements [Suite B Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
 
+It is superseded by [`+cric:crypto`](#cric) and is no longer used by Ames or
+Jael, but remains in `zuse` and is documented here.
+
 It utilizes AES symmetric key encryption and decryption from [`+aes:crypto`](#aes) implemented using the Diffie-Hellman key exchange protocol, elliptic curve digital signature algorithm (ECDSA) signing and verification with [`+ed:crypto`](#ed), and generates public/private key pairs using elliptic curve cryptography with `+ed:crypto`.
 
 A `+crub:crypto` core's payload contains public encryption and authentication keys and optional secret encryption and authentication keys.
@@ -174,6 +214,6 @@ Most gates in `+ed:crypto` are [jetted](../build-on-urbit/runtime/jetting.md), m
 
 ## `+aes:crypto` {#aes}
 
-This core contains cryptographic primitives and helper functions for [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric key encryption and decryption. As is the case with `ed:crypto`, these functionalities are utilized by [`+crub:crypto`](#crub), and most gates are jetted. See also the Vere documentation on [AES SIV](../build-on-urbit/runtime/cryptography.md#aes) for more information about the library utilized by jets.
+This core contains cryptographic primitives and helper functions for [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) symmetric key encryption and decryption. As is the case with `ed:crypto`, these functionalities are utilized by [`+cric:crypto`](#cric) and [`+crub:crypto`](#crub), and most gates are jetted. See also the Vere documentation on [AES SIV](../build-on-urbit/runtime/cryptography.md#aes) for more information about the library utilized by jets.
 
 This core contains several doors, each one used for a different variation of AES according to key size and mode. The only ones currently in use are `+siva:aes:crypto` and `+sivc:aes:crypto`, which are 128-bit and 256-bit modes of [`AES-SIV`](https://www.aes-siv.com) respectively.

content/urbit-os/kernel/ames/cryptography.md

@@ -29,23 +29,25 @@ The `$ames-state` includes a [`+acru:ames`](cryptography.md#crypto-core) core, a
 
 Each Urbit ship possesses two networking keypairs: one for encryption, and one for authentication. We often refer to these two keypairs as though they were a single keypair because they are stored as a single atom. [Elliptic Curve Diffie-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman) is used for encryption, while [Elliptic Curve Digital Signature Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) is used for authentication
 
-The encrypted payload of each packet is a `$shut-packet`, which is the `+jam` of a cell with the [$bone](data-types.md#bone), message number, and message fragment or ack (see [Ames](README.md) for more information on packet structure). The message fragment is signed using the authentication key. It is encrypted using [`+en:crub:crypto`](../../../hoon/cryptography.md#en) found in `sys/zuse.hoon`, which utilizes the 256-bit AES-SIV algorithm.
+The encrypted payload of each packet is a `$shut-packet`, which is the `+jam` of a cell with the [$bone](data-types.md#bone), message number, and message fragment or ack (see [Ames](README.md) for more information on packet structure). The message fragment is signed using the authentication key. It is encrypted using [`+en:cyf:cric:crypto`](../../../hoon/cryptography.md#cric) found in `sys/zuse.hoon`, which utilizes the 256-bit AES-SIV algorithm.
 
 ## Diffie-Hellman key exchange <a href="#key-exchange" id="key-exchange"></a>
 
 For each foreign ship a given ship has communicated with, `$ames-state` contains a [`$peer-state`](./data-types.md#peer-state), inside which the [`$symmetric-key`](data-types.md#symmetric-key) (an atom which nests under `@uw`) is utilized for encrypting all Ames packets shared between the two ships. The `$symmetric-key` is derived using [`+shar:ed:crypto`](../../../hoon/cryptography.md#ed) found in `/sys/zuse.hoon`, which is an arm utilized for generating the symmetric key for elliptic curve [Diffie-Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) with [curve25519](https://en.wikipedia.org/wiki/Curve25519). Briefly, each ship in a two-way conversation computes the shared symmetric key for that conversation by computing the product of their own private key and the public key of the other party.
 
 ## Comet self-attestation <a href="#comets" id="comets"></a>
 
-Recall that the `@p` of a comet is the hash of their 128-bit public key cast as a `@p`. Since the public key of a comet is not stored on Azimuth, a comet proves its identity with an "attestation packet". This is an unencrypted packet whose payload is the comet's signature created with its private key. This is the only circumstance under which a ship will send an unencrypted packet. The signature is generated with [`+sign:as:crub`](../../../hoon/cryptography.md#sign-as) found in `sys/zuse.hoon`.
+Recall that the `@p` of a comet is the hash of their 128-bit public key cast as a `@p`. Since the public key of a comet is not stored on Azimuth, a comet proves its identity with an "attestation packet". This is an unencrypted packet whose payload is the comet's signature created with its private key. This is the only circumstance under which a ship will send an unencrypted packet. The signature is generated with [`+sign-raw:ed:crypto`](../../../hoon/cryptography.md#ed) found in `sys/zuse.hoon`, using the signing keypair directly (`+etch-open-packet` in `sys/vane/ames.hoon`).
 
 Upon hearing an attestation packet, the receiving ship will generate a symmetric key for communications with the comet, according to the [key exchange](#key-exchange) protocol.
 
 The fact that the first packet exchanged between a comet and another ship must be an attestation packet is why comets are unable to initiate communication with one another, and also why comets must be the first to initiate communication with a non-comet. This is a technical limitation with a planned workaround.
 
 ## `+acru:ames` <a href="#crypto-core" id="crypto-core"></a>
 
-The `+crypto-core` in `$ames-state` is an `+acru:ames` core, a [lead](../../../hoon/advanced.md#dry-polymorphism-and-core-nesting-rules) interface core for asymmetric cryptosuites found in `sys/lull.hoon` which handles encryption, decryption, signing, and verifying. In practice, the only cryptosuite in use is [`+crub:crypto`](../../../hoon/cryptography.md#crub), which implements [Suite B Cryptography](https://en.wikipedia.org/wiki/NSA_Suite_B_Cryptography).
+`+acru:ames` is a [lead](../../../hoon/advanced.md#dry-polymorphism-and-core-nesting-rules) interface core for asymmetric cryptosuites, found in `sys/lull.hoon`, which handles encryption, decryption, signing, and verifying. The cryptosuite in use is [`+cric:crypto`](../../../hoon/cryptography.md#cric); `+crub:crypto` is no longer referenced by Ames.
+
+Note that Ames no longer stores a crypto core in its state. Earlier versions of `$ames-state` held a `crypto-core` field, and `sys/vane/ames.hoon` still defines `+acru-12` and `+acru-25` shapes — but those exist only to type *previous* states during a migration. The current `+$ axle` (`sys/lull.hoon`) instead stores the key material directly, as `[saf=keypairs =ring =pass]`, where `+$ keypairs` is `[pub=public-keys sek=private-keys]`.
 
 ```hoon
   ++  acru  $_  ^?                                      ::  asym cryptosuite
@@ -73,7 +75,7 @@ The `+crypto-core` in `$ames-state` is an `+acru:ames` core, a [lead](../../../h
     --  ::acru                                          ::
 ```
 
-As the `+acru` core is merely an interface, the details on how it is implemented may vary according to the cryptosuite. We summarize what each core is utilized for here, but see [`crub:crypto`](../../../hoon/cryptography.md#crub) for more details on how the specific cryptosuite utilized by Ames is implemented.
+As the `+acru` core is merely an interface, the details on how it is implemented may vary according to the cryptosuite. We summarize what each core is utilized for here, but see [`cric:crypto`](../../../hoon/cryptography.md#cric) for more details on how the specific cryptosuite utilized by Ames is implemented.
 
 #### `+as:acru`
 

content/urbit-os/kernel/jael/data-types.md

@@ -150,7 +150,7 @@ Structures for points (Ship IDs in Azimuth).
   ==
 ```
 
-Public key data for a particular ship. The `rift` is the current continuity breach number and `$life` is the current key revision number. The `.keys` `+map` contains the public key (`.pass`) for each `$life` up to the current one. The `.sponsor` is the current sponsor of the ship in question, if it has one.
+Public key data for a particular ship. The `rift` is the current continuity breach number and `$life` is the current key revision number. The `.keys` `+map` contains, for each `$life` up to the current one, the public key (`.pass`) and the `crypto-suite` version number identifying which cryptographic suite that key belongs to. The `.sponsor` is the current sponsor of the ship in question, if it has one.
 
 ### `$key-update:point` {#key-updatepoint}