Here we give a technical overview of how Ames implements cryptography.
By default, all packets are encrypted with 256-bit AES symmetric key encryption, whose key is obtained by Diffie-Hellman key exchange, with public/private keys generated using elliptic curve Curve25519. The only exception to this are comet self-attestation packets, which are unencrypted.
All packets are also signed using Elliptic Curve Digital Signature Algorithm.
$ames-state includes a
+acru:ames core, an interface
core into which one of the cryptosuites in
zuse may be implemented. Some, but
not all, of the calls to cryptography-related tasks (encryption, signing,
decrypting, and authenticating) are peformed utilizing the
Packet encryption and authentication
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 is used for encryption, while Elliptic Curve Digital Signature Algorithm is used for authentication
The encrypted payload of each packet is a
$shut-packet, which is the
a cell with the
bone, message number, and message fragment or ack (see
Ames for more information on packet structure). The
message fragment is signed using the authentication key. It is encrypted using
+en:crub:crypto found in
sys/zuse.hoon, which utilizes the 256-bit AES-SIV algorithm.
Diffie-Hellman key exchange
For each foreign ship a given ship has communicated with,
$ames-state contains a
$peer-state, inside which the
$symmetric-key (an atom which nests under
@uw) is utilized for encrypting all Ames packets shared between the two ships.
symmetric-key is derived using
+shar:ed:crypto found in
which is an arm utilized for generating the symmetric key for elliptic curve
with 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.
Recall that the
@p of a comet is the hash of their 128-bit public key cast as
@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 found in
Upon hearing an attestation packet, the receiving ship will generate a symmetric key for communications with the comet, according to the 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.
$ames-state is an
+acru:ames core, a
interface core for asymmetric cryptosuites found in
handles encryption, decryption, signing, and verifying. In practice, the only
cryptosuite in use is
+crub:crypto, which implements Suite B
++ acru $_ ^? :: asym cryptosuite |% :: opaque object ++ as ^? :: asym ops |% ++ seal |~([a=pass b=@] *@) :: encrypt to a ++ sign |~(a=@ *@) :: certify as us ++ sure |~(a=@ *(unit @)) :: authenticate from us ++ tear |~([a=pass b=@] *(unit @)) :: accept from a -- ::as :: ++ de |~([a=@ b=@] *(unit @)) :: symmetric de, soft ++ dy |~([a=@ b=@] *@) :: symmetric de, hard ++ en |~([a=@ b=@] *@) :: symmetric en ++ ex ^? :: export |% ++ fig *@uvH :: fingerprint ++ pac *@uvG :: default passcode ++ pub *pass :: public key ++ sec *ring :: private key -- ::ex :: ++ nu ^? :: reconstructors |% ++ pit |~([a=@ b=@] ^?(..nu)) :: from [width seed] ++ nol |~(a=ring ^?(..nu)) :: from ring ++ com |~(a=pass ^?(..nu)) :: from pass -- ::nu :: -- ::acru ::
+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 for more details on
how the specific cryptosuite utilized by Ames is implemented.
This core is used for the standard asymmetric cryptographic operations: encrypting
+seal), signing (
+sign), authenticating (
+sure), and decrypting (
This core is used to extract keys and their fingerprints.
+sec is the secret key (which
may be empty),
+pub is the public key associated to the secret key,
the fingerprint associated to the secret key, and
+fig is the fingerprint
associated to the public key. We note that when the core contains both
encryption and authentication keys, they are typically concatenated to be
returned as a single atom.
This core contains constructors for the
+pit:nu is used to
+acru core with both a private and public key (i.e. both
+pub:ex are set) from a bitlength and seed.
+nol:nu can then be
called from an
+acru core created with
+pit:nu to get an
+acru core with
only the secret key, while
+com:nu can be called to get an
+acru core with
only the public key.
These arms are for symmetric encryption (
+en) and decryption (
+dy). The difference between the decryption arms is that
+de returns null
+dy crashes upon failure.