├── Makefile ├── README.md ├── my.bib ├── noise.md └── output ├── noise.html └── noise.pdf /Makefile: -------------------------------------------------------------------------------- 1 | 2 | # Edit SPECNAME for the name your spec 3 | SPECNAME := noise 4 | 5 | # Ensure SPECTOOLS points at your spectools 6 | PANDOC := $(SPECTOOLS)/pandoc 7 | CITEPROC := $(SPECTOOLS)/pandoc-citeproc 8 | 9 | # Use "make", "make html", "make pdf", or "make clean" 10 | all: html pdf 11 | 12 | html: output/$(SPECNAME).html 13 | 14 | pdf: output/$(SPECNAME).pdf 15 | 16 | output/$(SPECNAME).html: $(SPECNAME).md $(PANDOC)/template_pandoc.html $(PANDOC)/spec_markdown.css $(CITEPROC)/ieee-with-url.csl $(CITEPROC)/general.bib my.bib 17 | pandoc $(SPECNAME).md --standalone --toc \ 18 | --from markdown\ 19 | --template $(PANDOC)/template_pandoc.html \ 20 | --metadata=pdfn:$(SPECNAME).pdf \ 21 | --css=spec_markdown.css \ 22 | --filter pandoc-citeproc \ 23 | --bibliography=$(CITEPROC)/general.bib \ 24 | --bibliography=my.bib \ 25 | --csl=$(CITEPROC)/ieee-with-url.csl \ 26 | -o output/$(SPECNAME).html 27 | cp $(PANDOC)/spec_markdown.css output 28 | 29 | output/$(SPECNAME).pdf: $(SPECNAME).md $(PANDOC)/template_pandoc.latex $(CITEPROC)/ieee-with-url.csl $(CITEPROC)/general.bib my.bib 30 | pandoc $(SPECNAME).md --standalone --toc \ 31 | --from markdown\ 32 | --template $(PANDOC)/template_pandoc.latex \ 33 | --filter pandoc-citeproc \ 34 | --bibliography=$(CITEPROC)/general.bib \ 35 | --bibliography=my.bib \ 36 | --csl=$(CITEPROC)/ieee-with-url.csl \ 37 | -o output/$(SPECNAME).pdf 38 | 39 | clean: 40 | rm -f output/$(SPECNAME).html output/spec_markdown.css output/$(SPECNAME).pdf 41 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | Noise 3 | --------- 4 | Noise is a framework for crypto protocols based on Diffie-Hellman key agreement. 5 | 6 | Specification 7 | --------------- 8 | 9 | The Noise specification is stored in [noise.md](noise.md) as Pandoc Markdown. 10 | The [Makefile](Makefile) processes the source file to produce HTML and PDF. 11 | 12 | Only a few Pandoc features are used: 13 | 14 | - Metadata at top of file. 15 | 16 | - Reference links use Pandoc's "implicit_header_references" (clicking on these 17 | links in the Github display doesn't do anything). 18 | 19 | - Zero-numbered lists (warning: the Github display of these numbered lists 20 | shows them starting at 1, instead of 0). 21 | 22 | - Table of contents and metadata headers added to output. 23 | -------------------------------------------------------------------------------- /my.bib: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/noiseprotocol/noise_spec/ecdf084ece2bf92b16b1201b6ae5c99d23fb4151/my.bib -------------------------------------------------------------------------------- /noise.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'The Noise Protocol Framework' 3 | author: 'Trevor Perrin (noise@trevp.net)' 4 | revision: '34' 5 | status: 'official/unstable' 6 | date: '2018-07-11' 7 | bibliography: 'my.bib' 8 | link-citations: 'true' 9 | --- 10 | 11 | # 1. Introduction 12 | 13 | Noise is a framework for crypto protocols based on Diffie-Hellman key 14 | agreement. Noise can describe protocols that consist of a single message as 15 | well as interactive protocols. 16 | 17 | # 2. Overview 18 | 19 | ## 2.1. Terminology 20 | 21 | A Noise protocol begins with two parties exchanging **handshake messages**. 22 | During this **handshake phase** the parties exchange DH public keys and perform 23 | a sequence of DH operations, hashing the DH results into a shared secret key. 24 | After the handshake phase each party can use this shared key to send encrypted 25 | **transport messages**. 26 | 27 | The Noise framework supports handshakes where each party has a long-term 28 | **static key pair** and/or an **ephemeral key pair**. A Noise handshake is 29 | described by a simple language. This language consists of **tokens** which are 30 | arranged into **message patterns**. Message patterns are arranged into 31 | **handshake patterns**. 32 | 33 | A **message pattern** is a sequence of tokens that specifies the DH public keys 34 | that comprise a handshake message, and the DH operations that are performed 35 | when sending or receiving that message. A **handshake pattern** specifies the 36 | sequential exchange of messages that comprise a handshake. 37 | 38 | A handshake pattern can be instantiated by **DH functions**, **cipher 39 | functions**, and **hash functions** to give a concrete **Noise protocol**. 40 | 41 | ## 2.2. Overview of handshake state machine 42 | 43 | The core of Noise is a set of variables maintained by each party during a 44 | handshake, and rules for sending and receiving handshake messages by 45 | sequentially processing the tokens from a message pattern. 46 | 47 | Each party maintains the following variables: 48 | 49 | * **`s, e`**: The local party's static and ephemeral key pairs (which may be 50 | empty). 51 | 52 | * **`rs, re`**: The remote party's static and ephemeral public keys (which may 53 | be empty). 54 | 55 | * **`h`**: A **handshake hash** value that hashes all the handshake data that's 56 | been sent and received. 57 | 58 | * **`ck`**: A **chaining key** that hashes all previous DH outputs. Once the 59 | handshake completes, the chaining key will be used to derive the encryption 60 | keys for transport messages. 61 | 62 | * **`k, n`**: An encryption key `k` (which may be empty) and a counter-based 63 | nonce `n`. Whenever a new DH output causes a new `ck` to be calculated, a 64 | new `k` is also calculated. The key `k` and nonce `n` are used to encrypt 65 | static public keys and handshake payloads. Encryption with `k` uses some 66 | **AEAD** cipher mode (in the sense of Rogaway [@Rogaway:2002]) 67 | and uses the current `h` value as **associated data** 68 | which is covered by the AEAD authentication. Encryption of static public 69 | keys and payloads provides some confidentiality and key confirmation during 70 | the handshake phase. 71 | 72 | A handshake message consists of some DH public keys followed by a **payload**. 73 | The payload may contain certificates or other data chosen by the application. 74 | To send a handshake message, the sender specifies the payload and sequentially 75 | processes each token from a message pattern. The possible tokens are: 76 | 77 | * **`"e"`**: The sender generates a new ephemeral key pair and stores it in 78 | the `e` variable, writes the ephemeral public key as cleartext into the 79 | message buffer, and hashes the public key along with the old `h` to derive a 80 | new `h`. 81 | 82 | * **`"s"`**: The sender writes its static public key from the `s` variable 83 | into the message buffer, encrypting it if `k` is non-empty, and hashes the 84 | output along with the old `h` to derive a new `h`. 85 | 86 | * **`"ee", "se", "es", "ss"`**: A DH is performed between the initiator's key 87 | pair (whether static or ephemeral is determined by the first letter) and the 88 | responder's key pair (whether static or ephemeral is determined by the 89 | second letter). The result is hashed along with the old `ck` to derive a 90 | new `ck` and `k`, and `n` is set to zero. 91 | 92 | After processing the final token in a handshake message, the sender then writes 93 | the payload into the message buffer, encrypting it if `k` is non-empty, and 94 | hashes the output along with the old `h` to derive a new `h`. 95 | 96 | As a simple example, an unauthenticated DH handshake is described by the 97 | handshake pattern: 98 | 99 | -> e 100 | <- e, ee 101 | 102 | The **initiator** sends the first message, which is simply an ephemeral public key. 103 | The **responder** sends back its own ephemeral public key. Then a DH is performed 104 | and the output is hashed into a shared secret key. 105 | 106 | Note that a cleartext payload is sent in the first message, after the cleartext 107 | ephemeral public key, and an encrypted payload is sent in the response message, 108 | after the cleartext ephemeral public key. The application may send whatever 109 | payloads it wants. 110 | 111 | The responder can send its static public key (under encryption) and 112 | authenticate itself via a slightly different pattern: 113 | 114 | -> e 115 | <- e, ee, s, es 116 | 117 | In this case, the final `ck` and `k` values are a hash of both DH results. 118 | Since the `es` token indicates a DH between the initiator's ephemeral key and 119 | the responder's static key, successful decryption by the initiator of the 120 | second message's payload serves to authenticate the responder to the initiator. 121 | 122 | Note that the second message's payload may contain a zero-length plaintext, but 123 | the payload ciphertext will still contain authentication data (such as an 124 | authentication tag or "synthetic IV"), since encryption is with an AEAD mode. 125 | The second message's payload can also be used to deliver certificates for the 126 | responder's static public key. 127 | 128 | The initiator can send *its* static public key (under encryption), and 129 | authenticate itself, using a handshake pattern with one additional message: 130 | 131 | -> e 132 | <- e, ee, s, es 133 | -> s, se 134 | 135 | The following sections flesh out the details, and add some complications. 136 | However, the core of Noise is this simple system of variables, tokens, and 137 | processing rules, which allow concise expression of a range of protocols. 138 | 139 | # 3. Message format 140 | 141 | All Noise messages are less than or equal to 65535 bytes in length. 142 | Restricting message size has several advantages: 143 | 144 | * Simpler testing, since it's easy to test the maximum sizes. 145 | 146 | * Reduces the likelihood of errors in memory handling, or integer overflow. 147 | 148 | * Enables support for streaming decryption and random-access decryption of 149 | large data streams. 150 | 151 | * Enables higher-level protocols that encapsulate Noise messages to use an efficient 152 | standard length field of 16 bits. 153 | 154 | All Noise messages can be processed without parsing, since there are no type or 155 | length fields. Of course, Noise messages might be encapsulated within a 156 | higher-level protocol that contains type and length information. Noise 157 | messages might encapsulate payloads that require parsing of some sort, but 158 | payloads are handled by the application, not by Noise. 159 | 160 | A Noise **transport message** is simply an AEAD ciphertext that is less than or 161 | equal to 65535 bytes in length, and that consists of an encrypted payload plus 162 | 16 bytes of authentication data. The details depend on the AEAD cipher 163 | function, e.g. AES256-GCM, or ChaCha20-Poly1305, but typically the 164 | authentication data is either a 16-byte authentication tag appended to the 165 | ciphertext, or a 16-byte synthetic IV prepended to the ciphertext. 166 | 167 | A Noise **handshake message** is also less than or equal to 65535 bytes. It 168 | begins with a sequence of one or more DH public keys, as determined by its 169 | message pattern. Following the public keys will be a single payload which can 170 | be used to convey certificates or other handshake data, but can also contain a 171 | zero-length plaintext. 172 | 173 | Static public keys and payloads will be in cleartext if they are sent in a 174 | handshake prior to a DH operation, and will be AEAD ciphertexts if they occur 175 | after a DH operation. (If Noise is being used with pre-shared symmetric keys, 176 | this rule is different; see [Section 9](#pre-shared-symmetric-keys)). Like transport messages, AEAD 177 | ciphertexts will expand each encrypted field (whether static public key or 178 | payload) by 16 bytes. 179 | 180 | For an example, consider the handshake pattern: 181 | 182 | -> e 183 | <- e, ee, s, es 184 | -> s, se 185 | 186 | The first message consists of a cleartext public key (`"e"`) followed by a 187 | cleartext payload (remember that a payload is implicit at the end of each 188 | message pattern). The second message consists of a cleartext public key 189 | (`"e"`) followed by an encrypted public key (`"s"`) followed by an encrypted 190 | payload. The third message consists of an encrypted public key (`"s"`) 191 | followed by an encrypted payload. 192 | 193 | Assuming each payload contains a zero-length plaintext, and DH public keys are 194 | 56 bytes, the message sizes will be: 195 | 196 | 1. 56 bytes (one cleartext public key and a cleartext payload) 197 | 2. 144 bytes (two public keys, the second encrypted, and encrypted payload) 198 | 3. 88 bytes (one encrypted public key and encrypted payload) 199 | 200 |   201 | \newpage 202 | 203 | # 4. Crypto functions 204 | 205 | A Noise protocol is instantiated with a concrete set of **DH functions**, 206 | **cipher functions**, and **hash functions**. The signature for these 207 | functions is defined below. Some concrete functions are defined in [Section 208 | 12](#dh-functions-cipher-functions-and-hash-functions). 209 | 210 | The following notation will be used in algorithm pseudocode: 211 | 212 | * The `||` operator concatenates byte sequences. 213 | * The `byte()` function constructs a single byte. 214 | 215 | ## 4.1. DH functions 216 | 217 | Noise depends on the following **DH functions** (and an associated constant): 218 | 219 | * **`GENERATE_KEYPAIR()`**: Generates a new Diffie-Hellman key pair. A DH key pair 220 | consists of `public_key` and `private_key` elements. A `public_key` 221 | represents an encoding of a DH public key into a byte sequence of 222 | length `DHLEN`. The `public_key` encoding details are specific to each set 223 | of DH functions. 224 | 225 | * **`DH(key_pair, public_key)`**: Performs a Diffie-Hellman calculation 226 | between the private key in `key_pair` and the `public_key` and returns an output 227 | sequence of bytes of length `DHLEN`. For security, the Gap-DH problem based 228 | on this function must be unsolvable by any practical cryptanalytic adversary 229 | [@gapdh]. 230 | 231 | The `public_key` either encodes some value which is a generator in a large 232 | prime-order group (which value may have multiple equivalent encodings), or 233 | is an invalid value. Implementations must handle invalid public keys 234 | either by returning some output which is purely a function of the public 235 | key and does not depend on the private key, or by signaling an error to 236 | the caller. The DH function may define more specific rules for handling 237 | invalid values. 238 | 239 | * **`DHLEN`** = A constant specifying the size in bytes of public keys and DH 240 | outputs. For security reasons, `DHLEN` must be 32 or greater. 241 | 242 | ## 4.2. Cipher functions 243 | 244 | Noise depends on the following **cipher functions**: 245 | 246 | * **`ENCRYPT(k, n, ad, plaintext)`**: Encrypts `plaintext` using the cipher 247 | key `k` of 32 bytes and an 8-byte unsigned integer nonce `n` which must be 248 | unique for the key `k`. Returns the ciphertext. Encryption must be done 249 | with an "AEAD" encryption mode with the associated data `ad` (using the 250 | terminology from [@Rogaway:2002]) and returns a ciphertext that is the same 251 | size as the plaintext plus 16 bytes for authentication data. The entire 252 | ciphertext must be indistinguishable from random if the key is secret (note 253 | that this is an additional requirement that isn't necessarily met by all 254 | AEAD schemes). 255 | 256 | * **`DECRYPT(k, n, ad, ciphertext)`**: Decrypts `ciphertext` using a cipher 257 | key `k` of 32 bytes, an 8-byte unsigned integer nonce `n`, and associated 258 | data `ad`. Returns the plaintext, unless authentication fails, in which 259 | case an error is signaled to the caller. 260 | 261 | * **`REKEY(k)`**: Returns a new 32-byte cipher key as a pseudorandom function 262 | of `k`. If this function is not specifically defined for some set of cipher 263 | functions, then it defaults to returning the first 32 bytes from `ENCRYPT(k, 264 | maxnonce, zerolen, zeros)`, where `maxnonce` equals 2^64^-1, `zerolen` is a 265 | zero-length byte sequence, and `zeros` is a sequence of 32 bytes filled with 266 | zeros. 267 | 268 | ## 4.3. Hash functions 269 | 270 | Noise depends on the following **hash function** (and associated constants): 271 | 272 | * **`HASH(data)`**: Hashes some arbitrary-length data with a 273 | collision-resistant cryptographic hash function and returns an output of 274 | `HASHLEN` bytes. 275 | 276 | * **`HASHLEN`** = A constant specifying the size in bytes of the hash output. 277 | Must be 32 or 64. 278 | 279 | * **`BLOCKLEN`** = A constant specifying the size in bytes that the hash 280 | function uses internally to divide its input for iterative processing. This 281 | is needed to use the hash function with HMAC (`BLOCKLEN` is `B` in [@rfc2104]). 282 | 283 | Noise defines additional functions based on the above `HASH()` function: 284 | 285 | * **`HMAC-HASH(key, data)`**: Applies `HMAC` from [@rfc2104] 286 | using the `HASH()` function. This function is only called as part of `HKDF()`, below. 287 | 288 | * **`HKDF(chaining_key, input_key_material, num_outputs)`**: Takes a `chaining_key` byte 289 | sequence of length `HASHLEN`, and an `input_key_material` byte sequence with 290 | length either zero bytes, 32 bytes, or `DHLEN` bytes. Returns a pair or triple of byte sequences each of length `HASHLEN`, depending on whether `num_outputs` is two or three: 291 | * Sets `temp_key = HMAC-HASH(chaining_key, input_key_material)`. 292 | * Sets `output1 = HMAC-HASH(temp_key, byte(0x01))`. 293 | * Sets `output2 = HMAC-HASH(temp_key, output1 || byte(0x02))`. 294 | * If `num_outputs == 2` then returns the pair `(output1, output2)`. 295 | * Sets `output3 = HMAC-HASH(temp_key, output2 || byte(0x03))`. 296 | * Returns the triple `(output1, output2, output3)`. 297 | 298 | Note that `temp_key`, `output1`, `output2`, and `output3` are all `HASHLEN` bytes in 299 | length. Also note that the `HKDF()` function is simply `HKDF` from [@rfc5869] 300 | with the `chaining_key` as HKDF `salt`, and zero-length HKDF `info`. 301 | 302 | # 5. Processing rules 303 | 304 | To precisely define the processing rules we adopt an object-oriented 305 | terminology, and present three "objects" which encapsulate state variables and 306 | contain functions which implement processing logic. These three objects are 307 | presented as a hierarchy: each higher-layer object includes one instance of the 308 | object beneath it. From lowest-layer to highest, the objects are: 309 | 310 | * A **`CipherState`** object contains `k` and `n` variables, which it uses to 311 | encrypt and decrypt ciphertexts. During the handshake phase each party has 312 | a single `CipherState`, but during the transport phase each party has two 313 | `CipherState` objects: one for sending, and one for receiving. 314 | 315 | * A **`SymmetricState`** object contains a `CipherState` plus `ck` and `h` 316 | variables. It is so-named because it encapsulates all the "symmetric 317 | crypto" used by Noise. During the handshake phase each party has a single 318 | `SymmetricState`, which can be deleted once the handshake is finished. 319 | 320 | * A **`HandshakeState`** object contains a `SymmetricState` plus DH variables 321 | `(s, e, rs, re)` and a variable representing the handshake pattern. 322 | During the handshake phase each party has a single `HandshakeState`, which 323 | can be deleted once the handshake is finished. 324 | 325 | To execute a Noise protocol you `Initialize()` a `HandshakeState`. During 326 | initialization you specify the handshake pattern, any local key pairs, and any 327 | public keys for the remote party you have knowledge of. After `Initialize()` 328 | you call `WriteMessage()` and `ReadMessage()` on the `HandshakeState` to 329 | process each handshake message. If any error is signaled by the `DECRYPT()` or 330 | `DH()` functions then the handshake has failed and the `HandshakeState` is deleted. 331 | 332 | Processing the final handshake message returns two `CipherState` objects, the 333 | first for encrypting transport messages from initiator to responder, and the 334 | second for messages in the other direction. At that point the `HandshakeState` 335 | should be deleted except for the hash value `h`, which may be used for post-handshake channel binding (see [Section 11.2](#channel-binding)). 336 | 337 | Transport messages are then encrypted and decrypted by calling 338 | `EncryptWithAd()` and `DecryptWithAd()` on the relevant `CipherState` with 339 | zero-length associated data. If `DecryptWithAd()` signals an error due to 340 | `DECRYPT()` failure, then the input message is discarded. The application may 341 | choose to delete the `CipherState` and terminate the session on such an error, 342 | or may continue to attempt communications. If `EncryptWithAd()` or 343 | `DecryptWithAd()` signal an error due to nonce exhaustion, then the 344 | application must delete the `CipherState` and terminate the session. 345 | 346 | The below sections describe these objects in detail. 347 | 348 | ## 5.1. The `CipherState` object 349 | 350 | A `CipherState` can encrypt and decrypt data based on its `k` and `n` 351 | variables: 352 | 353 | * **`k`**: A cipher key of 32 bytes (which may be `empty`). `Empty` is a 354 | special value which indicates `k` has not yet been initialized. 355 | 356 | * **`n`**: An 8-byte (64-bit) unsigned integer nonce. 357 | 358 | A `CipherState` responds to the following functions. The `++` post-increment 359 | operator applied to `n` means "use the current `n` value, then increment it". 360 | The maximum `n` value (2^64^-1) is reserved for other use. If incrementing `n` 361 | results in 2^64^-1, then any further `EncryptWithAd()` or `DecryptWithAd()` 362 | calls will signal an error to the caller. 363 | 364 | * **`InitializeKey(key)`**: Sets `k = key`. Sets `n = 0`. 365 | 366 | * **`HasKey()`**: Returns true if `k` is non-empty, false otherwise. 367 | 368 | * **`SetNonce(nonce)`**: Sets `n = nonce`. This function is used for 369 | handling out-of-order transport messages, as described in [Section 11.4](#out-of-order-transport-messages). 370 | 371 | * **`EncryptWithAd(ad, plaintext)`**: If `k` is non-empty returns 372 | `ENCRYPT(k, n++, ad, plaintext)`. Otherwise returns `plaintext`. 373 | 374 | * **`DecryptWithAd(ad, ciphertext)`**: If `k` is non-empty returns 375 | `DECRYPT(k, n++, ad, ciphertext)`. Otherwise returns `ciphertext`. If an 376 | authentication failure occurs in `DECRYPT()` then `n` is not incremented 377 | and an error is signaled to the caller. 378 | 379 | * **`Rekey()`**: Sets `k = REKEY(k)`. 380 | 381 | ## 5.2. The `SymmetricState` object 382 | 383 | A `SymmetricState` object contains a `CipherState` plus the following 384 | variables: 385 | 386 | * **`ck`**: A chaining key of `HASHLEN` bytes. 387 | * **`h`**: A hash output of `HASHLEN` bytes. 388 | 389 | A `SymmetricState` responds to the following functions: 390 | 391 | * **`InitializeSymmetric(protocol_name)`**: Takes an arbitrary-length 392 | `protocol_name` byte sequence (see [Section 8](#protocol-names-and-modifiers)). Executes the following steps: 393 | 394 | * If `protocol_name` is less than or equal to `HASHLEN` bytes in length, 395 | sets `h` equal to `protocol_name` with zero bytes appended to make 396 | `HASHLEN` bytes. Otherwise sets `h = HASH(protocol_name)`. 397 | 398 | * Sets `ck = h`. 399 | 400 | * Calls `InitializeKey(empty)`. 401 | 402 | * **`MixKey(input_key_material)`**: Executes the following steps: 403 | 404 | * Sets `ck, temp_k = HKDF(ck, input_key_material, 2)`. 405 | * If `HASHLEN` is 64, then truncates `temp_k` to 32 bytes. 406 | * Calls `InitializeKey(temp_k)`. 407 | 408 | * **`MixHash(data)`**: Sets `h = HASH(h || data)`. 409 | 410 | * **`MixKeyAndHash(input_key_material)`**: This function is used for 411 | handling pre-shared symmetric keys, as described in [Section 412 | 9](#pre-shared-symmetric-keys). It executes the following steps: 413 | 414 | * Sets `ck, temp_h, temp_k = HKDF(ck, input_key_material, 3)`. 415 | * Calls `MixHash(temp_h)`. 416 | * If `HASHLEN` is 64, then truncates `temp_k` to 32 bytes. 417 | * Calls `InitializeKey(temp_k)`. 418 | 419 | * **`GetHandshakeHash()`**: Returns `h`. This function should only be 420 | called at the end of a handshake, i.e. after the `Split()` function has 421 | been called. This function is used for channel binding, as described in 422 | [Section 11.2](#channel-binding) 423 | 424 | * **`EncryptAndHash(plaintext)`**: Sets `ciphertext = EncryptWithAd(h, 425 | plaintext)`, calls `MixHash(ciphertext)`, and returns `ciphertext`. Note that if 426 | `k` is `empty`, the `EncryptWithAd()` call will set `ciphertext` equal to `plaintext`. 427 | 428 | * **`DecryptAndHash(ciphertext)`**: Sets `plaintext = DecryptWithAd(h, 429 | ciphertext)`, calls `MixHash(ciphertext)`, and returns `plaintext`. Note that if 430 | `k` is `empty`, the `DecryptWithAd()` call will set `plaintext` equal to `ciphertext`. 431 | 432 | * **`Split()`**: Returns a pair of `CipherState` objects for encrypting 433 | transport messages. Executes the following steps, where `zerolen` is a zero-length 434 | byte sequence: 435 | * Sets `temp_k1, temp_k2 = HKDF(ck, zerolen, 2)`. 436 | * If `HASHLEN` is 64, then truncates `temp_k1` and `temp_k2` to 32 bytes. 437 | * Creates two new `CipherState` objects `c1` and `c2`. 438 | * Calls `c1.InitializeKey(temp_k1)` and `c2.InitializeKey(temp_k2)`. 439 | * Returns the pair `(c1, c2)`. 440 | 441 | 442 | ## 5.3. The `HandshakeState` object 443 | 444 | A `HandshakeState` object contains a `SymmetricState` plus the following 445 | variables, any of which may be `empty`. `Empty` is a special value which 446 | indicates the variable has not yet been initialized. 447 | 448 | * **`s`**: The local static key pair 449 | * **`e`**: The local ephemeral key pair 450 | * **`rs`**: The remote party's static public key 451 | * **`re`**: The remote party's ephemeral public key 452 | 453 | A `HandshakeState` also has variables to track its role, and the remaining 454 | portion of the handshake pattern: 455 | 456 | * **`initiator`**: A boolean indicating the initiator or responder role. 457 | 458 | * **`message_patterns`**: A sequence of message patterns. Each message 459 | pattern is a sequence of tokens from the set `("e", "s", "ee", "es", "se", 460 | "ss")`. (An additional `"psk"` token is introduced in [Section 461 | 9](#pre-shared-symmetric-keys), but we defer its explanation until then.) 462 | 463 | A `HandshakeState` responds to the following functions: 464 | 465 | * **`Initialize(handshake_pattern, initiator, prologue, s, e, rs, re)`**: 466 | Takes a valid `handshake_pattern` (see [Section 7](#handshake-patterns)) and an 467 | `initiator` boolean specifying this party's role as either initiator or 468 | responder. 469 | 470 | Takes a `prologue` byte sequence which may be zero-length, or 471 | which may contain context information that both parties want to confirm is 472 | identical (see [Section 6](#prologue)). 473 | 474 | Takes a set of DH key pairs `(s, e)` and 475 | public keys `(rs, re)` for initializing local variables, any of which may be empty. 476 | Public keys are only passed in if the `handshake_pattern` uses pre-messages 477 | (see [Section 7](#handshake-patterns)). The ephemeral values `(e, re)` are typically 478 | left empty, since they are created and exchanged during the handshake; but there are 479 | exceptions (see [Section 10](#compound-patterns)). 480 | 481 | Performs the following steps: 482 | 483 | * Derives a `protocol_name` byte sequence by combining the names for the 484 | handshake pattern and crypto functions, as specified in [Section 485 | 8](#protocol-names-and-modifiers). Calls `InitializeSymmetric(protocol_name)`. 486 | 487 | * Calls `MixHash(prologue)`. 488 | 489 | * Sets the `initiator`, `s`, `e`, `rs`, and `re` variables to the 490 | corresponding arguments. 491 | 492 | * Calls `MixHash()` once for each public key listed in the pre-messages 493 | from `handshake_pattern`, with the specified public key as input (see 494 | [Section 7](#handshake-patterns) for an explanation of pre-messages). 495 | If both initiator and responder have pre-messages, the initiator's 496 | public keys are hashed first. If multiple public keys are listed in 497 | either party's pre-message, the public keys are hashed in the order 498 | that they are listed. 499 | 500 | * Sets `message_patterns` to the message patterns from `handshake_pattern`. 501 | 502 | * **`WriteMessage(payload, message_buffer)`**: Takes a `payload` byte sequence 503 | which may be zero-length, and a `message_buffer` to write the output into. Performs the following steps, aborting if any `EncryptAndHash()` call returns an error: 504 | 505 | * Fetches and deletes the next message pattern from `message_patterns`, 506 | then sequentially processes each token from the message pattern: 507 | 508 | * For `"e"`: Sets `e` (which must be empty) to `GENERATE_KEYPAIR()`. 509 | Appends `e.public_key` to the buffer. Calls `MixHash(e.public_key)`. 510 | 511 | * For `"s"`: Appends `EncryptAndHash(s.public_key)` to the buffer. 512 | 513 | * For `"ee"`: Calls `MixKey(DH(e, re))`. 514 | 515 | * For `"es"`: Calls `MixKey(DH(e, rs))` if initiator, `MixKey(DH(s, re))` if responder. 516 | 517 | * For `"se"`: Calls `MixKey(DH(s, re))` if initiator, `MixKey(DH(e, rs))` if responder. 518 | 519 | * For `"ss"`: Calls `MixKey(DH(s, rs))`. 520 | 521 | * Appends `EncryptAndHash(payload)` to the buffer. 522 | 523 | * If there are no more message patterns returns two new `CipherState` 524 | objects by calling `Split()`. 525 | 526 | \newpage 527 | 528 | * **`ReadMessage(message, payload_buffer)`**: Takes a byte sequence 529 | containing a Noise handshake message, and a `payload_buffer` to write the 530 | message's plaintext payload into. Performs the following steps, aborting 531 | if any `DecryptAndHash()` call returns an error: 532 | 533 | * Fetches and deletes the next message pattern from `message_patterns`, 534 | then sequentially processes each token from the message pattern: 535 | 536 | * For `"e"`: Sets `re` (which must be empty) to the next `DHLEN` 537 | bytes from the message. Calls `MixHash(re.public_key)`. 538 | 539 | * For `"s"`: Sets `temp` to the next `DHLEN + 16` bytes of the message if 540 | `HasKey() == True`, or to the next `DHLEN` bytes otherwise. Sets `rs` (which must be empty) 541 | to `DecryptAndHash(temp)`. 542 | 543 | * For `"ee"`: Calls `MixKey(DH(e, re))`. 544 | 545 | * For `"es"`: Calls `MixKey(DH(e, rs))` if initiator, `MixKey(DH(s, re))` if responder. 546 | 547 | * For `"se"`: Calls `MixKey(DH(s, re))` if initiator, `MixKey(DH(e, rs))` if responder. 548 | 549 | * For `"ss"`: Calls `MixKey(DH(s, rs))`. 550 | 551 | * Calls `DecryptAndHash()` on the remaining bytes of the message and stores 552 | the output into `payload_buffer`. 553 | 554 | * If there are no more message patterns returns two new `CipherState` 555 | objects by calling `Split()`. 556 | 557 | # 6. Prologue 558 | 559 | Noise protocols have a **prologue** input which allows arbitrary data to be 560 | hashed into the `h` variable. If both parties do not provide identical 561 | prologue data, the handshake will fail due to a decryption error. This is 562 | useful when the parties engaged in negotiation prior to the handshake and want 563 | to ensure they share identical views of that negotiation. 564 | 565 | For example, suppose Bob communicates to Alice a list of Noise protocols that 566 | he is willing to support. Alice will then choose and execute a single 567 | protocol. To ensure that a "man-in-the-middle" did not edit Bob's list to 568 | remove options, Alice and Bob could include the list as prologue data. 569 | 570 | Note that while the parties confirm their prologues are identical, they don't 571 | mix prologue data into encryption keys. If an input contains secret data that’s 572 | intended to strengthen the encryption, a PSK handshake should be used 573 | instead (see [Section 9](pre-shared-symmetric-keys)). 574 | 575 | 576 | # 7. Handshake patterns 577 | 578 | ## 7.1. Handshake pattern basics 579 | 580 | A **message pattern** is some sequence of tokens from the set `("e", "s", "ee", 581 | "es", "se", "ss", "psk")`. The handling of these tokens within 582 | `WriteMessage()` and `ReadMessage()` has been described previously, except for 583 | the `"psk"` token, which will be described in [Section 584 | 9](pre-shared-symmetric-keys). Future specifications might introduce other 585 | tokens. 586 | 587 | A **pre-message pattern** is one of the following sequences of tokens: 588 | 589 | * `"e"` 590 | * `"s"` 591 | * `"e, s"` 592 | * empty 593 | 594 | 595 | A **handshake pattern** consists of: 596 | 597 | * A pre-message pattern for the initiator, representing information about 598 | the initiator's public keys that is known to the responder. 599 | 600 | * A pre-message pattern for the responder, representing information about the 601 | responder's public keys that is known to the initiator. 602 | 603 | * A sequence of message patterns for the actual handshake messages. 604 | 605 | The pre-messages represent an exchange of public keys that was somehow 606 | performed prior to the handshake, so these public keys must be inputs to 607 | `Initialize()` for the "recipient" of the pre-message. 608 | 609 | The first actual handshake message is sent from the initiator to the responder. 610 | The next message is sent from the responder, the next from the initiator, and so 611 | on in alternating fashion. 612 | 613 | 614 | The following handshake pattern describes an unauthenticated DH handshake consisting of two message patterns: 615 | 616 | NN: 617 | -> e 618 | <- e, ee 619 | 620 | In the following handshake pattern both the initiator and responder possess 621 | static key pairs, and the handshake pattern comprises three message patterns: 622 | 623 | XX: 624 | -> e 625 | <- e, ee, s, es 626 | -> s, se 627 | 628 | The handshake pattern names are `NN` and `XX`. This naming convention will be 629 | explained in [Section 7.5](#interactive-handshake-patterns-fundamental). 630 | 631 | Non-empty pre-messages are shown as pre-message patterns prior to the delimiter 632 | `"..."`. If both parties have a pre-message, the initiator's is listed first, 633 | and hashed first. During `Initialize()`, `MixHash()` is called on any 634 | pre-message public keys, as described in [Section 635 | 5.3](#the-handshakestate-object). 636 | 637 | The following handshake pattern describes a handshake where the initiator has 638 | pre-knowledge of the responder's static public key and uses it for "zero-RTT" 639 | encryption: 640 | 641 | NK: 642 | <- s 643 | ... 644 | -> e, es 645 | <- e, ee 646 | 647 | In the following handshake pattern both parties have pre-knowledge of the 648 | other's static public key. The initiator's pre-message is listed first: 649 | 650 | KK: 651 | -> s 652 | <- s 653 | ... 654 | -> e, es, ss 655 | <- e, ee, se 656 | 657 | \newpage 658 | 659 | ## 7.2. Alice and Bob 660 | 661 | In all handshake patterns shown previously, the initiator is the party on the 662 | left (sending with right-pointing arrows) and the responder is the party on the 663 | right. 664 | 665 | However, multiple Noise protocols might be used within a **compound protocol** 666 | where the responder in one Noise protocol becomes the initiator for a later 667 | Noise protocol. As a convenience for terminology and notation in this case, we 668 | introduce the notion of **Alice** and **Bob** roles which are different from 669 | initiator and responder roles. Alice will be viewed as the party on the 670 | left (sending messages with right arrows), and Bob will be the party on the 671 | right. 672 | 673 | Handshake patterns written in **canonical form** (i.e. **Alice-initiated 674 | form**) assume the initiator is Alice (the left-most party). All processing 675 | rules and discussion so far have assumed canonical-form handshake patterns. 676 | 677 | However, handshake patterns can be written in **Bob-initiated form** by 678 | reversing the arrows and the DH tokens (e.g. replacing `"es"` with `"se"`, and 679 | vice versa). This doesn't change the handshake pattern, it simply makes it 680 | easier to view Alice-initiated and Bob-initiated handshakes side-by-side. 681 | 682 | Below are the handshake patterns from the previous section in Bob-initiated 683 | form: 684 | 685 | NN: 686 | <- e 687 | -> e, ee 688 | 689 | XX: 690 | <- e 691 | -> e, ee, s, se 692 | <- s, es 693 | 694 | NK: 695 | -> s 696 | ... 697 | <- e, se 698 | -> e, ee 699 | 700 | KK: 701 | <- s 702 | -> s 703 | ... 704 | <- e, se, ss 705 | -> e, ee, es 706 | 707 | For an example of Bob-initiated notation, see [Section 708 | 10.2](#the-fallback-modifier). 709 | 710 | ## 7.3. Handshake pattern validity 711 | 712 | Handshake patterns must be **valid** in the following senses: 713 | 714 | 1. Parties can only perform DH between private keys and public 715 | keys they possess. 716 | 717 | 2. Parties must not send their static public key or ephemeral public key more 718 | than once per handshake (i.e. including the pre-messages, there must be no 719 | more than one occurrence of `"e"`, and one occurrence of `"s"`, in the 720 | messages sent by any party). 721 | 722 | 3. Parties must not perform a DH calculation more than once per handshake (i.e. 723 | there must be no more than one occurrence of `"ee"`, `"es"`, `"se"`, or `"ss"` 724 | per handshake). 725 | 726 | 4. After performing a DH between a remote public key (either static or 727 | ephemeral) and the local static key, the local party must not call 728 | `ENCRYPT()` unless it has also performed a DH between its local ephemeral 729 | key and the remote public key. In particular, this means that (using 730 | canonical notation): 731 | 732 | After an `"se"` token, the initiator must not send a handshake payload 733 | or transport payload unless there has also been an `"ee"` token. 734 | 735 | After an `"ss"` token, the initiator must not send a handshake payload 736 | or transport payload unless there has also been an `"es"` token. 737 | 738 | After an `"es"` token, the responder must not send a handshake payload 739 | or transport payload unless there has also been an `"ee"` token. 740 | 741 | After an `"ss"` token, the responder must not send a handshake payload 742 | or transport payload unless there has also been an `"se"` token. 743 | 744 | Patterns failing the first check are obviously nonsense. 745 | 746 | The second and third checks outlaw redundant transmission of values, and 747 | redundant computation, to simplify implementation and testing. 748 | 749 | The fourth check accomplishes two purposes: 750 | 751 | * First, it is necessary because Noise relies on DH outputs involving 752 | ephemeral keys to randomize the shared secret keys. Patterns failing this 753 | check could result in catastrophic key reuse, because the victim might 754 | send a message encrypted with a key that doesn't include a contribution from 755 | their local ephemeral key (or where the contribution from their local 756 | ephemeral was nullified by an invalid ephemeral from the other party). 757 | 758 | * Second, this check guarantees that ephemeral keys are used to provide 759 | important security properties such as forward-secrecy and key-compromise 760 | impersonation resistance. 761 | 762 | Users are recommended to only use the handshake patterns listed below, or other 763 | patterns that have been vetted by experts to satisfy the above checks. 764 | 765 | ## 7.4. One-way handshake patterns 766 | 767 | The following handshake patterns represent "one-way" handshakes supporting a 768 | one-way stream of data from a sender to a recipient. These patterns could be 769 | used to encrypt files, database records, or other non-interactive data streams. 770 | 771 | Following a one-way handshake the sender can send a stream of transport 772 | messages, encrypting them using the first `CipherState` returned by `Split()`. 773 | The second `CipherState` from `Split()` is discarded - the recipient must not 774 | send any messages using it (as this would violate the rules in [Section 7.3](#handshake-pattern-validity)). 775 | 776 | One-way patterns are named with a single character, which indicates the 777 | status of the sender's static key: 778 | 779 | * **`N`** = **`N`**o static key for sender 780 | * **`K`** = Static key for sender **`K`**nown to recipient 781 | * **`X`** = Static key for sender **`X`**mitted ("transmitted") to recipient 782 | 783 | +-------------------------+ 784 | | N: | 785 | | <- s | 786 | | ... | 787 | | -> e, es | 788 | +-------------------------+ 789 | | K: | 790 | | -> s | 791 | | <- s | 792 | | ... | 793 | | -> e, es, ss | 794 | +-------------------------+ 795 | | X: | 796 | | <- s | 797 | | ... | 798 | | -> e, es, s, ss | 799 | +-------------------------+ 800 | 801 | `N` is a conventional DH-based public-key encryption. The other patterns 802 | add sender authentication, where the sender's public key is either known to the 803 | recipient beforehand (`K`) or transmitted under encryption (`X`). 804 | 805 | \newpage 806 | 807 | ## 7.5. Interactive handshake patterns (fundamental) 808 | 809 | The following handshake patterns represent interactive protocols. These 810 | 12 patterns are called the **fundamental** interactive handshake patterns. 811 | 812 | The fundamental interactive patterns are named with two characters, which 813 | indicate the status of the initiator and responder's static keys: 814 | 815 | The first character refers to the initiator's static key: 816 | 817 | * **`N`** = **`N`**o static key for initiator 818 | * **`K`** = Static key for initiator **`K`**nown to responder 819 | * **`X`** = Static key for initiator **`X`**mitted ("transmitted") to responder 820 | * **`I`** = Static key for initiator **`I`**mmediately transmitted to responder, 821 | despite reduced or absent identity hiding 822 | 823 | The second character refers to the responder's static key: 824 | 825 | * **`N`** = **`N`**o static key for responder 826 | * **`K`** = Static key for responder **`K`**nown to initiator 827 | * **`X`** = Static key for responder **`X`**mitted ("transmitted") to initiator 828 | 829 | \newpage 830 | 831 | +---------------------------+--------------------------------+ 832 | | NN: | KN: | 833 | | -> e | -> s | 834 | | <- e, ee | ... | 835 | | | -> e | 836 | | | <- e, ee, se | 837 | +---------------------------+--------------------------------+ 838 | | NK: | KK: | 839 | | <- s | -> s | 840 | | ... | <- s | 841 | | -> e, es | ... | 842 | | <- e, ee | -> e, es, ss | 843 | | | <- e, ee, se | 844 | +---------------------------+--------------------------------+ 845 | | NX: | KX: | 846 | | -> e | -> s | 847 | | <- e, ee, s, es | ... | 848 | | | -> e | 849 | | | <- e, ee, se, s, es | 850 | +---------------------------+--------------------------------+ 851 | | XN: | IN: | 852 | | -> e | -> e, s | 853 | | <- e, ee | <- e, ee, se | 854 | | -> s, se | | 855 | +---------------------------+--------------------------------+ 856 | | XK: | IK: | 857 | | <- s | <- s | 858 | | ... | ... | 859 | | -> e, es | -> e, es, s, ss | 860 | | <- e, ee | <- e, ee, se | 861 | | -> s, se | | 862 | +---------------------------+--------------------------------+ 863 | | XX: | IX: | 864 | | -> e | -> e, s | 865 | | <- e, ee, s, es | <- e, ee, se, s, es | 866 | | -> s, se | | 867 | +---------------------------+--------------------------------+ 868 | 869 | \newpage 870 | 871 | The `XX` pattern is the most generically useful, since it supports mutual 872 | authentication and transmission of static public keys. 873 | 874 | All fundamental patterns allow some encryption of handshake payloads: 875 | 876 | * Patterns where the initiator has pre-knowledge of the responder's static 877 | public key (i.e. patterns ending in `K`) allow **zero-RTT** encryption, 878 | meaning the initiator can encrypt the first handshake payload. 879 | 880 | * All fundamental patterns allow **half-RTT** encryption of the first response 881 | payload, but the encryption only targets an initiator static public key in 882 | patterns starting with `K` or `I`. 883 | 884 | The security properties for handshake payloads are usually weaker than the 885 | final security properties achieved by transport payloads, so these early 886 | encryptions must be used with caution. 887 | 888 | In some patterns the security properties of transport payloads can also vary. 889 | In particular: patterns starting with `K` or `I` have the caveat that the 890 | responder is only guaranteed "weak" forward secrecy for the transport messages 891 | it sends until it receives a transport message from the initiator. After 892 | receiving a transport message from the initiator, the responder becomes assured 893 | of "strong" forward secrecy. 894 | 895 | More analysis of these payload security properties is in [Section 7.7](#payload-security-properties). 896 | 897 | ## 7.6. Interactive handshake patterns (deferred) 898 | 899 | The fundamental handshake patterns in the previous section perform DH operations for authentication (`"es"` and `"se"`) as early as possible. 900 | 901 | An additional set of handshake patterns can be described which defer these authentication DHs to the next message. To name these **deferred handshake patterns**, the numeral "1" is used after the first and/or second character in a fundamental pattern name to indicate that the initiator and/or responder's authentication DH is deferred to the next message. 902 | 903 | Deferred patterns might be useful for several reasons: 904 | 905 | * The initiator might have prior knowledge of the responder's static public key, but not wish to send any 0-RTT encrypted data. 906 | 907 | * In some cases, deferring authentication can improve the identity-hiding properties of the handshake (see [Section 7.8](#identity-hiding)). 908 | 909 | * Future extensions to Noise might be capable of replacing DH operations with signatures or KEM ciphertexts, but would only be able to do so if the sender is authenticating themselves (signatures) or the sender is authenticating the recipient (KEM ciphertexts). Thus every fundamental handshake pattern is only capable of having each authentication DH replaced with a signature *or* KEM ciphertext, but the deferred variants make both replacements possible. 910 | 911 | Below are two examples showing a fundamental handshake pattern on the left, and deferred variant(s) on the right. The full set of 23 deferred handshake patterns are in the [Appendix](#deferred-patterns). 912 | 913 | +---------------------------+--------------------------------+ 914 | | NK: | NK1: | 915 | | <- s | <- s | 916 | | ... | ... | 917 | | -> e, es | -> e | 918 | | <- e, ee | <- e, ee, es | 919 | | | | 920 | +---------------------------+--------------------------------+ 921 | | XX: | X1X: | 922 | | -> e | -> e | 923 | | <- e, ee, s, es | <- e, ee, s, es | 924 | | -> s, se | -> s | 925 | | | <- se | 926 | | | | 927 | | | XX1: | 928 | | | -> e | 929 | | | <- e, ee, s | 930 | | | -> es, s, se | 931 | | | | 932 | | | X1X1: | 933 | | | -> e | 934 | | | <- e, ee, s | 935 | | | -> es, s | 936 | | | <- se | 937 | | | | 938 | +---------------------------+--------------------------------+ 939 | 940 | 941 | 942 | 943 | ## 7.7. Payload security properties 944 | 945 | The following table lists the security properties for Noise handshake and 946 | transport payloads for all the one-way patterns in [Section 7.4](#one-way-handshake-patterns) and the fundamental patterns in 947 | [Section 7.5](#interactive-handshake-patterns-fundamental). Each payload is assigned a "source" 948 | property regarding the degree of authentication of the sender provided to the 949 | recipient, and a "destination" property regarding the degree of 950 | confidentiality provided to the sender. 951 | 952 | The source properties are: 953 | 954 | 0. **No authentication.** This payload may have been sent by any party, 955 | including an active attacker. 956 | 957 | 1. **Sender authentication *vulnerable* to key-compromise impersonation 958 | (KCI)**. The sender authentication is based on a static-static DH 959 | (`"ss"`) involving both parties' static key pairs. If the recipient's 960 | long-term private key has been compromised, this authentication can be 961 | forged. Note that a future version of Noise might include signatures, 962 | which could improve this security property, but brings other trade-offs. 963 | 964 | 2. **Sender authentication *resistant* to key-compromise impersonation 965 | (KCI)**. The sender authentication is based on an ephemeral-static DH 966 | (`"es"` or `"se"`) between the sender's static key pair and the 967 | recipient's ephemeral key pair. Assuming the corresponding private keys 968 | are secure, this authentication cannot be forged. 969 | 970 | The destination properties are: 971 | 972 | 0. **No confidentiality.** This payload is sent in cleartext. 973 | 974 | 1. **Encryption to an ephemeral recipient.** This payload has forward 975 | secrecy, since encryption involves an ephemeral-ephemeral DH (`"ee"`). 976 | However, the sender has not authenticated the recipient, so this payload 977 | might be sent to any party, including an active attacker. 978 | 979 | 2. **Encryption to a known recipient, forward secrecy for sender 980 | compromise only, vulnerable to replay.** This payload is encrypted based 981 | only on DHs involving the recipient's static key pair. If the recipient's 982 | static private key is compromised, even at a later date, this payload can 983 | be decrypted. This message can also be replayed, since there's no 984 | ephemeral contribution from the recipient. 985 | 986 | 3. **Encryption to a known recipient, weak forward secrecy.** This 987 | payload is encrypted based on an ephemeral-ephemeral DH and also an 988 | ephemeral-static DH involving the recipient's static key pair. However, 989 | the binding between the recipient's alleged ephemeral public key and the 990 | recipient's static public key hasn't been verified by the sender, so the 991 | recipient's alleged ephemeral public key may have been forged by an active 992 | attacker. In this case, the attacker could later compromise the 993 | recipient's static private key to decrypt the payload. Note that a future 994 | version of Noise might include signatures, which could improve this 995 | security property, but brings other trade-offs. 996 | 997 | 4. **Encryption to a known recipient, weak forward secrecy if the 998 | sender's private key has been compromised.** This payload is encrypted 999 | based on an ephemeral-ephemeral DH, and also based on an ephemeral-static 1000 | DH involving the recipient's static key pair. However, the binding 1001 | between the recipient's alleged ephemeral public and the recipient's 1002 | static public key has only been verified based on DHs involving both those 1003 | public keys and the sender's static private key. Thus, if the sender's 1004 | static private key was previously compromised, the recipient's alleged 1005 | ephemeral public key may have been forged by an active attacker. In this 1006 | case, the attacker could later compromise the intended recipient's static 1007 | private key to decrypt the payload (this is a variant of a "KCI" attack 1008 | enabling a "weak forward secrecy" attack). Note that a future version of 1009 | Noise might include signatures, which could improve this security 1010 | property, but brings other trade-offs. 1011 | 1012 | 5. **Encryption to a known recipient, strong forward secrecy.** This 1013 | payload is encrypted based on an ephemeral-ephemeral DH as well as an 1014 | ephemeral-static DH with the recipient's static key pair. Assuming the 1015 | ephemeral private keys are secure, and the recipient is not being actively 1016 | impersonated by an attacker that has stolen its static private key, this 1017 | payload cannot be decrypted. 1018 | 1019 | For one-way handshakes, the below-listed security properties apply to the 1020 | handshake payload as well as transport payloads. 1021 | 1022 | For interactive handshakes, security properties are listed for each handshake 1023 | payload. Transport payloads are listed as arrows without a pattern. Transport 1024 | payloads are only listed if they have different security properties than the 1025 | previous handshake payload sent from the same party. If two transport payloads 1026 | are listed, the security properties for the second only apply if the first was 1027 | received. 1028 | 1029 | +--------------------------------------------------------------+ 1030 | | Source Destination | 1031 | +--------------------------------------------------------------+ 1032 | | N 0 2 | 1033 | +--------------------------------------------------------------+ 1034 | | K 1 2 | 1035 | +--------------------------------------------------------------+ 1036 | | X 1 2 | 1037 | +--------------------------------------------------------------+ 1038 | | NN | 1039 | | -> e 0 0 | 1040 | | <- e, ee 0 1 | 1041 | | -> 0 1 | 1042 | +--------------------------------------------------------------+ 1043 | | NK | 1044 | | <- s | 1045 | | ... | 1046 | | -> e, es 0 2 | 1047 | | <- e, ee 2 1 | 1048 | | -> 0 5 | 1049 | +--------------------------------------------------------------+ 1050 | | NX | 1051 | | -> e 0 0 | 1052 | | <- e, ee, s, es 2 1 | 1053 | | -> 0 5 | 1054 | +--------------------------------------------------------------+ 1055 | | XN | 1056 | | -> e 0 0 | 1057 | | <- e, ee 0 1 | 1058 | | -> s, se 2 1 | 1059 | | <- 0 5 | 1060 | | | 1061 | +--------------------------------------------------------------+ 1062 | | XK | 1063 | | <- s | 1064 | | ... | 1065 | | -> e, es 0 2 | 1066 | | <- e, ee 2 1 | 1067 | | -> s, se 2 5 | 1068 | | <- 2 5 | 1069 | +--------------------------------------------------------------+ 1070 | | XX | 1071 | | -> e 0 0 | 1072 | | <- e, ee, s, es 2 1 | 1073 | | -> s, se 2 5 | 1074 | | <- 2 5 | 1075 | +--------------------------------------------------------------+ 1076 | | KN | 1077 | | -> s | 1078 | | ... | 1079 | | -> e 0 0 | 1080 | | <- e, ee, se 0 3 | 1081 | | -> 2 1 | 1082 | | <- 0 5 | 1083 | +--------------------------------------------------------------+ 1084 | | KK | 1085 | | -> s | 1086 | | <- s | 1087 | | ... | 1088 | | -> e, es, ss 1 2 | 1089 | | <- e, ee, se 2 4 | 1090 | | -> 2 5 | 1091 | | <- 2 5 | 1092 | +--------------------------------------------------------------+ 1093 | | KX | 1094 | | -> s | 1095 | | ... | 1096 | | -> e 0 0 | 1097 | | <- e, ee, se, s, es 2 3 | 1098 | | -> 2 5 | 1099 | | <- 2 5 | 1100 | +--------------------------------------------------------------+ 1101 | | IN | 1102 | | -> e, s 0 0 | 1103 | | <- e, ee, se 0 3 | 1104 | | -> 2 1 | 1105 | | <- 0 5 | 1106 | +--------------------------------------------------------------+ 1107 | | IK | 1108 | | <- s | 1109 | | ... | 1110 | | -> e, es, s, ss 1 2 | 1111 | | <- e, ee, se 2 4 | 1112 | | -> 2 5 | 1113 | | <- 2 5 | 1114 | +--------------------------------------------------------------+ 1115 | | IX | 1116 | | -> e, s 0 0 | 1117 | | <- e, ee, se, s, es 2 3 | 1118 | | -> 2 5 | 1119 | | <- 2 5 | 1120 | +--------------------------------------------------------------+ 1121 | 1122 | 1123 | ## 7.8. Identity hiding 1124 | 1125 | The following table lists the identity-hiding properties for all the one-way 1126 | handshake patterns in [Section 7.4](#one-way-handshake-patterns) and the fundamental handshake patterns in [Section 7.5](#interactive-handshake-patterns-fundamental). In addition, we list a few deferred handshake patterns which have different identity-hiding properties than the corresponding fundamental pattern. 1127 | 1128 | Each pattern is assigned properties describing the confidentiality supplied to 1129 | the initiator's static public key, and to the responder's static public key. 1130 | The underlying assumptions are that ephemeral private keys are secure, and that 1131 | parties abort the handshake if they receive a static public key from the other 1132 | party which they don't trust. 1133 | 1134 | This section only considers identity leakage through static public key fields 1135 | in handshakes. Of course, the identities of Noise participants might be 1136 | exposed through other means, including payload fields, traffic analysis, or 1137 | metadata such as IP addresses. 1138 | 1139 | The properties for the relevant public key are: 1140 | 1141 | 0. Transmitted in clear. 1142 | 1143 | 1. Encrypted with forward secrecy, but can be probed by an 1144 | anonymous initiator. 1145 | 1146 | 2. Encrypted with forward secrecy, but sent to an anonymous responder. 1147 | 1148 | 3. Not transmitted, but a passive attacker can check candidates for the 1149 | responder's private key and determine whether the candidate is correct. 1150 | An attacker could also replay a previously-recorded message to a new 1151 | responder and determine whether the two responders are the "same" (i.e. are 1152 | using the same static key pair) by whether the recipient accepts the message. 1153 | 1154 | 4. Encrypted to responder's static public key, without forward secrecy. 1155 | If an attacker learns the responder's private key they can decrypt the 1156 | initiator's public key. 1157 | 1158 | 5. Not transmitted, but a passive attacker can check candidates for the pair 1159 | of (responder's private key, initiator's public key) and learn whether the 1160 | candidate pair is correct. 1161 | 1162 | 6. Encrypted but with weak forward secrecy. An active attacker who 1163 | pretends to be the initiator without the initiator's static private key, 1164 | then later learns the initiator private key, can then decrypt the 1165 | responder's public key. 1166 | 1167 | 7. Not transmitted, but an active attacker who pretends to be the 1168 | initator without the initiator's static private key, then later learns a 1169 | candidate for the initiator private key, can then check whether the 1170 | candidate is correct. 1171 | 1172 | 8. Encrypted with forward secrecy to an authenticated party. 1173 | 1174 | 9. An active attacker who pretends to be the initiator and records a single 1175 | protocol run can then check candidates for the responder's public key. 1176 | 1177 | 1178 | 1179 | +------------------------------------------+ 1180 | | Initiator Responder | 1181 | +------------------------------------------+ 1182 | | N - 3 | 1183 | +------------------------------------------+ 1184 | | K 5 5 | 1185 | +------------------------------------------+ 1186 | | X 4 3 | 1187 | +------------------------------------------+ 1188 | | NN - - | 1189 | +------------------------------------------+ 1190 | | NK - 3 | 1191 | +------------------------------------------+ 1192 | | NK1 - 9 | 1193 | +------------------------------------------+ 1194 | | NX - 1 | 1195 | +------------------------------------------+ 1196 | | XN 2 - | 1197 | +------------------------------------------+ 1198 | | XK 8 3 | 1199 | +------------------------------------------+ 1200 | | XK1 8 9 | 1201 | +------------------------------------------+ 1202 | | XX 8 1 | 1203 | +------------------------------------------+ 1204 | | KN 7 - | 1205 | +------------------------------------------+ 1206 | | KK 5 5 | 1207 | +------------------------------------------+ 1208 | | KX 7 6 | 1209 | +------------------------------------------+ 1210 | | IN 0 - | 1211 | +------------------------------------------+ 1212 | | IK 4 3 | 1213 | +------------------------------------------+ 1214 | | IK1 0 9 | 1215 | +------------------------------------------+ 1216 | | IX 0 6 | 1217 | +------------------------------------------+ 1218 | 1219 | \newpage 1220 | 1221 | # 8. Protocol names and modifiers 1222 | 1223 | To produce a **Noise protocol name** for `Initialize()` you concatenate the 1224 | ASCII string `"Noise_"` with four underscore-separated name sections which 1225 | sequentially name the handshake pattern, the DH functions, the cipher 1226 | functions, and then the hash functions. The resulting name must be 255 bytes 1227 | or less. Examples: 1228 | 1229 | * `Noise_XX_25519_AESGCM_SHA256` 1230 | * `Noise_N_25519_ChaChaPoly_BLAKE2s` 1231 | * `Noise_IK_448_ChaChaPoly_BLAKE2b` 1232 | 1233 | Each name section must consist only of alphanumeric characters (i.e. characters 1234 | in one of the ranges `"A"`...`"Z"`, `"a"`...`"z"`, and `"0"`...`"9"`), and the two special 1235 | characters `"+"` and `"/"`. 1236 | 1237 | Additional rules apply to each name section, as specified below. 1238 | 1239 | ## 8.1. Handshake pattern name section 1240 | 1241 | A handshake pattern name section contains a handshake pattern name plus a 1242 | sequence of zero or more **pattern modifiers**. 1243 | 1244 | The handshake pattern name must be an uppercase ASCII string containing only 1245 | alphabetic characters or numerals (e.g. `"XX1"` or `"IK"`). 1246 | 1247 | Pattern modifiers specify arbitrary extensions or modifications to the behavior 1248 | specified by the handshake pattern. For example, a modifier could be applied 1249 | to a handshake pattern which transforms it into a different pattern according 1250 | to some rule. The `"psk0"` and `"fallback"` modifiers are examples of this, 1251 | and will be defined later in this document. 1252 | 1253 | A pattern modifier is named with a lowercase alphanumeric ASCII string which 1254 | must begin with an alphabetic character (not a numeral). The pattern modifier 1255 | is appended to the base pattern as described below: 1256 | 1257 | The first modifier added onto a base pattern is simply appended. Thus 1258 | the `"fallback"` modifier, when added to the `"XX"` pattern, produces `"XXfallback"`. 1259 | Additional modifiers are separated with a plus sign. Thus, adding the `"psk0"` 1260 | modifier would result in the name section `"XXfallback+psk0"`, or a 1261 | full protocol name such as `"Noise_XXfallback+psk0_25519_AESGCM_SHA256"`. 1262 | 1263 | In some cases the sequential ordering of modifiers will specify different 1264 | protocols. However, if the order of some modifiers does not matter, then they are 1265 | required to be sorted alphabetically (this is an arbitrary convention to ensure 1266 | interoperability). 1267 | 1268 | ## 8.2. Cryptographic algorithm name sections 1269 | 1270 | The rules for the DH, cipher, and hash name sections are identical. Each name 1271 | section must contain one or more algorithm names separated by plus signs. 1272 | 1273 | Each algorithm name must consist solely of alphanumeric characters and the 1274 | forward-slash character (`"/"`). Algorithm names are recommended to be short, 1275 | and to use the `"/"` character only when necessary to avoid ambiguity (e.g. 1276 | `"SHA3/256"` is preferable to `"SHA3256"`). 1277 | 1278 | In most cases there will be a single algorithm name in each name section (i.e. 1279 | no plus signs). Multiple algorithm names are only used when called for by the 1280 | pattern or a modifier. 1281 | 1282 | None of the patterns or modifiers in this document require multiple algorithm 1283 | names in any name section. However, this functionality might be useful in 1284 | future extensions. For example, multiple algorithm names might be used in the 1285 | DH section to specify "hybrid" post-quantum forward secrecy; or multiple hash 1286 | algorithms might be specified for different purposes. 1287 | 1288 | # 9. Pre-shared symmetric keys 1289 | 1290 | Noise provides a **pre-shared symmetric key** or **PSK** mode to support 1291 | protocols where both parties have a 32-byte shared secret key. 1292 | 1293 | ## 9.1. Cryptographic functions 1294 | 1295 | PSK mode uses the `SymmetricState.MixKeyAndHash()` function to mix the PSK into both the encryption keys and the `h` value. 1296 | 1297 | Note that `MixKeyAndHash()` uses `HKDF(..., 3)`. The third output from `HKDF()` is used as the `k` value so that calculation of `k` may be skipped if `k` is not used. 1298 | 1299 | ## 9.2. Handshake tokens 1300 | 1301 | In a PSK handshake, a `"psk"` token is allowed to appear one or more times in a 1302 | handshake pattern. This token can only appear in message patterns (not 1303 | pre-message patterns). This token is processed by calling 1304 | `MixKeyAndHash(psk)`, where `psk` is a 32-byte secret value provided by the 1305 | application. 1306 | 1307 | In non-PSK handshakes, the `"e"` token in a pre-message pattern or message pattern always 1308 | results in a call to `MixHash(e.public_key)`. In a PSK handshake, all of these calls 1309 | are followed by `MixKey(e.public_key)`. In conjunction with the validity rule in the 1310 | next section, this ensures that PSK-based encryption uses encryption keys that are randomized using 1311 | ephemeral public keys as nonces. 1312 | 1313 | ## 9.3. Validity rule 1314 | 1315 | To prevent catastrophic key reuse, handshake patterns using the `"psk"` token must follow an additional validity rule: 1316 | 1317 | * A party may not send any encrypted data after it processes a `"psk"` token unless it has previously 1318 | sent an ephemeral public key (an `"e"` token), either before or after the `"psk"` token. 1319 | 1320 | This rule guarantees that a `k` derived from a PSK will never be used for 1321 | encryption unless it has also been randomized by `MixKey(e.public_key)` 1322 | using a self-chosen ephemeral public key. 1323 | 1324 | ## 9.4. Pattern modifiers 1325 | 1326 | To indicate PSK mode and the placement of the `"psk"` token, pattern modifiers 1327 | are used (see [Section 8](#protocol-names-and-modifiers)). The modifier `psk0` places a `"psk"` 1328 | token at the beginning of the first handshake message. The modifiers 1329 | `psk1`, `psk2`, etc., place a `"psk"` token at the end of the 1330 | first, second, etc., handshake message. 1331 | 1332 | Any pattern using one of these modifiers must process tokens according to the rules in [Section 9.2](#handshake-tokens]), and must follow the validity rule in [Section 9.3](#validity-rule). 1333 | 1334 | The table below lists some unmodified one-way patterns on the left, and the recommended 1335 | PSK pattern on the right: 1336 | 1337 | 1338 | +--------------------------------+--------------------------------------+ 1339 | | N: | Npsk0: | 1340 | | <- s | <- s | 1341 | | ... | ... | 1342 | | -> e, es | -> psk, e, es | 1343 | | | | 1344 | +--------------------------------+--------------------------------------+ 1345 | | K: | Kpsk0: | 1346 | | -> s | -> s | 1347 | | <- s | <- s | 1348 | | ... | ... | 1349 | | -> e, es, ss | -> psk, e, es, ss | 1350 | | | | 1351 | +--------------------------------+--------------------------------------+ 1352 | | X: | Xpsk1: | 1353 | | <- s | <- s | 1354 | | ... | ... | 1355 | | -> e, es, s, ss | -> e, es, s, ss, psk | 1356 | | | | 1357 | +--------------------------------+--------------------------------------+ 1358 | 1359 | Note that the `psk1` modifier is recommended for `X`. This is because 1360 | `X` transmits the initiator's static public key. Because PSKs are 1361 | typically pairwise, the responder likely cannot determine the PSK until it has 1362 | decrypted the initiator's static public key. Thus, `psk1` is likely to be more 1363 | useful here than `psk0`. 1364 | 1365 | Following similar logic, we can define the most likely interactive PSK patterns: 1366 | 1367 | +--------------------------------+--------------------------------------+ 1368 | | NN: | NNpsk0: | 1369 | | -> e | -> psk, e | 1370 | | <- e, ee | <- e, ee | 1371 | +--------------------------------+--------------------------------------+ 1372 | | NN: | NNpsk2: | 1373 | | -> e | -> e | 1374 | | <- e, ee | <- e, ee, psk | 1375 | +--------------------------------+--------------------------------------+ 1376 | | NK: | NKpsk0: | 1377 | | <- s | <- s | 1378 | | ... | ... | 1379 | | -> e, es | -> psk, e, es | 1380 | | <- e, ee | <- e, ee | 1381 | +--------------------------------+--------------------------------------+ 1382 | | NK: | NKpsk2: | 1383 | | <- s | <- s | 1384 | | ... | ... | 1385 | | -> e, es | -> e, es | 1386 | | <- e, ee | <- e, ee, psk | 1387 | +--------------------------------+--------------------------------------+ 1388 | | NX: | NXpsk2: | 1389 | | -> e | -> e | 1390 | | <- e, ee, s, es | <- e, ee, s, es, psk | 1391 | +--------------------------------+--------------------------------------+ 1392 | | XN: | XNpsk3: | 1393 | | -> e | -> e | 1394 | | <- e, ee | <- e, ee | 1395 | | -> s, se | -> s, se, psk | 1396 | +--------------------------------+--------------------------------------+ 1397 | | XK: | XKpsk3: | 1398 | | <- s | <- s | 1399 | | ... | ... | 1400 | | -> e, es | -> e, es | 1401 | | <- e, ee | <- e, ee | 1402 | | -> s, se | -> s, se, psk | 1403 | +--------------------------------+--------------------------------------+ 1404 | | XX: | XXpsk3: | 1405 | | -> e | -> e | 1406 | | <- e, ee, s, es | <- e, ee, s, es | 1407 | | -> s, se | -> s, se, psk | 1408 | +--------------------------------+--------------------------------------+ 1409 | | KN: | KNpsk0: | 1410 | | -> s | -> s | 1411 | | ... | ... | 1412 | | -> e | -> psk, e | 1413 | | <- e, ee, se | <- e, ee, se | 1414 | +--------------------------------+--------------------------------------+ 1415 | | KN: | KNpsk2: | 1416 | | -> s | -> s | 1417 | | ... | ... | 1418 | | -> e | -> e | 1419 | | <- e, ee, se | <- e, ee, se, psk | 1420 | +--------------------------------+--------------------------------------+ 1421 | | KK: | KKpsk0: | 1422 | | -> s | -> s | 1423 | | <- s | <- s | 1424 | | ... | ... | 1425 | | -> e, es, ss | -> psk, e, es, ss | 1426 | | <- e, ee, se | <- e, ee, se | 1427 | +--------------------------------+--------------------------------------+ 1428 | | KK: | KKpsk2: | 1429 | | -> s | -> s | 1430 | | <- s | <- s | 1431 | | ... | ... | 1432 | | -> e, es, ss | -> e, es, ss | 1433 | | <- e, ee, se | <- e, ee, se, psk | 1434 | +--------------------------------+--------------------------------------+ 1435 | | KX: | KXpsk2: | 1436 | | -> s | -> s | 1437 | | ... | ... | 1438 | | -> e | -> e | 1439 | | <- e, ee, se, s, es | <- e, ee, se, s, es, psk | 1440 | +--------------------------------+--------------------------------------+ 1441 | | IN: | INpsk1: | 1442 | | -> e, s | -> e, s, psk | 1443 | | <- e, ee, se | <- e, ee, se | 1444 | | | | 1445 | +--------------------------------+--------------------------------------+ 1446 | | IN: | INpsk2: | 1447 | | -> e, s | -> e, s | 1448 | | <- e, ee, se | <- e, ee, se, psk | 1449 | | | | 1450 | +--------------------------------+--------------------------------------+ 1451 | | IK: | IKpsk1: | 1452 | | <- s | <- s | 1453 | | ... | ... | 1454 | | -> e, es, s, ss | -> e, es, s, ss, psk | 1455 | | <- e, ee, se | <- e, ee, se | 1456 | | | | 1457 | +--------------------------------+--------------------------------------+ 1458 | | IK: | IKpsk2: | 1459 | | <- s | <- s | 1460 | | ... | ... | 1461 | | -> e, es, s, ss | -> e, es, s, ss | 1462 | | <- e, ee, se | <- e, ee, se, psk | 1463 | | | | 1464 | +--------------------------------+--------------------------------------+ 1465 | | IX: | IXpsk2: | 1466 | | -> e, s | -> e, s | 1467 | | <- e, ee, se, s, es | <- e, ee, se, s, es, psk | 1468 | | | | 1469 | +--------------------------------+--------------------------------------+ 1470 | 1471 | The above list does not exhaust all possible patterns that can be formed with 1472 | these modifiers. In particular, any of these PSK modifiers can be safely 1473 | applied to any previously named pattern, resulting in patterns like 1474 | `IKpsk0`, `KKpsk1`, or even `XXpsk0+psk3`, which aren't 1475 | listed above. 1476 | 1477 | This still doesn't exhaust all the ways that `"psk"` tokens could be used 1478 | outside of these modifiers (e.g. placement of `"psk"` tokens in the middle of a 1479 | message pattern). Defining additional PSK modifiers is outside the scope of 1480 | this document. 1481 | 1482 | # 10. Compound protocols 1483 | 1484 | ## 10.1. Rationale for compound protocols 1485 | 1486 | So far we've assumed Alice and Bob wish to execute a single Noise protocol 1487 | chosen by the initiator (Alice). However, there are a number of reasons why 1488 | Bob might wish to switch to a different Noise protocol after receiving 1489 | Alice's first message. For example: 1490 | 1491 | * Alice might have chosen a Noise protocol based on a cipher, DH function, or 1492 | handshake pattern which Bob doesn't support. 1493 | 1494 | * Alice might have sent a "zero-RTT" encrypted initial message based on an out-of-date 1495 | version of Bob's static public key or PSK. 1496 | 1497 | Handling these scenarios requires a **compound protocol** where Bob switches 1498 | from the initial Noise protocol chosen by Alice to a new Noise protocol. In such a 1499 | compound protocol the roles of initiator and responder would be reversed - Bob 1500 | would become the initiator of the new Noise protocol, and Alice the responder. 1501 | 1502 | Compound protocols introduce significant complexity as Alice needs to advertise 1503 | the Noise protocol she is beginning with and the Noise protocol(s) she is 1504 | capable of switching to, and both parties have to negotiate a secure transition. 1505 | 1506 | These details are largely out of scope for this document. However, to give an 1507 | example of how compound protocols can be constructed, and to provide some 1508 | building blocks, the following sections define a **`fallback`** modifier and show 1509 | how it can be used to create a **Noise Pipe** compound protocol. 1510 | 1511 | Noise Pipes support the `XX` pattern, but also allow Alice to cache Bob's 1512 | static public key and attempt an `IK` handshake with 0-RTT encryption. 1513 | 1514 | In case Bob can't decrypt Alice's initial `IK` message, he will switch to the 1515 | `XXfallback` pattern, which essentially allows the parties to complete an `XX` 1516 | handshake as if Alice had sent an `XX` initial message instead of an `IK` initial message. 1517 | 1518 | ## 10.2. The `fallback` modifier 1519 | 1520 | The `fallback` modifier converts an Alice-initiated pattern to a Bob-initiated 1521 | pattern by converting Alice's initial message to a pre-message that Bob must 1522 | receive through some other means (e.g. via an initial `IK` message from Alice). 1523 | After this conversion, the rest of the handshake pattern is interpreted as a 1524 | Bob-initiated handshake pattern. 1525 | 1526 | For example, here is the `fallback` modifier applied to `XX` to produce `XXfallback`: 1527 | 1528 | \newpage 1529 |   1530 | 1531 | XX: 1532 | -> e 1533 | <- e, ee, s, es 1534 | -> s, se 1535 | 1536 | XXfallback: 1537 | -> e 1538 | ... 1539 | <- e, ee, s, es 1540 | -> s, se 1541 | 1542 | Note that `fallback` can only be applied to handshake patterns in Alice-initiated form where Alice's first message is capable of being interpreted as a pre-message (i.e. it must be either `"e"`, `"s"`, or `"e, s"`). 1543 | 1544 | ## 10.3. Zero-RTT and Noise protocols 1545 | 1546 | A typical compound protocol for zero-RTT encryption involves three different Noise protocols: 1547 | 1548 | * A **full protocol** is used if Alice doesn't possess stored information about Bob that would enable zero-RTT encryption, or doesn't wish to use the zero-RTT handshake. 1549 | 1550 | * A **zero-RTT protocol** allows encryption of data in the initial message. 1551 | 1552 | * A **switch protocol** is triggered by Bob if he can't decrypt Alice's first zero-RTT handshake message. 1553 | 1554 | There must be some way for Bob to distinguish the full versus zero-RTT cases 1555 | on receiving the first message. If Alice makes a zero-RTT attempt, there must 1556 | be some way for her to distinguish the zero-RTT versus switch cases on receiving 1557 | the response. 1558 | 1559 | For example, each handshake message could be preceded by some negotiation data, 1560 | such as a `type` byte (see [Section 13](#application-responsibilities)). This 1561 | data is not part of the Noise message proper, but signals which Noise protocol 1562 | is being used. 1563 | 1564 | ## 10.4. Noise Pipes 1565 | 1566 | This section defines the **Noise Pipe** compound protocol. The following 1567 | handshake patterns satisfy the full, zero-RTT, and switch roles discussed in 1568 | the previous section, so can be used to provide a full handshake with a simple 1569 | zero-RTT option: 1570 | 1571 | XX: 1572 | -> e 1573 | <- e, ee, s, es 1574 | -> s, se 1575 | 1576 | IK: 1577 | <- s 1578 | ... 1579 | -> e, es, s, ss 1580 | <- e, ee, se 1581 | 1582 | XXfallback: 1583 | -> e 1584 | ... 1585 | <- e, ee, s, es 1586 | -> s, se 1587 | 1588 | The `XX` pattern is used for a **full handshake** if the parties haven't 1589 | communicated before, after which Alice can cache Bob's static 1590 | public key. 1591 | 1592 | The `IK` pattern is used for a **zero-RTT handshake**. 1593 | 1594 | The `XXfallback` pattern is used for a **switch handshake** if Bob fails to 1595 | decrypt an initial `IK` message (perhaps due to having changed his static key). 1596 | 1597 | ## 10.5. Handshake indistinguishability 1598 | 1599 | Parties might wish to hide from an eavesdropper which type of handshake they are 1600 | performing. For example, suppose parties are using Noise Pipes, and want to 1601 | hide whether they are performing a full handshake, zero-RTT handshake, or 1602 | fallback handshake. 1603 | 1604 | This is fairly easy: 1605 | 1606 | * The first three messages can have their payloads padded with random bytes to 1607 | a constant size, regardless of which handshake is executed. 1608 | 1609 | * Bob will attempt to decrypt the first message as an `IK` message, 1610 | and will switch to `XXfallback` if decryption fails. 1611 | 1612 | * An Alice who sends an `IK` initial message can use trial decryption 1613 | to differentiate between a response using `IK` or `XXfallback`. 1614 | 1615 | * An Alice attempting a full handshake will send an ephemeral public key, then 1616 | random padding, and will use `XXfallback` to handle the response. Note that 1617 | `XX` isn't used, because the server can't distinguish an `XX` message from a 1618 | failed `IK` attempt by using trial decryption. 1619 | 1620 | This leaves the Noise ephemeral public keys in the clear. Ephemeral public 1621 | keys are randomly chosen DH public values, but they will typically have enough 1622 | structure that an eavesdropper might suspect the parties are using Noise, even 1623 | if the eavesdropper can't distinguish the different handshakes. To make the 1624 | ephemerals indistinguishable from random byte sequences, techniques like 1625 | Elligator [@elligator] could be used. 1626 | 1627 | # 11. Advanced features 1628 | 1629 | ## 11.1. Dummy keys 1630 | 1631 | Consider a protocol where an initiator will authenticate herself if the responder 1632 | requests it. This could be viewed as the initiator choosing between patterns 1633 | like `NX` and `XX` based on some value inside the responder's first 1634 | handshake payload. 1635 | 1636 | Noise doesn't directly support this. Instead, this could be simulated by 1637 | always executing `XX`. The initiator can simulate the `NX` case by 1638 | sending a **dummy static public key** if authentication is not requested. The 1639 | value of the dummy public key doesn't matter. 1640 | 1641 | This technique is simple, since it allows use of a single handshake pattern. 1642 | It also doesn't reveal which option was chosen from message sizes or 1643 | computation time. It could be extended to allow an `XX` pattern to 1644 | support any permutation of authentications (initiator only, responder only, 1645 | both, or none). 1646 | 1647 | Similarly, **dummy PSKs** (e.g. a PSK of all zeros) would allow a protocol to 1648 | optionally support PSKs. 1649 | 1650 | ## 11.2. Channel binding 1651 | 1652 | Parties might wish to execute a Noise protocol, then perform authentication at 1653 | the application layer using signatures, passwords, or something else. 1654 | 1655 | To support this, Noise libraries may call `GetHandshakeHash()` after the 1656 | handshake is complete and expose the returned value to the application as a 1657 | **handshake hash** which uniquely identifies the Noise session. 1658 | 1659 | Parties can then sign the handshake hash, or hash it along with their password, 1660 | to get an authentication token which has a "channel binding" property: the 1661 | token can't be used by the receiving party with a different sesssion. 1662 | 1663 | ## 11.3. Rekey 1664 | Parties might wish to periodically update their cipherstate keys using a one-way function, so that a compromise of cipherstate keys will not decrypt older messages. Periodic rekey might also be used to reduce the volume of data encrypted under a single cipher key (this is usually not important with good ciphers, though note the discussion on `AESGCM` data volumes in [Section 14](#security-considerations)). 1665 | 1666 | To enable this, Noise supports a `Rekey()` function which may be called on a `CipherState`. 1667 | 1668 | It is up to to the application if and when to perform rekey. For example: 1669 | 1670 | * Applications might perform **continuous rekey**, where they rekey the relevant cipherstate after every transport message sent or received. This is simple and gives good protection to older ciphertexts, but might be difficult for implementations where changing keys is expensive. 1671 | 1672 | * Applications might rekey a cipherstate automatically after it has has been used to send or receive some number of messages. 1673 | 1674 | * Applications might choose to rekey based on arbitrary criteria, in which case they signal this to the other party by sending a message. 1675 | 1676 | Applications must make these decisions on their own; there are no pattern modifiers which specify rekey behavior. 1677 | 1678 | Note that rekey only updates the cipherstate's `k` value, it doesn't reset the cipherstate's `n` value, so applications performing rekey must still perform a new handshake if sending 2^64^ or more transport messages. 1679 | 1680 | ## 11.4. Out-of-order transport messages 1681 | 1682 | In some use cases, Noise transport messages might be lost or arrive 1683 | out-of-order (e.g. when messages are sent over UDP). To handle this, an 1684 | application protocol can send the `n` value used for encrypting each transport 1685 | message alongside that message. On receiving such a message the recipient 1686 | would call the `SetNonce()` function on the receiving `CipherState` using the 1687 | received `n` value. 1688 | 1689 | Recipients doing this must track the received `n` values for which decryption 1690 | was successful and reject any message which repeats such a value, to prevent 1691 | replay attacks. 1692 | 1693 | Note that lossy and out-of-order message delivery introduces many other concerns 1694 | (including out-of-order handshake messages and denial of service risks) which 1695 | are outside the scope of this document. 1696 | 1697 | ## 11.5. Half-duplex protocols 1698 | In some application protocols the parties strictly alternate sending messages. In this case Noise can be used in a **half-duplex** mode [@blinker] where the first `CipherState` returned by `Split()` is used for encrypting messages in both directions, and the second `CipherState` returned by `Split()` is unused. This allows some small optimizations, since `Split()` only has to calculate a single output `CipherState`, and both parties only need to store a single `CipherState` during the transport phase. 1699 | 1700 | This feature must be used with extreme caution. In particular, it would be a catastrophic security failure if the protocol is not strictly alternating and both parties encrypt different messages using the same `CipherState` and nonce value. 1701 | 1702 | 1703 | # 12. DH functions, cipher functions, and hash functions 1704 | 1705 | ## 12.1. The `25519` DH functions 1706 | 1707 | * **`GENERATE_KEYPAIR()`**: Returns a new Curve25519 key pair. 1708 | 1709 | * **`DH(keypair, public_key)`**: Executes the Curve25519 DH function (aka 1710 | "X25519" in [@rfc7748]). Invalid public key values will produce an output 1711 | of all zeros. 1712 | 1713 | Alternatively, implementations are allowed to detect inputs that 1714 | produce an all-zeros output and signal an error instead. This behavior is 1715 | discouraged because it adds complexity and implementation variance, and 1716 | does not improve security. This behavior is allowed because it might 1717 | match the behavior of some software. 1718 | 1719 | * **`DHLEN`** = 32 1720 | 1721 | ## 12.2. The `448` DH functions 1722 | 1723 | * **`GENERATE_KEYPAIR()`**: Returns a new Curve448 key pair. 1724 | 1725 | * **`DH(keypair, public_key)`**: Executes the Curve448 DH function (aka "X448" 1726 | in [@rfc7748]). Invalid public key values will produce an output of all 1727 | zeros. 1728 | 1729 | Alternatively, implementations are allowed to detect inputs that 1730 | produce an all-zeros output and signal an error instead. This behavior is 1731 | discouraged because it adds complexity and implementation variance, and 1732 | does not improve security. This behavior is allowed because it might 1733 | match the behavior of some software. 1734 | 1735 | * **`DHLEN`** = 56 1736 | 1737 | ## 12.3. The `ChaChaPoly` cipher functions 1738 | 1739 | * **`ENCRYPT(k, n, ad, plaintext)` / `DECRYPT(k, n, ad, ciphertext)`**: 1740 | `AEAD_CHACHA20_POLY1305` from [@rfc7539]. The 96-bit nonce is formed by 1741 | encoding 32 bits of zeros followed by little-endian encoding of `n`. 1742 | (Earlier implementations of ChaCha20 used a 64-bit nonce; with these 1743 | implementations it's compatible to encode `n` directly into the ChaCha20 1744 | nonce without the 32-bit zero prefix). 1745 | 1746 | ## 12.4. The `AESGCM` cipher functions 1747 | 1748 | * **`ENCRYPT(k, n, ad, plaintext)` / `DECRYPT(k, n, ad, ciphertext)`**: AES256 1749 | with GCM from [@nistgcm] with a 128-bit tag appended to the 1750 | ciphertext. The 96-bit nonce is formed by encoding 32 bits of zeros 1751 | followed by big-endian encoding of `n`. 1752 | 1753 | ## 12.5. The `SHA256` hash function 1754 | 1755 | * **`HASH(input)`**: `SHA-256` from [@nistsha2]. 1756 | * **`HASHLEN`** = 32 1757 | * **`BLOCKLEN`** = 64 1758 | 1759 | ## 12.6. The `SHA512` hash function 1760 | 1761 | * **`HASH(input)`**: `SHA-512` from [@nistsha2]. 1762 | * **`HASHLEN`** = 64 1763 | * **`BLOCKLEN`** = 128 1764 | 1765 | ## 12.7. The `BLAKE2s` hash function 1766 | 1767 | * **`HASH(input)`**: `BLAKE2s` from [@rfc7693] with digest length 32. 1768 | * **`HASHLEN`** = 32 1769 | * **`BLOCKLEN`** = 64 1770 | 1771 | ## 12.8. The `BLAKE2b` hash function 1772 | 1773 | * **`HASH(input)`**: `BLAKE2b` from [@rfc7693] with digest length 64. 1774 | * **`HASHLEN`** = 64 1775 | * **`BLOCKLEN`** = 128 1776 | 1777 | \newpage 1778 | 1779 | # 13. Application responsibilities 1780 | 1781 | An application built on Noise must consider several issues: 1782 | 1783 | * **Choosing crypto functions**: The `25519` DH functions are recommended for 1784 | typical uses, though the `448` DH functions might offer extra security 1785 | in case a cryptanalytic attack is developed against elliptic curve 1786 | cryptography. The `448` DH functions should be used with a 512-bit hash 1787 | like `SHA512` or `BLAKE2b`. The `25519` DH functions may be used with a 1788 | 256-bit hash like `SHA256` or `BLAKE2s`, though a 512-bit hash might offer 1789 | extra security in case a cryptanalytic attack is developed 1790 | against the smaller hash functions. `AESGCM` is hard to implement with 1791 | high speed and constant time in software. 1792 | 1793 | * **Extensibility**: Applications are recommended to use an extensible data 1794 | format for the payloads of all messages (e.g. JSON, Protocol Buffers). This 1795 | ensures that fields can be added in the future which are ignored by older 1796 | implementations. 1797 | 1798 | * **Padding**: Applications are recommended to use a data format for the 1799 | payloads of all encrypted messages that allows padding. This allows 1800 | implementations to avoid leaking information about message sizes. Using an 1801 | extensible data format, per the previous bullet, may be sufficient. 1802 | 1803 | * **Session termination**: Applications must consider that a sequence of Noise 1804 | transport messages could be truncated by an attacker. Applications should 1805 | include explicit length fields or termination signals inside of transport 1806 | payloads to signal the end of an interactive session, or the end of a 1807 | one-way stream of transport messages. 1808 | 1809 | * **Length fields**: Applications must handle any framing or additional 1810 | length fields for Noise messages, considering that a Noise message may be up 1811 | to 65535 bytes in length. If an explicit length field is needed, 1812 | applications are recommended to add a 16-bit big-endian length field prior 1813 | to each message. 1814 | 1815 | * **Negotiation data**: Applications might wish to support the transmission 1816 | of some negotiation data prior to the handshake, and/or prior to each 1817 | handshake message. Negotiation data could contain things like version 1818 | information and identifiers for Noise protocols. For example, a simple 1819 | approach would be to send a single-byte type field prior to each Noise 1820 | handshake message. More flexible approaches might send extensible 1821 | structures such as protobufs. Negotiation data introduces significant 1822 | complexity and security risks such as rollback attacks (see next section). 1823 | 1824 | \newpage 1825 | 1826 | # 14. Security considerations 1827 | 1828 | This section collects various security considerations: 1829 | 1830 | * **Authentication**: A Noise protocol with static public keys verifies that 1831 | the corresponding private keys are possessed by the participant(s), but it's 1832 | up to the application to determine whether the remote party's static public 1833 | key is acceptable. Methods for doing so include certificates which sign the 1834 | public key (and which may be passed in handshake payloads), preconfigured 1835 | lists of public keys, or "pinning" / "key-continuity" approaches where 1836 | parties remember public keys they encounter and check whether the same party 1837 | presents the same public key in the future. 1838 | 1839 | * **Session termination**: Preventing attackers from truncating a stream of 1840 | transport messages is an application responsibility. See previous section. 1841 | 1842 | * **Rollback**: If parties decide on a Noise protocol based on some previous 1843 | negotiation that is not included as prologue, then a rollback attack might 1844 | be possible. This is a particular risk with compound protocols, 1845 | and requires careful attention if a Noise handshake is preceded by 1846 | communication between the parties. 1847 | 1848 | * **Static key reuse**: A static key pair used with Noise should be used with 1849 | a single hash algorithm. The key pair should not be used outside of Noise, 1850 | nor with multiple hash algorithms. It is acceptable to use the static key 1851 | pair with different Noise protocols, provided the same hash algorithm is 1852 | used in all of them. (Reusing a Noise static key pair outside of Noise 1853 | would require extremely careful analysis to ensure the uses don't compromise 1854 | each other, and security proofs are preserved). 1855 | 1856 | * **PSK reuse**: A PSK used with Noise should be used with a single hash 1857 | algorithm. The PSK should not be used outside of Noise, nor with multiple 1858 | hash algorithms. 1859 | 1860 | * **Ephemeral key reuse**: Every party in a Noise protocol must send a fresh 1861 | ephemeral public key prior to sending any encrypted data. Ephemeral keys 1862 | must never be reused. Violating these rules is likely to cause catastrophic 1863 | key reuse. This is one rationale behind the patterns in [Section 1864 | 7](#handshake-patterns), and the validity rules in [Section 1865 | 7.3](#handshake-pattern-validity). It's also the reason why one-way 1866 | handshakes only allow transport messages from the sender, not the recipient. 1867 | 1868 | * **Misusing public keys as secrets**: It might be tempting to use a pattern 1869 | with a pre-message public key and assume that a successful handshake implies 1870 | the other party's knowledge of the public key. Unfortunately, this is not 1871 | the case, since setting public keys to invalid values might cause 1872 | predictable DH output. For example, a `Noise_NK_25519` initiator might send 1873 | an invalid ephemeral public key to cause a known DH output of all zeros, 1874 | despite not knowing the responder's static public key. If the parties want 1875 | to authenticate with a shared secret, it should be used as a PSK. 1876 | 1877 | * **Channel binding**: Depending on the DH functions, it might be possible 1878 | for a malicious party to engage in multiple sessions that derive the same 1879 | shared secret key by setting public keys to invalid values that cause 1880 | predictable DH output (as in the previous bullet). It might also be 1881 | possible to set public keys to equivalent values that cause the same DH 1882 | output for different inputs. This is why a higher-level protocol should use 1883 | the handshake hash (`h`) for a unique channel binding, instead of `ck`, as 1884 | explained in [Section 11.2](#channel-binding). 1885 | 1886 | * **Incrementing nonces**: Reusing a nonce value for `n` with the same key 1887 | `k` for encryption would be catastrophic. Implementations must carefully 1888 | follow the rules for nonces. Nonces are not allowed to wrap back to zero 1889 | due to integer overflow, and the maximum nonce value is reserved. This 1890 | means parties are not allowed to send more than 2^64^-1 transport messages. 1891 | 1892 | * **Protocol names**: The protocol name used with `Initialize()` must 1893 | uniquely identify the combination of handshake pattern and crypto functions 1894 | for every key it's used with (whether ephemeral key pair, static key pair, 1895 | or PSK). If the same secret key was reused with the same protocol name but 1896 | a different set of cryptographic operations then bad interactions could 1897 | occur. 1898 | 1899 | * **Pre-shared symmetric keys**: Pre-shared symmetric keys must be secret 1900 | values with 256 bits of entropy. 1901 | 1902 | * **Data volumes**: The `AESGCM` cipher functions suffer a gradual reduction 1903 | in security as the volume of data encrypted under a single key increases. 1904 | Due to this, parties should not send more than 2^56^ bytes (roughly 72 1905 | petabytes) encrypted by a single key. If sending such large volumes of data 1906 | is a possibility then different cipher functions should be chosen. 1907 | 1908 | * **Hash collisions**: If an attacker can find hash collisions on prologue 1909 | data or the handshake hash, they may be able to perform "transcript 1910 | collision" attacks that trick the parties into having different views of 1911 | handshake data. It is important to use Noise with 1912 | collision-resistant hash functions, and replace the hash function at any 1913 | sign of weakness. 1914 | 1915 | * **Implementation fingerprinting**: If this protocol is used in settings 1916 | with anonymous parties, care should be taken that implementations behave 1917 | identically in all cases. This may require mandating exact behavior for 1918 | handling of invalid DH public keys. 1919 | 1920 | \newpage 1921 | 1922 | # 15. Rationales 1923 | 1924 | This section collects various design rationales. 1925 | 1926 | ## 15.1. Ciphers and encryption 1927 | 1928 | Cipher keys and PSKs are 256 bits because: 1929 | 1930 | * 256 bits is a conservative length for cipher keys when considering 1931 | cryptanalytic safety margins, time/memory tradeoffs, multi-key attacks, 1932 | rekeying, and quantum attacks. 1933 | 1934 | * Pre-shared key length is fixed to simplify testing and implementation, and 1935 | to deter users from mistakenly using low-entropy passwords as pre-shared keys. 1936 | 1937 | Nonces are 64 bits because: 1938 | 1939 | * Some ciphers only have 64 bit nonces (e.g. Salsa20). 1940 | 1941 | * 64 bit nonces were used in the initial specification and implementations 1942 | of ChaCha20, so Noise nonces can be used with these implementations. 1943 | 1944 | * 64 bits makes it easy for the entire nonce to be treated as an integer 1945 | and incremented. 1946 | 1947 | * 96 bits nonces (e.g. in RFC 7539) are a confusing size where it's unclear if 1948 | random nonces are acceptable. 1949 | 1950 | The authentication data in a ciphertext (i.e. the authentication tag or synthetic IV) is 128 bits because: 1951 | 1952 | * Some algorithms (e.g. GCM) lose more security than an ideal MAC when 1953 | truncated. 1954 | 1955 | * Noise may be used in a wide variety of contexts, including where attackers 1956 | can receive rapid feedback on whether guesses for authentication data are correct. 1957 | 1958 | * A single fixed length is simpler than supporting variable-length tags. 1959 | 1960 | Ciphertexts are required to be indistinguishable from random because: 1961 | 1962 | * This makes Noise protocols easier to use with random padding (for length-hiding), or 1963 | for censorship-resistant "unfingerprintable" protocols, or with steganography. However note 1964 | that ephemeral keys are likely to be distinguishable from random unless a technique such 1965 | as Elligator [@elligator] is used. 1966 | 1967 | Rekey defaults to using encryption with the nonce 2^64^-1 because: 1968 | 1969 | * With `AESGCM` and `ChaChaPoly` rekey can be computed efficiently (the 1970 | "encryption" just needs to apply the cipher, and can skip calculation of 1971 | the authentication tag). 1972 | 1973 | Rekey doesn't reset `n` to zero because: 1974 | 1975 | * Leaving `n` unchanged is simple. 1976 | 1977 | * If the cipher has a weakness such that repeated rekeying gives rise to a cycle of keys, then letting `n` advance will avoid catastrophic reuse of the same `k` and `n` values. 1978 | 1979 | * Letting `n` advance puts a bound on the total number of encryptions that can be performed with a set of derived keys. 1980 | 1981 | The `AESGCM` data volume limit is 2^56^ bytes because: 1982 | 1983 | * This is 2^52^ AES blocks (each block is 16 bytes). The limit is based on 1984 | the risk of birthday collisions being used to rule out plaintext guesses. 1985 | The probability an attacker could rule out a random guess on a 2^56^ byte 1986 | plaintext is less than 1 in 1 million (roughly (2^52^ * 2^52^) / 2^128^). 1987 | 1988 | Cipher nonces are big-endian for `AESGCM`, and little-endian for `ChaCha20`, because: 1989 | 1990 | * ChaCha20 uses a little-endian block counter internally. 1991 | 1992 | * AES-GCM uses a big-endian block counter internally. 1993 | 1994 | * It makes sense to use consistent endianness in the cipher code. 1995 | 1996 | 1997 | ## 15.2. Hash functions and hashing 1998 | 1999 | The recommended hash function families are SHA2 and BLAKE2 because: 2000 | 2001 | * SHA2 is widely available and is often used alongside AES. 2002 | 2003 | * BLAKE2 is fast and similar to ChaCha20. 2004 | 2005 | Hash output lengths of both 256 bits and 512 bits are supported because: 2006 | 2007 | * 256-bit hashes provide sufficient collision resistance at the 128-bit 2008 | security level. 2009 | 2010 | * The 256-bit hashes (SHA-256 and BLAKE2s) require less RAM, and less computation when processing 2011 | smaller inputs (due to smaller block size), than SHA-512 and BLAKE2b. 2012 | 2013 | * SHA-256 and BLAKE2s are faster on 32-bit processors than the larger hashes, which use 64-bit operations internally. 2014 | 2015 | The `MixKey()` design uses HKDF because: 2016 | 2017 | * HKDF is well-known and HKDF "chains" are used in similar ways in other protocols (e.g. 2018 | Signal, IPsec, TLS 1.3). 2019 | 2020 | * HKDF has a published analysis [@hkdfpaper]. 2021 | 2022 | * HKDF applies multiple layers of hashing between each `MixKey()` input. This 2023 | "extra" hashing might mitigate the impact of hash function weakness. 2024 | 2025 | HMAC is used with all hash functions instead of allowing hashes to use a more 2026 | specialized function (e.g. keyed BLAKE2), because: 2027 | 2028 | * HKDF requires the use of HMAC, and some of the HKDF analysis in 2029 | [@hkdfpaper] depends on the nested structure of HMAC. 2030 | 2031 | * HMAC is widely used with Merkle-Damgard hashes such as SHA2. SHA3 2032 | candidates such as Keccak and BLAKE were required to be suitable with HMAC. 2033 | Thus, HMAC should be applicable to all widely-used hash functions. 2034 | 2035 | * HMAC applies nested hashing to process each input. This 2036 | "extra" hashing might mitigate the impact of hash function weakness. 2037 | 2038 | * HMAC (and HKDF) are widely-used constructions. If some weakness is found in a 2039 | hash function, cryptanalysts will likely analyze that weakness in the 2040 | context of HMAC and HKDF. 2041 | 2042 | * Applying HMAC consistently is simple, and avoids having custom designs with different 2043 | cryptanalytic properties when using different hash functions. 2044 | 2045 | * HMAC is easy to build on top of a hash function interface. If a more 2046 | specialized function (e.g. keyed BLAKE2) can't be implemented using only 2047 | the underlying hash, then it is not guaranteed to be available everywhere 2048 | the hash function is available. 2049 | 2050 | `MixHash()` is used instead of sending all inputs directly through `MixKey()` because: 2051 | 2052 | * `MixHash()` is more efficient than `MixKey()`. 2053 | 2054 | * `MixHash()` produces a non-secret `h` value that might be useful to 2055 | higher-level protocols, e.g. for channel-binding. 2056 | 2057 | The `h` value hashes handshake ciphertext instead of plaintext because: 2058 | 2059 | * This ensures `h` is a non-secret value that can be used for channel-binding or 2060 | other purposes without leaking secret information. 2061 | 2062 | * This provides stronger guarantees against ciphertext malleability. 2063 | 2064 | 2065 | ## 15.3. Other 2066 | 2067 | Big-endian length fields are recommended because: 2068 | 2069 | * Length fields are likely to be handled by parsing code where 2070 | big-endian "network byte order" is traditional. 2071 | 2072 | * Some ciphers use big-endian internally (e.g. GCM, SHA2). 2073 | 2074 | * While it's true that Curve25519, Curve448, and ChaCha20/Poly1305 use 2075 | little-endian, these will likely be handled by specialized libraries, so 2076 | there's not a strong argument for aligning with them. 2077 | 2078 | Session termination is left to the application because: 2079 | 2080 | * Providing a termination signal in Noise doesn't help the application much, 2081 | since the application still has to use the signal correctly. 2082 | 2083 | * For an application with its own termination signal, having a 2084 | second termination signal in Noise is likely to be confusing rather than helpful. 2085 | 2086 | Explicit random nonces (like TLS "Random" fields) are not used because: 2087 | 2088 | * One-time ephemeral public keys make explicit nonces unnecessary. 2089 | 2090 | * Explicit nonces allow reuse of ephemeral public keys. However reusing ephemerals (with periodic replacement) is more complicated, requires a secure time source, is less secure in case of ephemeral compromise, and only provides a small optimization, since key generation can be done for a fraction of the cost of a DH operation. 2091 | 2092 | * Explicit nonces increase message size. 2093 | 2094 | * Explicit nonces make it easier to "backdoor" crypto implementations, e.g. by modifying the RNG so that key recovery data is leaked through the nonce fields. 2095 | 2096 | 2097 | # 16. IPR 2098 | 2099 | The Noise specification (this document) is hereby placed in the public domain. 2100 | 2101 | \newpage 2102 | 2103 | # 17. Acknowledgements 2104 | 2105 | Noise is inspired by: 2106 | 2107 | * The NaCl and CurveCP protocols from Dan Bernstein et al [@nacl; @curvecp]. 2108 | * The SIGMA and HOMQV protocols from Hugo Krawczyk [@sigma; @homqv]. 2109 | * The Ntor protocol from Ian Goldberg et al [@ntor]. 2110 | * The analysis of OTR by Mario Di Raimondo et al [@otr]. 2111 | * The analysis by Caroline Kudla and Kenny Paterson of "Protocol 4" by Simon Blake-Wilson et al [@kudla2005; @blakewilson1997]. 2112 | * Mike Hamburg's proposals for a sponge-based protocol framework, which led to STROBE [@moderncryptostrobe; @strobe]. 2113 | * The KDF chains used in the Double Ratchet Algorithm [@doubleratchet]. 2114 | 2115 | General feedback on the spec and design came from: Moxie Marlinspike, Jason 2116 | Donenfeld, Rhys Weatherley, Mike Hamburg, David Wong, Jake McGinty, Tiffany 2117 | Bennett, Jonathan Rudenberg, Stephen Touset, Tony Arcieri, Alex Wied, Alexey 2118 | Ermishkin, Olaoluwa Osuntokun, Karthik Bhargavan, and Nadim Kobeissi. 2119 | 2120 | Helpful editorial feedback came from: Tom Ritter, Karthik Bhargavan, David 2121 | Wong, Klaus Hartke, Dan Burkert, Jake McGinty, Yin Guanhao, Nazar Mokrynskyi, 2122 | Keziah Elis Biermann, Justin Cormack, Katriel Cohn-Gordon, and Nadim Kobeissi. 2123 | 2124 | Helpful input and feedback on the key derivation design came from: Moxie 2125 | Marlinspike, Hugo Krawczyk, Samuel Neves, Christian Winnerlein, J.P. Aumasson, 2126 | and Jason Donenfeld. 2127 | 2128 | The PSK approach was largely motivated and designed by Jason Donenfeld, based 2129 | on his experience with PSKs in WireGuard. 2130 | 2131 | The deferred patterns resulted from discussions with Justin Cormack. The pattern 2132 | derivation rules in the Appendix are also from Justin Cormack. 2133 | 2134 | The security properties table for deferred patterns was derived by the 2135 | Noise Explorer tool, from Nadim Kobeissi. 2136 | 2137 | The rekey design benefited from discussions with Rhys Weatherley, Alexey 2138 | Ermishkin, and Olaoluwa Osuntokun. 2139 | 2140 | The BLAKE2 team (in particular J.P. Aumasson, Samuel Neves, and Zooko) 2141 | provided helpful discussion on using BLAKE2 with Noise. 2142 | 2143 | Jeremy Clark, Thomas Ristenpart, and Joe Bonneau gave feedback on earlier 2144 | versions. 2145 | 2146 | \newpage 2147 | 2148 | # 18. Appendices 2149 | 2150 | ## 18.1. Deferred patterns 2151 | 2152 | The following table lists all 23 deferred handshake patterns in the right 2153 | column, with their corresponding fundamental handshake pattern in the left 2154 | column. See [Section 7](#handshake-patterns) for an explanation of 2155 | fundamental and deferred patterns. 2156 | 2157 | +---------------------------+--------------------------------+ 2158 | | NK: | NK1: | 2159 | | <- s | <- s | 2160 | | ... | ... | 2161 | | -> e, es | -> e | 2162 | | <- e, ee | <- e, ee, es | 2163 | | | | 2164 | +---------------------------+--------------------------------+ 2165 | | NX: | NX1: | 2166 | | -> e | -> e | 2167 | | <- e, ee, s, es | <- e, ee, s | 2168 | | | -> es | 2169 | | | | 2170 | +---------------------------+--------------------------------+ 2171 | | XN: | X1N: | 2172 | | -> e | -> e | 2173 | | <- e, ee | <- e, ee | 2174 | | -> s, se | -> s | 2175 | | | <- se | 2176 | | | | 2177 | +---------------------------+--------------------------------+ 2178 | | XK: | X1K: | 2179 | | <- s | <- s | 2180 | | ... | ... | 2181 | | -> e, es | -> e, es | 2182 | | <- e, ee | <- e, ee | 2183 | | -> s, se | -> s | 2184 | | | <- se | 2185 | | | | 2186 | | | XK1: | 2187 | | | <- s | 2188 | | | ... | 2189 | | | -> e | 2190 | | | <- e, ee, es | 2191 | | | -> s, se | 2192 | | | | 2193 | | | X1K1: | 2194 | | | <- s | 2195 | | | ... | 2196 | | | -> e | 2197 | | | <- e, ee, es | 2198 | | | -> s | 2199 | | | <- se | 2200 | | | | 2201 | +---------------------------+--------------------------------+ 2202 | | XX: | X1X: | 2203 | | -> e | -> e | 2204 | | <- e, ee, s, es | <- e, ee, s, es | 2205 | | -> s, se | -> s | 2206 | | | <- se | 2207 | | | | 2208 | | | XX1: | 2209 | | | -> e | 2210 | | | <- e, ee, s | 2211 | | | -> es, s, se | 2212 | | | | 2213 | | | X1X1: | 2214 | | | -> e | 2215 | | | <- e, ee, s | 2216 | | | -> es, s | 2217 | | | <- se | 2218 | | | | 2219 | +---------------------------+--------------------------------+ 2220 | | KN: | K1N: | 2221 | | -> s | -> s | 2222 | | ... | ... | 2223 | | -> e | -> e | 2224 | | <- e, ee, se | <- e, ee | 2225 | | | -> se | 2226 | | | | 2227 | +---------------------------+--------------------------------+ 2228 | | KK: | K1K: | 2229 | | -> s | -> s | 2230 | | <- s | <- s | 2231 | | ... | ... | 2232 | | -> e, es, ss | -> e, es | 2233 | | <- e, ee, se | <- e, ee | 2234 | | | -> se | 2235 | | | | 2236 | | | KK1: | 2237 | | | -> s | 2238 | | | <- s | 2239 | | | ... | 2240 | | | -> e | 2241 | | | <- e, ee, se, es | 2242 | | | | 2243 | | | K1K1: | 2244 | | | -> s | 2245 | | | <- s | 2246 | | | ... | 2247 | | | -> e | 2248 | | | <- e, ee, es | 2249 | | | -> se | 2250 | | | | 2251 | +---------------------------+--------------------------------+ 2252 | | KX: | K1X: | 2253 | | -> s | -> s | 2254 | | ... | ... | 2255 | | -> e | -> e | 2256 | | <- e, ee, se, s, es | <- e, ee, s, es | 2257 | | | -> se | 2258 | | | | 2259 | | | KX1: | 2260 | | | -> s | 2261 | | | ... | 2262 | | | -> e | 2263 | | | <- e, ee, se, s | 2264 | | | -> es | 2265 | | | | 2266 | | | K1X1: | 2267 | | | -> s | 2268 | | | ... | 2269 | | | -> e | 2270 | | | <- e, ee, s | 2271 | | | -> se, es | 2272 | | | | 2273 | | | | 2274 | +---------------------------+--------------------------------+ 2275 | | IN: | I1N: | 2276 | | -> e, s | -> e, s | 2277 | | <- e, ee, se | <- e, ee | 2278 | | | -> se | 2279 | | | | 2280 | +---------------------------+--------------------------------+ 2281 | | IK: | I1K: | 2282 | | <- s | <- s | 2283 | | ... | ... | 2284 | | -> e, es, s, ss | -> e, es, s | 2285 | | <- e, ee, se | <- e, ee | 2286 | | | -> se | 2287 | | | | 2288 | | | IK1: | 2289 | | | <- s | 2290 | | | ... | 2291 | | | -> e, s | 2292 | | | <- e, ee, se, es | 2293 | | | | 2294 | | | I1K1: | 2295 | | | <- s | 2296 | | | ... | 2297 | | | -> e, s | 2298 | | | <- e, ee, es | 2299 | | | -> se | 2300 | | | | 2301 | +---------------------------+--------------------------------+ 2302 | | IX: | I1X: | 2303 | | -> e, s | -> e, s | 2304 | | <- e, ee, se, s, es | <- e, ee, s, es | 2305 | | | -> se | 2306 | | | | 2307 | | | IX1: | 2308 | | | -> e, s | 2309 | | | <- e, ee, se, s | 2310 | | | -> es | 2311 | | | | 2312 | | | I1X1: | 2313 | | | -> e, s | 2314 | | | <- e, ee, s | 2315 | | | -> se, es | 2316 | | | | 2317 | +---------------------------+--------------------------------+ 2318 | 2319 | \newpage 2320 | 2321 | ## 18.2. Security properties for deferred patterns 2322 | 2323 | The following table lists the the security properties for the Noise handshake 2324 | and transport payloads for all the deferred patterns in the previous section. 2325 | The security properties are labelled using the notation from [Section 7.7](#payload-security-properties). 2326 | 2327 | +--------------------------------------------------------------+ 2328 | | Source Destination | 2329 | +--------------------------------------------------------------+ 2330 | | NK1 | 2331 | | <- s | 2332 | | ... | 2333 | | -> e 0 0 | 2334 | | <- e, ee, es 2 1 | 2335 | | -> 0 5 | 2336 | +--------------------------------------------------------------+ 2337 | | NX1 | 2338 | | -> e 0 0 | 2339 | | <- e, ee, s 0 1 | 2340 | | -> es 0 3 | 2341 | | -> 2 1 | 2342 | | <- 0 5 | 2343 | +--------------------------------------------------------------+ 2344 | | X1N | 2345 | | -> e 0 0 | 2346 | | <- e, ee 0 1 | 2347 | | -> s 0 1 | 2348 | | <- se 0 3 | 2349 | | -> 2 1 | 2350 | +--------------------------------------------------------------+ 2351 | | X1K | 2352 | | <- s | 2353 | | ... | 2354 | | -> e, es 0 2 | 2355 | | <- e, ee 2 1 | 2356 | | -> s 0 5 | 2357 | | <- se 2 3 | 2358 | | -> 2 5 | 2359 | | <- 2 5 | 2360 | +--------------------------------------------------------------+ 2361 | | XK1 | 2362 | | <- s | 2363 | | ... | 2364 | | -> e 0 0 | 2365 | | <- e, ee, es 2 1 | 2366 | | -> s, se 2 5 | 2367 | | <- 2 5 | 2368 | +--------------------------------------------------------------+ 2369 | | X1K1 | 2370 | | <- s | 2371 | | ... | 2372 | | -> e 0 0 | 2373 | | <- e, ee, es 2 1 | 2374 | | -> s 0 5 | 2375 | | <- se 2 3 | 2376 | | -> 2 5 | 2377 | | <- 2 5 | 2378 | +--------------------------------------------------------------+ 2379 | | X1X | 2380 | | -> e 0 0 | 2381 | | <- e, ee, s, es 2 1 | 2382 | | -> s 0 5 | 2383 | | <- se 2 3 | 2384 | | -> 2 5 | 2385 | | <- 2 5 | 2386 | +--------------------------------------------------------------+ 2387 | | XX1 | 2388 | | -> e 0 0 | 2389 | | <- e, ee, s 0 1 | 2390 | | -> es, s, se 2 3 | 2391 | | <- 2 5 | 2392 | | -> 2 5 | 2393 | +--------------------------------------------------------------+ 2394 | | X1X1 | 2395 | | -> e 0 0 | 2396 | | <- e, ee, s 0 1 | 2397 | | -> es, s 0 3 | 2398 | | <- se 2 3 | 2399 | | -> 2 5 | 2400 | | <- 2 5 | 2401 | +--------------------------------------------------------------+ 2402 | | K1N | 2403 | | -> s | 2404 | | ... | 2405 | | -> e 0 0 | 2406 | | <- e, ee 0 1 | 2407 | | -> se 2 1 | 2408 | | <- 0 5 | 2409 | +--------------------------------------------------------------+ 2410 | | K1K | 2411 | | -> s | 2412 | | <- s | 2413 | | ... | 2414 | | -> e, es 0 2 | 2415 | | <- e, ee, se 2 1 | 2416 | | -> se 2 5 | 2417 | | <- 2 5 | 2418 | +--------------------------------------------------------------+ 2419 | | KK1 | 2420 | | -> s | 2421 | | <- s | 2422 | | ... | 2423 | | -> e 0 0 | 2424 | | <- e, ee, se, es 2 3 | 2425 | | -> 2 5 | 2426 | | <- 2 5 | 2427 | +--------------------------------------------------------------+ 2428 | | K1K1 | 2429 | | -> s | 2430 | | <- s | 2431 | | ... | 2432 | | -> e 0 0 | 2433 | | <- e, ee, es 2 1 | 2434 | | -> se 2 5 | 2435 | | <- 2 5 | 2436 | +--------------------------------------------------------------+ 2437 | | K1X | 2438 | | -> s | 2439 | | ... | 2440 | | -> e 0 0 | 2441 | | <- e, ee, s, es 2 1 | 2442 | | -> se 2 5 | 2443 | | <- 2 5 | 2444 | +--------------------------------------------------------------+ 2445 | | KX1 | 2446 | | -> s | 2447 | | ... | 2448 | | -> e 0 0 | 2449 | | <- e, ee, se, s 0 3 | 2450 | | -> es 2 3 | 2451 | | <- 2 5 | 2452 | | -> 2 5 | 2453 | +--------------------------------------------------------------+ 2454 | | K1X1 | 2455 | | -> s | 2456 | | ... | 2457 | | -> e 0 0 | 2458 | | <- e, ee, s 0 1 | 2459 | | -> se, es 2 3 | 2460 | | <- 2 5 | 2461 | | -> 2 5 | 2462 | +--------------------------------------------------------------+ 2463 | | I1N | 2464 | | -> e, s 0 0 | 2465 | | <- e, ee 0 1 | 2466 | | -> se 2 1 | 2467 | | <- 0 5 | 2468 | +--------------------------------------------------------------+ 2469 | | I1K | 2470 | | <- s | 2471 | | ... | 2472 | | -> e, es, s 0 2 | 2473 | | <- e, ee 2 1 | 2474 | | -> se 2 5 | 2475 | | <- 2 5 | 2476 | +--------------------------------------------------------------+ 2477 | | IK1 | 2478 | | <- s | 2479 | | ... | 2480 | | -> e, s 0 0 | 2481 | | <- e, ee, se, es 2 3 | 2482 | | -> 2 5 | 2483 | | <- 2 5 | 2484 | +--------------------------------------------------------------+ 2485 | | I1K1 | 2486 | | <- s | 2487 | | ... | 2488 | | -> e, s 0 0 | 2489 | | <- e, ee, es 2 1 | 2490 | | -> se 2 5 | 2491 | | <- 2 5 | 2492 | +--------------------------------------------------------------+ 2493 | | I1X | 2494 | | -> e, s 0 0 | 2495 | | <- e, ee, s, es 2 1 | 2496 | | -> se 2 5 | 2497 | | <- 2 5 | 2498 | +--------------------------------------------------------------+ 2499 | | IX1 | 2500 | | -> e, s 0 0 | 2501 | | <- e, ee, se, s 0 3 | 2502 | | -> es 2 3 | 2503 | | <- 2 5 | 2504 | | -> 2 5 | 2505 | +--------------------------------------------------------------+ 2506 | | I1X1 | 2507 | | -> e, s 0 0 | 2508 | | <- e, ee, s 0 1 | 2509 | | -> se, es 2 3 | 2510 | | <- 2 5 | 2511 | | -> 2 5 | 2512 | +--------------------------------------------------------------+ 2513 | 2514 | ## 18.3. Pattern derivation rules 2515 | 2516 | The following rules were used to derive the one-way, fundamental, and deferred handshake patterns. 2517 | 2518 | First, populate the pre-message contents as defined by the pattern name. 2519 | 2520 | Next populate the initiator's first message by applying the first rule from the below table which matches. Then delete the matching rule and repeat this process until no more rules can be applied. If this is a one-way pattern, it is now complete. 2521 | 2522 | Otherwise, populate the responder's first message in the same way. Once no more responder rules can be applied, then switch to the initiator's next message and repeat this process, switching messages until no more rules can be applied by either party. 2523 | 2524 | **Initiator rules:** 2525 | 2526 | 1. Send `"e"`. 2527 | 2. Perform `"ee"` if `"e"` has been sent, and received. 2528 | 3. Perform `"se"` if `"s"` has been sent, and `"e"` received. If initiator authentication is deferred, skip this rule for the first message in which it applies, then mark the initiator authentication as non-deferred. 2529 | 4. Perform `"es"` if `"e"` has been sent, and `"s"` received. If responder authentication is deferred, skip this rule for the first message in which it applies, then mark the responder authentication as non-deferred. 2530 | 5. Perform `"ss"` if `"s"` has been sent, and received, and `"es"` has been performed, and this is the first message, and initiator authentication is not deferred. 2531 | 6. Send `"s"` if this is the first message and initiator is "I" or one-way "X". 2532 | 7. Send `"s"` if this is not the first message and initiator is "X". 2533 | 2534 | **Responder rules:** 2535 | 2536 | 1. Send `"e"`. 2537 | 2. Perform `"ee"` if `"e"` has been sent, and received. 2538 | 3. Perform `"se"` if `"e"` has been sent, and `"s"` received. If initiator authentication is deferred, skip this rule for the first message in which it applies, then mark the initiator authentication as non-deferred. 2539 | 4. Perform `"es"` if `"s"` has been sent, and `"e"` received. If responder authentication is deferred, skip this rule for the first message in which it applies, then mark the responder authentication as non-deferred. 2540 | 5. Send `"s"` if responder is "X". 2541 | 2542 | \newpage 2543 | 2544 | ## 18.4. Change log 2545 | 2546 | 2547 | **Revision 34:** 2548 | 2549 | * Added official/unstable marking; the unstable only refers to the new deferred patterns, the rest of this document is considered stable. 2550 | 2551 | * Clarified DH() definition so that the identity element is an invalid value (not a generator), thus may be rejected. 2552 | 2553 | * Clarified ciphertext-indistinguishability requirement for AEAD schemes and added a rationale. 2554 | 2555 | * Clarified the order of hashing pre-message public keys. 2556 | 2557 | * Rewrote handshake patterns explanation for clarity. 2558 | 2559 | * Added new validity rule to disallow repeating the same DH operation. 2560 | 2561 | * Clarified the complex validity rule regarding ephemeral keys and key re-use. 2562 | 2563 | * Removed parenthesized list of keys from pattern notation, as it was redundant. 2564 | 2565 | * Added deferred patterns. 2566 | 2567 | * Renamed "Authentication" and "Confidentiality" security properties to "Source" and "Destination" to avoid confusion. 2568 | 2569 | * **[SECURITY]** Added a new identity-hiding property, and changed identity-hiding property 3 to discuss an identity equality-check attack. 2570 | 2571 | * Replaced "fallback patterns" concept with Bob-initiated pattern notation. 2572 | 2573 | * Rewrote section on compound protocols and pipes for clarity, including 2574 | clearer distinction between "switch protocol" and "fallback patterns". 2575 | 2576 | * De-emphasized "type byte" suggestion, and added a more general discussion of negotiation data. 2577 | 2578 | * **[SECURITY]** Added security considerations regarding static key reuse and PSK reuse. 2579 | 2580 | * Added pattern derivation rules to Appendix. 2581 | 2582 | \newpage 2583 | 2584 | # 19. References 2585 | -------------------------------------------------------------------------------- /output/noise.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/noiseprotocol/noise_spec/ecdf084ece2bf92b16b1201b6ae5c99d23fb4151/output/noise.pdf --------------------------------------------------------------------------------