• Brooklyn Zelenka, Fission

• Daniel Holmgren, Bluesky
• Quinn Wilton, Fission
• Brooklyn Zelenka, Fission

Authorized Wire Authenticated Key Exchange (AWAKE) is an AKE built on top of the UCAN auth token. AWAKE is similar to other mutual authentication schemes (such as self-signed mTLS), but with a focus on authorization and proof. AWAKE leverages the UCAN capability chain to prove access to some resource, validating that the requestor is communicating with a party capable of performing certain actions. This is a helpful root of trust with a well defined context when establishing a secure communications channel.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

AWAKE bootstraps a secure session on top of a public channel. Key exchanges for point-to-point communication are plentiful, but in open, trustless protocols, rooting trust can be a barrier for ad hoc communications channels. Two common approaches are to use a trusted certificate authority, or ignore the principal and "merely" establish a point-to-point channel.

Capability-based systems have a helpful philosophy towards a third path. By emphasizing authorization over authentication, they provide a way to know something provable about what the other party "can do", even if they have no sure way of knowing "who they are". One way of phrasing this is that such an agent is "functionally equivalent to the principal in this context". AWAKE makes use of authorization to bootstrap point-to-point sessions that are both secure and mutually trusted.

This document contains shorthand (especially in diagrams) and nuanced senses of some terms. Below is a dictionary of AWAKE-specific terms:

Payloads are encoding agnostic, but JSON is RECOMMENDED. For JSON, any fields that contain non-JSON values (such as ECDH public keys and encryption payloads) MUST be serialized as unpadded Base64.

All payloads MUST include the "AWAKE version" field awv: "0.1.0". Payloads MUST also include a message type field type (see each stage for the value). All field keys and message type values MUST be lowercase and treated as case-sensitive.

Encryption is core to securing a tunnel. Key material and secrets created for AWAKE MUST be considered ephemeral and MUST NOT be reused between sessions.

At a high-level, AWAKE uses a NIST P-256 Elliptic Curve Diffie-Hellman (ECDH) Double Ratchet to secure messages.

UCAN MUST be used as the signature envelope for AWAKE. Any UCAN-compatible asymmetric key MAY be used for signatures, including RSA, Ed25519, P-256, and so on.

The ECDH portion of the Double Ratchet KDF MUST use P-256.

All symmetric encryption in AWAKE MUST use 256-bit AES-GCM. These keys MUST be generated by the KDF, and SHOULD be non-extractable where possible.

Each encrypted payload MUST include a unique (freshly generated) 12-byte initialization vector.

AWAKE uses HKDF to derive keys. Key derivation in AWAKE's double ratchet MUST use the following algorithms:

The Double Ratchet conceptually consists of three ratchets: a Diffie-Hellman (asymmetric) ratchet, and two chain ratchets: a Sending Chain (encryption) and a Receiving Chain (decryption).

The Sending Chain of the Requestor MUST always match the Receiving Chain of the Responder, and vice versa. The Diffie-Hellman ratchet is used to start a new epoch for the chain ratchets, "resetting" them with fresh starting values.

       High-Level Sketch
        Double Ratchet

               ⋮
               ⋮
               ▼
       ┌──────────────┐
       │              │
       │  DH Ratchet  │
       │              │
       └─┬──────────┬─┘
         │          │
         │          │
         ▼          ▼
┌───────────┐    ┌─────────────┐
│           │    │             │
│  Sending  │    │  Receiving  │
│  Chain 0  │    │   Chain 0   │
│           │    │             │
└────────┬──┘    └──┬──────────┘
         │          │
         │          │
         ▼          ▼
┌───────────┐    ┌─────────────┐
│           │    │             │
│  Sending  │    │  Receiving  │
│  Chain 1  │    │   Chain 1   │
│           │    │             │
└────────┬──┘    └──┬──────────┘
         │          │
         │          │
         ▼          ▼
┌───────────┐    ┌─────────────┐
│           │    │             │
│  Sending  │    │  Receiving  │
│  Chain 2  │    │   Chain 2   │
│           │    │             │
└───────────┘    └─────────────┘
         ⋮          ⋮
         ⋮          ⋮
         ▼          ▼

         Diffie-Hellman          Secret                      Message
            Ratchet               Chain                      Crypto
┌──────────────┴─────────────┐  ┌───┴───┐                 ┌────┴────┐
 Alice's P-256    Bob's P-256    Current
   Private Key    Public Key     Secret
            │      │                │
            │      │                │
      ┌─────┼──────┼────────────────┼────────────────┐
      │     │      │                │                │
      │     │      │                │                │
      │     ▼      ▼                ▼                │
      │    ┌────────┐          ┌────────┐            │
      │    │        │          │        │            │
      │    │  ECDH  ├─────────►│  HKDF  │            │
      │    │        │          │        │            │
      │    └────────┘          └────┬───┘            │
      │                             │                │
      │                             │                │
      │                             ▼                │
      │                        ┌─────────┐  512-603  │
      │                        │         ├───────────┼───► Unique IV
      │                        │  Split  │           │
      │                        │         ├───────────┼───► AES-Key
      │                        └────┬────┘  256-511  │      (OKM)
      │                             │                │
      │                             │ 0-255          │
      │                             │                │
      └─────────────────────────────┼────────────────┘
                                    │
                                    │
                                    ▼
                                  Next
                                 Secret

// JS-flavored Pseudocode

const ecdhSecret = ecdh(aliceSk, bobPk)
const awakeTag = 0x4157414B452D5543414E // "AWAKE-UCAN" as hex
const pseudorandomBits = hkdf.generateBits({ecdh, salt: currentSecret, info: awakeTag, bitLength: 256 + 256 + 96})
const [aesKey, nextSecret, iv] = pseudorandomBits.splitKeysAndIv()

The ECDH secret MUST be generated using NIST P-256 elliptic curve curve (AKA secp256r1). Non-extractable P-256 keys SHOULD be used where available (e.g. via the WebCrypto API). The sender MUST rotate their public key on every send. This does mean that in the message phase, multiple keys MAY be valid due to concurrency and out-of-order message delivery.

The updated secret MUST be generated from the first 32-bytes of the HKDF output. This new secret MUST be used as the input secret for the next message. Note that due to out-of-order message delivery, this secret MAY be used in up to one sent and one received message.

The one-time message key MUST be unique for every message since one Diffie-Hellman key will have changed, and the secret is updated per send or receipt.

This key MUST be generated from the second 32-byte segment of the HKDF output.

This key MUST be used to start the sender's Sending Chain, and the recipient's Receiving Chain.

Each message uses a unique initialization vector generated from the last 12-bytes of the HKDF output.

Note: This step MUST NOT be used during the AWAKE handshake.

Ratcheting a chain MUST be done by applying SHA-512 to the previous key or Diffie-Hellman KDF-generated secret.

SHA-512 will generate more bytes than are required. The unused trailing bytes MUST be discarded.

     Current
     Secret
        │
        │
        ▼
  ┌───────────┐
  │           │
  │  SHA-512  │
  │           │
  └─────┬─────┘
        │
        │
        ▼
   ┌─────────┐
   │         │
   │  Split  ├──────────► Unique IV
   │         │  256-351
   └────┬────┘
        │
        │ 0-255 
        │
        ▼
      Next
     Secret

// JS-flavored Pseudocode
const [nextSecret, iv, _] = sha2_512(currentSecret).splitKeyAndIv()

The Sender's Sending Chain MUST be derived from the first OKM in the Diffie-Hellman Step, and the Sender's Receiving Chain is derived from the Diffie-Hellman Step output secret. The mechanism is otherwise identical. The Receiver's chains MUST be identical to the Sender's, but with Sending/Receiving roles reversed.

AWAKE proceeds in one connection step, four communication rounds, and an OPTIONAL disconnection:

1. Both parties subscribe to a well-known channel
2. Requestor broadcasts intent
   • a. Temporary DID
   • b. Responder authorization criteria
3. Responder establishes point-to-point session
   • a. Responder securely proves that they have sufficient rights
   • b. Responder transmits a session key via asymmetric key exchange
4. Requestor authentication
   • a. Requestor sends actual DID
   • b. Requestor sends instance validation (e.g. UCAN or out-of-band PIN)
5. Responder sends an ACK
6. Secure session messages (zero or more rounds)
7. Either party disconnects

Attacker                 Requestor                  Responder
   │                         │                          │      ─┐
   │       Temp ECDH DID     │      Temp ECDH DID       │ (2a)  │
   │      & Auth Criteria    │     & Auth Criteria      │ (2b)  │
   │◄────────────────────────┼─────────────────────────►│       │
   │                         │                          │       │
   │                         │       Authorization      │ (3a)  │
   │                         │       & Secret Init      │ (3b)  │
   │                         │◄─────────────────────────┤       │
   │                         │                          │       ├─ Handshake
   │                         │        Actual DID        │ (4a)  │
   │                         │        & Challenge       │ (4b)  │
   │                         ├─────────────────────────►│       │
   │                         │                          │       │
   │                         │                          │       │
   │                         │           ACK            │ (5)   │
   │                         │◄─────────────────────────┤       │
   │                         │                          │      ─┘
   ϟ                         ϟ                          ϟ      ─┐
   │                         │                          │       │
   │                         │         Messages         │ (6)   ├─ Session
   │                         │◄────────────────────────►│       │
   │                         │                          │       │ 
   ϟ                         ϟ                          ϟ      ─┘
   │                         │                          │      ─┐
   │                         │           FIN            │ (7)   │
   │                         │◄────────────────────────►│       ├─ Disconnection
   │                         │                          │       │
   │                         ▀                          ▀      ─┘

AWAKE begins by all parties listening on a common channel. AWAKE itself is channel and transport agnostic; it MAY be broadcast to all listeners, MAY be asynchronous, and MAY be over any transport. To reduce channel noise, it is RECOMMENDED that this channel be scoped to a specific topic.

For instance, a WebSocket pubsub channel on the topic awake:did:key:zStEZpzSMtTt9k2vszgvCwF4fLQQSyA15W5AQ4z3AR6Bx4eFJ5crJFbuGxKmbma4 MAY be used for messages about resources owned by did:key:zStEZpzSMtTt9k2vszgvCwF4fLQQSyA15W5AQ4z3AR6Bx4eFJ5crJFbuGxKmbma4.

The AWAKE handshake MUST occur on a single channel. The underlying channel MAY be changed after the handshake is complete.

NOTE: This stage is completely in the clear.

Attacker                 Requestor                  Responder
   │                         │                          │ 
   │      Temp ECDH DID      │     Temp ECDH DID        │ (1a)
   │     & Auth Criteria     │    & Auth Criteria       │ (1b)
   │◄────────────────────────┼─────────────────────────►│
   ⋮                         ⋮                          ⋮

In this step, the Requestor broadcasts a temporary DID, and some criteria that a Responder MUST provide in §3.3. Both pieces of information are sent in a single message. This request payload MUST contain the did and caps fields. The caps field MAY be an empty array.

The payload stage MUST be signalled by the message type "awake/init".

Since this message is sent entirely in the clear, the Requestor MUST generate a fresh P-256 key pair per AWAKE initialization attempt. This key MUST be used as the first step in the ECDH Double Ratchet. In the payload, the public key MUST be formatted as a did:key.

This temporary key MUST only be used for key exchange, and MUST NOT be used for signatures, and MUST NOT be persisted past this one session bootstrap (i.e. discard after §3.3). It is RECOMMENDED that the private key be non-extractable when possible, such as via the WebCrypto API.

The Requestor MAY also include validation criteria expected from the Responder. This MUST be passed as an array of UCAN capabilities. The Responder MUST be able to prove access to these capabilities in §3.3.

{
  "awv": "0.1.0",
  "type": "awake/init",
  "did": "did:key:zDnaerx9CtbPJ1q36T5Ln5wYt3MQYeGRG5ehnPAmxcf5mDZpv",
  "caps": [
    {
      "with": "mailto:[email protected]",
      "can": "msg/send"
    },
    {
      "with": "dns:example.com",
      "can": "crud/update"
    },
    {
      "with": "owned://did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp/*",
      "can": "*"
    }
  ]
}

NOTE: The Responder is not yet trusted at this step, and MUST be treated as a possible impersonator or PITM

Requestor                  Responder
    ⋮                          ⋮
    │       Authorization      │ (3a)
    │       & Secret Init      │ (3b)
    │◄─────────────────────────┤
    ⋮                          ⋮

In this step, the Responder MUST prove that they have access to the requested resources. This is used to establish trust in the capabilities of the Responder, but MUST NOT actually delegate anything. This UCAN MUST contain the Requestor's temporary ECDH DID in the aud field. The iss field MUST contain the Responder's actual DID (i.e. not a temporary ECDH DID).

This step starts the Double Ratchet. The Responder MUST generate a fresh ECDH P-256 key pair. This MUST be combined with the Requestor's ECDH public key to generate a 256-bit AES key, which MUST be used to encrypt the private payload. The Requestor SHOULD accept multiple concurrent connection attempts on this request DID, at least until the handshake is complete.

The payload contains two encryption layers and a signature: the ECDH components, the AES envelope, and the capability proof signed by the Responder's "true" DID.

The SHA2 hash of the AES key generated in this step MUST be used as the first input secret in the KDF.

                 Payload

            ┌──────ECDH─────┐
            │               │
            │  256-bit AES  │
            │       │       │
            └───────┼───────┘
                    │
                    ▼
┌────────────────AES-GCM───────────────┐
│                                      │
│  ┌──────────────UCAN──────────────┐  │
│  │                                │  │
│  │  iss: Responder                │  │
│  │  aud: ReqECDH                  │  │
│  │  att: []                       │  │
│  │  fct: [nextResECDH, challenge] │  │
│  │  prf: ...                      │  │
│  │                                │  │
│  └────────────────────────────────┘  │
│                                      │
└──────────────────────────────────────┘

Upon receipt, the Requestor MUST validate that the UCAN capabilities in the proof fulfill their caps criteria. The UCAN itself MUST be valid, unrevoked, unexpired, and intended for the temporary DID (the aud field). If any of these checks fail, the session MUST be abandoned, the temporary DID regenerated, and the protocol restarted from intention broadcast.

The validation UCAN MUST NOT be used to delegate any capabilities. This UCAN MUST only be used to prove access to capabilities and sign the next ECDH public key. The att and my fields MUST be empty arrays. The issuer (iss) field MUST contain the Responder's long-term DID (rather than the temporary ECDH DID). The audience (aud) field MUST contain the Requestor's temporary ECDH DID from §3.2.

This UCAN MUST be encrypted with the KDF-generated AES-GCM key plus IV before being placed into the payload in §3.3.2.

The Responder MUST set the method of challenge to validate the Requestor. This MUST be set in the fct section of the UCAN so that it is signed by the Responder. The RECOMMENDED authorization methods are out-of-band PIN validation (oob-pin) and UCAN (ucan).

To set the challenge as oob-pin, the fct section of the UCAN MUST include the following:

{
  ...,
  "fct": [
    ...,
    {"awake/challenge": "oob-pin"}
  ]
}

To set the challenge as ucan, the fct section of the UCAN MUST include the following:

{
  ...,
  "fct": [
    ...,
    { 
      "awake/challenge": "ucan",
      "caps": [...requiredCaps] 
    }
  ]
}

If more than one awake/challenge field is set, the lowest-indexed one MUST be used.

The UCAN's facts (fct) field MUST also include the next Responder ECDH public key (to be used in Step 4) encoded as did:key. Having the next key in the UCAN places it inside the signature envelope, associating the next key with the Responder's UCAN DID.

//JSON encoded
{
  ...,
  "fct": [
    ...,
    {"awake/nextdid": step4EcdhDid}
  ]
}

If more than one awake/nextdid field is set, the lowest-indexed one MUST be used.

To start the Double Ratchet, the payload in this stage has the highest number of cleartext fields. Note that the value in the iss field contain the temporary ECDH DIDs, and MUST NOT use the Responder's actual long-term DID. Conversely, the UCAN inside the encrypted payload MUST use the Responder's long-term DID.

{
  "awv": "0.1.0",
  "type": "awake/res",
  "iss": responderStep3EcdhDid,
  "aud": requestorStep2EcdhDid,
  "msg": encryptedUcan 
}

NOTE: The Requestor is not yet trusted at this step, and MUST be treated as a possible impersonator or PITM

Requestor                  Responder
    ⋮                          ⋮
    │        Actual DID        │ (4a)
    │        & Challenge       │ (4b)
    ├─────────────────────────►│
    ⋮                          ⋮

At this stage, the Responder has been validated, but the Requestor is still untrusted. The Requestor now MUST provide their actual DID over the secure channel, and MUST prove that they are a trusted party rather than a PITM, eavesdropper, or phisher. This is accomplished in a single message.

The Requestor MUST provide the proof of authorization set by the Responder payload in §3.3.2. The RECOMMENDED authorization methods are PIN validation (pin) and UCAN (ucan). Note that if the Requestor does not know how to respond to fulfill an authorization method, the AWAKE connection MUST fail with an unknown-challenge message.

This message MUST be encrypted with the first AES output of the AWAKE KDF, using the initial chain secret established in §3.3.

{
  "awv": "0.1.0",
  "type": "awake/msg",
  "id": sha256(reqStep2EcdhPk + resStep3EcdhPk),
  "msg": encryptedChallenge
}

Out-of-band PIN challenges are most useful when the Requestor would not be able to provide UCAN validation, such as when signing into a new device that has not been delegated to yet. The PIN MUST be set by the Requestor, and transmitted out of band. Some examples of out of band transmission include displaying text on screen, email, text message, or QR code.

The PIN values MUST be within the UTF-8 character set. The PIN MUST be included in the pin field. It is RECOMMENDED that the PIN be restricted to human-readable characters, and 4 to 10 characters long. If a very long challenge is required, it is RECOMMENDED that the SHA2 hash of the challenge be used rather than putting a large challenge over the wire.

{
  "did": requestorActualDid,
  "sig": signedHash
}

If UCAN auth is required by the Responder, the Requestor MUST provide a UCAN. This is the same strategy as the one used by the Responder in [§3.3](#33-responder-es tablishes-point-to-point-session): the UCAN MUST be encrypted with the session key and the IV from the enclosing payload, MUST be given in a raw format, and MUST be inline (without a JSON object wrapper or similar).

The UCAN MUST be issued (iss) by the Requestor's DID (not the temporary DID), and its audience (aud) MUST be the Responder's DID. The att field MUST be set to an empty array (i.e. it MUST NOT delegate any capabilities). The prf array MUST fulfill the capabilities set by the Responder.

This MAY be used to prove that the Requestor has the same capabilities that the Requestor required from the Responder to start the handshake, such as when enforcing a minimum security clearance or proving functional equivalence between a single user's trusted devices.

              UCAN Auth

┌──────────────AES-GCM────────────┐
│                                 │
│  ┌────────────UCAN───────────┐  │
│  │                           │  │
│  │  iss: RequestorActualDid  │  │
│  │  aud: ResponderActualDid  │  │
│  │  fct: nextReqECDH         │  │
│  │  att: []                  │  │
│  │  prf: ...                 │  │
│  │                           │  │
│  └───────────────────────────┘  │
│                                 │
└─────────────────────────────────┘

The Responder MUST respond with an acknowledgment that the challenge in §3.4 was accepted.

Requestor                  Responder
    ⋮                          ⋮
    │           ACK            │ (5)
    │◄─────────────────────────┤
    │                          │

The encrypted message payload MUST include an awake/ack field, with a value of the requestor's long-term DID. This payload MAY contain additional fields. This is often useful if dovetailing the ACK with the first message of the session.

{
  ...,
  "awake/ack": reqActualDid
}

Requestor                  Responder
    ⋮                          ⋮
    │                          │
    │         Messages         │ (6)
    │◄────────────────────────►│
    │                          │
    ⋮                          ⋮

Messages sent over an established AWAKE session MUST contain the following keys:

Additional cleartext keys MAY be used, but are NOT RECOMMENDED since they can leak information about your session or the payload. Encrypted payloads MAY be padded with random noise or broken across multiple messages to prevent certain kinds of metadata leakage.

The deterministic and unique message ID MUST be the 256-bit SHA2 of the sender and receiver's ECDH public keys and the message count in this Diffie-Hellman epoch.

msgId = sha256(latestSenderEcdhPk + latestReceiverEcdhPk + messageCount)

The recipient SHOULD calculate the next possible message IDs, based on known keys. Unless a synchronous protocol is explicitly used, some number of previous keys SHOULD be considered active to receive out-of-order messages. The recipient SHOULD store messages that it cannot match message IDs for.

To protect against a Byzantine peer flooding its connections with a large number of keys, it is RECOMMENDED that the keys have a TTL, be stored in a fixed-size LIFO queue, or both.

The encrypted payload (msg) MAY include an awake/nextdid field. This continues the Double Ratchet at the Diffie-Hellman step, and updates the send & receive ratchets for successive messages.

Additional fields MAY be included to contain further payload.

// JSON encoded
{
  ...,
  "awake/nextdid": sendersNextEcdhDid
}

Requestor                  Responder
    ⋮                          ⋮
    │                          │
    │           FIN            │ (7)
    │◄────────────────────────►│
    │                          │
    ▀                          ▀ 

Graceful disconnection from an AWAKE attempt MAY be broadcast at any time during an AWAKE session, including to cancel the AWAKE handshake attempt. This payload MUST be the standard AWAKE message type and SHOULD NOT contain any other keys.

The disconnection message MUST include an awake/fin key with disconnect for its value. It MAY include additional fields.

// JSON encoded
{
  ...,
  "awake/fin": "disconnect"
}

All errors MUST use the generic AWAKE message payload, and include the error information in the encrypted payload. It MUST use the latest ECDH keys.

// JSON encoded
{
  "awake/error": "unknown-challenge",
  "awake/mid": offendingMessageId
}

mTLS is the best-known mutual authentication protocol. In many ways, AWAKE is mTLS with trusted rooted in UCAN and a self-signed capabilities model.

The Internet Key Exchange (IKE) Protocol is typically (but not exclusively) used as part of IPsec. IKE generally uses certificate authorities (CAs). IKE requires that X.509 be supported.

IKE shares many commonalities with AWAKE, including making available of the same cryptographic algorithms (e.g. P-256).

WireGuard is a VPN protocol that is widely deployed via the Linux kernel, and has since been ported to many other systems. It is UDP-based and aimed at raw performance and security. Being low-level, it is unconstrained in which cryptographic primitives is uses (i.e. Curve25519).

MLS is a work-in-progress protocol that aims to eventually improve on TLS 1.3. It includes design considerations for doing group messaging, uses ratchet trees, and so on. MLS does include the ability to use certificate authentication (among other authentication methods).

AWAKE may adopt MLS features in the future as it becomes more mature, but today AWAKE is restricted to a point-to-point protocol.

The Signal Protocol heavily influenced the design of AWAKE. Signal is widely deployed, having been included in WhatsApp, Android Messages, the Signal app, and others.

Signal's deployment targets have complete control over their cryptographic stack, and makes use of algorithms like 3XDH based on Curve25519. The AWAKE threat model includes browser application security that requires non-extractable keys, and at time of writing very few of these primitives are available.