noise-ruby 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6817736b9a72ca54f30ceb3238c9962fbd1f4a09092e9e0f783fec5a1035e9f
-  data.tar.gz: de1d7510423907f0b73fa4f4115916bb2044195dc4dbbf8acb1f83cb484f2e76
+  metadata.gz: 92da6ad3c1e14197a093a54fd4e70f26cfa6cb15aec9d7fe6686b664d79235b2
+  data.tar.gz: 2837519b1708e55d0a0a052c11c9fd05da2fef1c1a4d881624602070fd07a579
 SHA512:
-  metadata.gz: 3235949265d26680b60447ad79e7c2ef02824233343a948b3b6805cd519c5e3f1ff5b573abb2ab1feec11eb7e51523448e47ce787ed81bc0399e8ab86e2b8368
-  data.tar.gz: 29d18a35a9d052d117e2ce0422f2a165eedf85d8f53af2d4b77263af500a257d194237cfa274b6ee40d432fbb8366490ed30fffafdaffa7713d70593c4104559
+  metadata.gz: a36f16cb90bcb3ac4979031744dbd0d2de4e324e14209bc8ae4b073e92b5ee789c0b898ec641a6a92c59c7e07e4f7e4169140b0499e23695e11a31ea51ed5874
+  data.tar.gz: c12c1216154ce5bd8f37e7e6bb56a62cca0a5da7cfacc7bf2b8d2ed1014bd25a487450e62850092a1bee0f1847f2554f1f3bac5c8b216220eeea3c593cdc37c7

data/.dockerignore

@@ -4,5 +4,6 @@
 .rspec_status
 .ruby-lsp/
 coverage/
+interop/target/
 pkg/
 tmp/

data/.github/workflows/ruby.yml

@@ -53,3 +53,42 @@ jobs:
       - name: Run tests
         run: bundle exec rspec spec
 
+  interop:
+    runs-on: ubuntu-latest
+    # The suite finishes in seconds. Anything longer means two implementations are waiting on each
+    # other, and a job that hangs until the six hour default helps nobody.
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+
+      - name: Set up Rust
+        id: rust
+        uses: dtolnay/rust-toolchain@stable
+
+      # interop/target holds compiler fingerprints, so the toolchain belongs in the key: a new
+      # stable rustc has to start from a cache of its own rather than rebuild under an old one.
+      - name: Cache the interoperability harness build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            interop/target
+          key: interop-${{ runner.os }}-${{ steps.rust.outputs.cachekey }}-${{ hashFiles('interop/Cargo.lock') }}
+          restore-keys: interop-${{ runner.os }}-${{ steps.rust.outputs.cachekey }}-
+
+      - name: Build the interoperability harness
+        run: cargo build --release --locked
+        working-directory: interop
+
+      # A real handshake against snow, the Rust implementation. See interop/README.md.
+      - name: Run the interoperability suite
+        run: bundle exec rake interop
+

data/README.md

@@ -96,7 +96,7 @@ it.
 ```
 initiator = Noise::Connection::Initiator.new("Noise_NN_25519_ChaChaPoly_BLAKE2b")
 initiator.prologue = "test" # => "test"
-initiator.start_handshake # => true
+initiator.start_handshake
 cipher = initiator.write_message("") # => "\xB6\xF7gmxi\xAB\xBCY|t\xF0\x9D\x01A\ad\x92\xBBvp\x80ZNU\f=\x83\x81^\xFD\x15"
 ```
 
@@ -110,7 +110,7 @@ The responder responds messages to the initiator.
 ```
 responder = Noise::Connection::Responder.new("Noise_NN_25519_ChaChaPoly_BLAKE2b")
 responder.prologue = "test" # => "test"
-responder.start_handshake # => true
+responder.start_handshake
 plain = responder.read_message(cipher) # => ""
 cipher = responder.write_message("") # => "\v\xD9\x97'\xC0\xB1\xC9\xFFD\x8C\x7F\x18L\xB0\xF2\x14\xB0\x11\xC0\x90\xAAZ\xE1\x03\x17z)\xB81/5L\x16\xE3\xD1\xBE<{\xB8\xBB\xD6\xF1\x00\x10]\x99=\xD7"
 ```
@@ -161,6 +161,154 @@ initiator.rekey_encryption
 responder.rekey_decryption
 ```
 
+### Thread safety
+
+One connection belongs to one thread. A `Noise::Connection` holds its handshake state and its
+transport nonces in plain instance variables and never locks, so two threads that share one
+connection can encrypt two different plaintexts under the same nonce. That is not a small loss for
+either cipher this gem implements: reusing a nonce breaks the confidentiality of both messages and
+lets an attacker forge further ones.
+
+If an application has to reach one connection from more than one thread, it is responsible for
+serialising every call to it.
+
+This is deliberate rather than an omission. A lock inside the connection would make each call
+atomic without making concurrent use correct, because the transport nonce numbers the messages of
+a direction: two threads that both encrypt still produce a stream in an order the receiver cannot
+reconstruct. Only the application knows which message comes first, and deciding that order is
+itself the serialisation the lock cannot supply.
+
+Receiving is no easier. Decrypting a message that arrived out of order is a `decryption_nonce=`
+call followed by a `decrypt` call, and no lock taken one call at a time holds those two together.
+
+### Half-duplex mode
+
+Section 11.5 of the Noise specification describes protocols in which the two parties strictly take
+turns. Such a protocol may keep a single `CipherState` for both directions instead of one per
+direction, which halves what each party has to store after the handshake. Pass `half_duplex: true`
+to both parties to run that way.
+
+```
+initiator = Noise::Connection::Initiator.new("Noise_NN_25519_ChaChaPoly_SHA256", half_duplex: true)
+responder = Noise::Connection::Responder.new("Noise_NN_25519_ChaChaPoly_SHA256", half_duplex: true)
+```
+
+Because there is one `CipherState`, the methods that name a direction all reach it:
+`encryption_nonce` and `decryption_nonce` report the same count, setting either sets both, and
+`rekey_encryption` and `rekey_decryption` replace the same key.
+
+**The two parties must strictly alternate their transport messages.** They share one nonce, so a
+message in either direction advances the count both of them keep. If both parties encrypt before
+either decrypts, the two messages go out under the same nonce, which breaks the confidentiality of
+both and lets an attacker forge further ones. Nothing in this gem can detect that: it is the
+application protocol that has to guarantee the turn taking.
+
+Use it only when the protocol you are implementing calls for it. It is off by default, and a
+one-way pattern refuses it, because such a pattern has no messages to alternate.
+
+### Framing a connection for a socket
+
+`encrypt` and `decrypt` work on whole messages, which is the shape the Noise specification
+describes but not the shape a socket has. `Noise::Transport::Framed` puts a finished connection on
+top of an `IO` by writing each message preceded by its length, so that the reader knows how many
+bytes to take.
+
+```
+transport = Noise::Transport::Framed.new(connection, socket)
+
+transport.write("a message")
+message = transport.read
+```
+
+`read` returns one message, waiting until all of it has arrived however many pieces it comes in.
+It answers `nil` when the stream ends between messages, which is how the other party closes
+without cutting one in half, and raises `TruncatedMessageError` when the stream ends part way
+through one. `write` returns once the whole frame has gone out.
+
+Every failure ends the transport, so build a new connection rather than reading again. A
+`DecryptError` means the frame was not written by the party this connection shares a key with, or
+not in the order it claims. A `TruncatedMessageError` or a `ReadTimeoutError` leaves the bytes
+already taken out of the stream and nowhere to put them, so the next read would take the middle of
+a message for a length. Errors the socket itself raises, such as `Errno::ECONNRESET`, come through
+as they are.
+
+Pass `read_timeout:` in seconds to give up on a message that stops arriving:
+
+```
+transport = Noise::Transport::Framed.new(connection, socket, read_timeout: 30)
+```
+
+The timeout applies to each wait for more bytes rather than to the message as a whole, so a peer
+that sends a byte at a time holds the read open without ever tripping it. It needs a stream that
+answers `wait_readable`, which a socket does and a `StringIO` does not; asking for a timeout on
+one that cannot honour it raises `ArgumentError` rather than dropping it silently.
+
+The length goes out in the clear, as two big-endian bytes. Two are enough because a Noise message
+may not exceed 65535 bytes, and a payload is shorter than that by its authentication tag. The
+length being in the clear means this framing hides nothing about how long each message is; a
+protocol that has to hide its message sizes pads them, or encrypts the length as BOLT #8 does.
+
+Once a connection is framed, stop calling its `encrypt` and `decrypt` directly. A message that
+goes out unframed leaves the reader taking the next message's bytes for a length.
+
+### Lightning Network (BOLT #8)
+
+BOLT #8 is the transport the Lightning Network runs on: a `Noise_XK_secp256k1_ChaChaPoly_SHA256`
+handshake, then a byte stream in which every message is preceded by its own encrypted length.
+`Noise::Transport::Bolt8` owns that framing, so an application only has to run the handshake and
+hand over the finished connection.
+
+```
+name = Noise::Transport::Bolt8::PROTOCOL_NAME
+
+initiator = Noise::Connection::Initiator.new(name, keypairs: { s: local_static, rs: node_id })
+initiator.prologue = Noise::Transport::Bolt8::PROLOGUE
+initiator.start_handshake
+# ... exchange the three handshake messages over the socket ...
+
+transport = Noise::Transport::Bolt8.new(initiator, socket)
+transport.write("a lightning message")
+message = transport.read
+```
+
+It reads and writes exactly as `Framed` does above, `read_timeout:` and the `nil` that means the
+other party closed between messages included. What differs is the framing: the length is encrypted as a
+Noise message of its own rather than sent in the clear, so a watcher cannot tell how long each
+message is. `DecryptError` means the same thing it does there, and BOLT #8 requires the connection
+to be closed when it happens.
+
+Each direction replaces its key with `HKDF(ck, k)` once its nonce reaches 1000, which is every 500
+messages because each message is encrypted twice. This is not the `rekey_encryption` of the Noise
+specification: it draws on the chaining key the handshake ended with, so a key stolen now says
+nothing about the keys that direction used before it. The transport does it on its own; nothing
+has to be called.
+
+The transport takes over the connection's transport phase: it holds the very `CipherState`s the
+connection does. Once a connection is wrapped, stop calling its `encrypt`, `decrypt`, nonce
+accessors and rekey methods, because each of them moves the same key and nonce and the peer has no
+way to learn that they did. A half-duplex connection is refused outright, since BOLT #8 gives each
+direction a key of its own.
+
+Nothing else in the gem loads this. An application that does not speak Lightning never names
+`Noise::Transport::Bolt8`, and never pays for it.
+
+## Interoperability
+
+The suite checks this gem against the official test vectors in `spec/vectors/`, which are replayed
+transcripts. `interop/` runs the other kind of test: a real handshake, and then a real transport
+exchange, between this gem and [snow](https://github.com/mcginty/snow), the Rust implementation of
+the framework. It covers eighteen patterns against five cipher and hash suites, in both
+directions.
+
+It needs a Rust toolchain, so it is not part of `bundle exec rspec`:
+
+```
+cd interop && cargo build --release && cd ..
+bundle exec rake interop
+```
+
+See [interop/README.md](interop/README.md) for what it covers and what it does not.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -5,4 +5,16 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
+desc 'Build the harness the interoperability suite runs against'
+task :interop_harness do
+  Dir.chdir('interop') { sh 'cargo build --release --locked' }
+end
+
+desc 'Run the interoperability suite against the snow reference implementation'
+RSpec::Core::RakeTask.new(interop: :interop_harness) do |task|
+  task.pattern = 'interop/*_spec.rb'
+end
+
+# interop is deliberately left out: it needs a Rust toolchain, and the harness built from
+# interop/. See interop/README.md.
 task default: :spec

data/lib/noise/connection/base.rb

@@ -2,6 +2,39 @@
 
 module Noise
   module Connection
+    # A connection moves through four states, and every public operation is legal in some of them
+    # and not in others:
+    #
+    #   :created         -- start_handshake
+    #   :handshake_write -- write_message, fallback
+    #   :handshake_read  -- read_message, fallback
+    #   :transport       -- encrypt, decrypt, rekey_*, the nonce accessors
+    #
+    # start_handshake moves :created to the state this party starts the pattern in, which is
+    # :handshake_write for the initiator and :handshake_read for the responder. Writing or reading
+    # a handshake message passes the turn to the other party, and the message that completes the
+    # pattern moves the connection to :transport.
+    #
+    # == Threads
+    #
+    # One connection belongs to one thread. Nothing here is synchronised: the state above is a
+    # plain instance variable, and #encrypt and #decrypt advance the transport nonce with a plain
+    # +=, so two threads that share a connection can encrypt two different plaintexts under the
+    # same nonce. Neither ChaChaPoly nor AESGCM degrades gracefully when that happens: reusing a
+    # nonce breaks the confidentiality of both messages and lets an attacker forge further ones.
+    #
+    # A caller that has to reach one connection from more than one thread is responsible for
+    # serialising every call to it.
+    #
+    # This class deliberately does not lock. A Mutex would make each call atomic without making
+    # concurrent use correct: the transport nonce numbers the messages of a direction, so two
+    # threads that both encrypt still hand the transport layer a stream whose order the receiver
+    # cannot reconstruct. Only the application knows which message is meant to be first, and once
+    # it has said so, its own serialisation has already done what the lock would have done.
+    #
+    # The other direction is no better. Decrypting a message that arrived out of order is a
+    # #decryption_nonce= call followed by a #decrypt call, a sequence no per-call lock can hold
+    # together.
     class Base
       # The Noise spec caps a handshake or transport message at 65535 bytes. A transport message is
       # the ciphertext, so the plaintext a caller may hand to encrypt is shorter by the
@@ -9,7 +42,29 @@ module Noise
       MAX_MESSAGE_LENGTH = 65_535
       MAX_PLAINTEXT_LENGTH = MAX_MESSAGE_LENGTH - Noise::State::CipherState::TAG_LENGTH
 
-      attr_reader :protocol, :handshake_started, :handshake_finished, :handshake_hash, :handshake_state,
+      # The states in which the connection is running a handshake, and what it expects next in
+      # each of them. The message explains a HandshakeTurnError.
+      TURN_MESSAGES = {
+        handshake_write: 'This party writes the next handshake message; it cannot read one yet.',
+        handshake_read: 'This party reads the next handshake message; it cannot write one yet.'
+      }.freeze
+      private_constant :TURN_MESSAGES
+
+      # The states in which a handshake is running, which are the ones #fallback may be called in.
+      HANDSHAKE_STATES = TURN_MESSAGES.keys.freeze
+      private_constant :HANDSHAKE_STATES
+
+      # @return [Symbol] the current state, one of :created, :handshake_write, :handshake_read and
+      #   :transport.
+      attr_reader :state
+
+      # @return [String, nil] the chaining key the handshake ended with, once it has. Split()
+      #   derives the transport keys from it and leaves it as it is, so a transport layer that
+      #   derives its own keys from it later — BOLT #8 rotates its keys this way — needs it after
+      #   the handshake. It is as secret as the transport keys it produced.
+      attr_reader :chaining_key
+
+      attr_reader :protocol, :handshake_hash, :handshake_state,
                   :cipher_state_encrypt, :cipher_state_decrypt, :cipher_state_handshake, :s, :rs
       attr_accessor :psks, :prologue
 
@@ -23,37 +78,87 @@ module Noise
       #   the keypair given here instead of generating a fresh one, and an ephemeral key reused
       #   across handshakes gives up the forward secrecy every pattern depends on. The handshake
       #   still succeeds, so nothing reports the loss.
-      def initialize(name, keypairs: { s: nil, e: nil, rs: nil, re: nil })
+      # @param [Boolean] half_duplex whether to run the transport phase in half-duplex mode, in
+      #   which one CipherState encrypts both directions. See #half_duplex? for what that costs.
+      # @raise [Noise::Exceptions::NoiseValidationError] if half_duplex is asked for on a one-way
+      #   pattern, which has no messages to alternate.
+      def initialize(name, keypairs: { s: nil, e: nil, rs: nil, re: nil }, half_duplex: false)
         @protocol = Protocol.create(name)
+        @half_duplex = half_duplex
+        validate_half_duplex!
 
         # parameter keypairs[:e] and keypairs[:s] are strings, so should convert Noise::Key object.
         @local_keypairs = {}
         @local_keypairs[:e] = @protocol.dh_fn.class.from_private(keypairs[:e]) if keypairs[:e]
         @local_keypairs[:s] = @protocol.dh_fn.class.from_private(keypairs[:s]) if keypairs[:s]
         @remote_keys = { rs: keypairs[:rs], re: keypairs[:re] }
-        @handshake_started = false
-        @handshake_finished = false
-        initialize_next_message
+        @state = :created
       end
 
+      # Whether the transport phase uses one CipherState for both directions, which is the
+      # half-duplex mode of section 11.5 of the Noise specification. Both parties keep the first
+      # CipherState that Split() returns and drop the second.
+      #
+      # It is only safe when the two parties strictly alternate their transport messages. They
+      # share one nonce, so if both encrypt before either decrypts, two different plaintexts go
+      # out under the same nonce, which breaks the confidentiality of both and lets an attacker
+      # forge further ones. Nothing here can check that the application alternates; that is the
+      # application protocol's guarantee to make.
+      #
+      # Because there is one CipherState, the accessors that name a direction all reach it:
+      # #encryption_nonce and #decryption_nonce report the same count, setting either sets both,
+      # and #rekey_encryption and #rekey_decryption replace the same key.
+      #
+      # @return [Boolean]
+      def half_duplex?
+        @half_duplex
+      end
+
+      # @return [Boolean] true once #start_handshake has been called.
+      def handshake_started?
+        @state != :created
+      end
+      alias handshake_started handshake_started?
+
+      # @return [Boolean] true once the last handshake message has been written or read, which is
+      #   when the transport operations become available.
+      def handshake_finished?
+        @state == :transport
+      end
+      alias handshake_finished handshake_finished?
+
+      # Starts the handshake this connection was created for. It is legal once: a connection that
+      # already has a handshake, running or finished, has keys and a transcript that restarting
+      # would silently throw away. #fallback is the supported way to begin a second handshake.
       def start_handshake
+        ensure_state!(:created)
         validate
         initialise_handshake_state
-        @handshake_started = true
+        @state = initial_turn
+        nil
       end
 
       # Restarts the handshake with a fallback pattern, carrying over the keys of the aborted one.
       #
       # The roles swap here: the party that wrote the aborted message now reads, and the one that
-      # failed to read it now writes. Both sides are already in that state, so @next_message is
-      # deliberately left as it is rather than reset through initialize_next_message.
+      # failed to read it now writes. Both sides are already on that turn, so the current turn is
+      # carried over rather than reset to the one this party started the aborted pattern on.
       def fallback(fallback_name)
-        @protocol = Protocol.create(fallback_name)
-        @handshake_started = false
-        @handshake_finished = false
+        ensure_state!(*HANDSHAKE_STATES)
+
+        turn = @state
+        protocol = Protocol.create(fallback_name)
+        validate_half_duplex!(protocol)
+        @protocol = protocol
         @local_keypairs = { e: @handshake_state.e, s: @handshake_state.s }
         @remote_keys = { re: @handshake_state.re, rs: @handshake_state.rs }
+        # Everything that can fail has run by now, so a bad fallback name leaves the connection on
+        # the handshake it was already running. start_handshake accepts a connection in :created
+        # alone, so the aborted handshake is cleared here and the turn restored after it.
+        @state = :created
         start_handshake
+        @state = turn
+        nil
       end
 
       def initialise_handshake_state
@@ -69,10 +174,7 @@ module Noise
       end
 
       def write_message(payload = '')
-        # Call NoiseConnection.start_handshake first
-        raise Noise::Exceptions::NoiseHandshakeError unless @handshake_started
-        raise Noise::Exceptions::NoiseHandshakeError if @next_message != :write
-        raise Noise::Exceptions::NoiseHandshakeError if @handshake_finished
+        ensure_state!(:handshake_write)
 
         length = @handshake_state.expected_message_length(payload.bytesize)
         if length > MAX_MESSAGE_LENGTH
@@ -80,26 +182,27 @@ module Noise
                 "Message would be #{length} bytes, which exceeds the maximum of #{MAX_MESSAGE_LENGTH}."
         end
 
-        @next_message = :read
+        # The turn passes before the message is built, so that a message this party failed to
+        # build still leaves the connection waiting for the other party, as fallback expects.
+        @state = :handshake_read
         buffer = +''
-        @handshake_finished = @handshake_state.write_message(payload, buffer)
+        @state = :transport if @handshake_state.write_message(payload, buffer)
         buffer
       end
 
       def read_message(data)
-        # Call NoiseConnection.start_handshake first
-        raise Noise::Exceptions::NoiseHandshakeError unless @handshake_started
-        raise Noise::Exceptions::NoiseHandshakeError if @next_message != :read
-        raise Noise::Exceptions::NoiseHandshakeError if @handshake_finished
+        ensure_state!(:handshake_read)
 
         if data.bytesize > MAX_MESSAGE_LENGTH
           raise Noise::Exceptions::MessageTooLongError,
                 "Message is #{data.bytesize} bytes, which exceeds the maximum of #{MAX_MESSAGE_LENGTH}."
         end
 
-        @next_message = :write
+        # See #write_message: the turn passes before the message is read, so that a message that
+        # fails to decrypt leaves this party ready to write the fallback handshake message.
+        @state = :handshake_write
         buffer = +''
-        @handshake_finished = @handshake_state.read_message(data, buffer)
+        @state = :transport if @handshake_state.read_message(data, buffer)
         buffer
       end
 
@@ -197,6 +300,7 @@ module Noise
 
       def handshake_done(_c1, _c2)
         @handshake_hash = @symmetric_state.handshake_hash
+        @chaining_key = @symmetric_state.ck
         @s = @handshake_state.s
         @rs = @handshake_state.rs
         @handshake_state = nil
@@ -206,6 +310,36 @@ module Noise
 
       private
 
+      # A one-way pattern gives the responder no way to reply, so its parties never alternate and
+      # half-duplex has nothing to share a CipherState between. Sharing one anyway would hand the
+      # responder an encryption key the pattern is meant to deny it.
+      #
+      # @param [Noise::Protocol] protocol the protocol to check, which is the one being fallen back
+      #   to when #fallback asks.
+      # @raise [Noise::Exceptions::NoiseValidationError]
+      def validate_half_duplex!(protocol = @protocol)
+        return unless @half_duplex && protocol.pattern.one_way?
+
+        raise Noise::Exceptions::NoiseValidationError,
+              "#{protocol.name} is a one-way pattern, which cannot run half-duplex."
+      end
+
+      # The CipherState for the direction this party did not assign c1 to, which is decryption for
+      # the initiator and encryption for the responder.
+      #
+      # Half-duplex answers c1 both ways, so that the two parties encrypt and decrypt under the
+      # same key and nonce as they take turns. A one-way pattern has no second direction at all,
+      # so it has none.
+      #
+      # @param [Noise::State::CipherState] c1 the first CipherState Split() returned.
+      # @param [Noise::State::CipherState] c2 the second one.
+      # @return [Noise::State::CipherState, nil]
+      def other_direction_cipher_state(c1, c2)
+        return c1 if half_duplex?
+
+        @protocol.pattern.one_way? ? nil : c2
+      end
+
       # Returns the transport CipherState of the given direction.
       #
       # One-way patterns leave the direction the caller cannot use as nil, so the absence of a
@@ -213,13 +347,43 @@ module Noise
       #
       # @param [Symbol] direction :encrypt or :decrypt.
       def transport_cipher_state(direction)
-        raise Noise::Exceptions::NoiseHandshakeError unless @handshake_finished
+        ensure_state!(:transport)
 
         cipher_state = direction == :encrypt ? @cipher_state_encrypt : @cipher_state_decrypt
         raise Noise::Exceptions::NoiseHandshakeError, "This party cannot #{direction} messages." unless cipher_state
 
         cipher_state
       end
+
+      # Raises unless the connection is in one of the states the calling operation is legal in.
+      # Every public operation goes through here, so a new one cannot forget its precondition.
+      #
+      # @param [Array<Symbol>] allowed the states the operation may be called in.
+      def ensure_state!(*allowed)
+        return if allowed.include?(@state)
+
+        raise state_error(allowed)
+      end
+
+      # Builds the exception for an operation called in the wrong state. All four descend from
+      # NoiseHandshakeError, so a caller that does not care which one it is can rescue the parent.
+      #
+      # @param [Array<Symbol>] allowed the states the operation may be called in.
+      # @return [Noise::Exceptions::NoiseHandshakeError]
+      def state_error(allowed)
+        case @state
+        when :created
+          Noise::Exceptions::HandshakeNotStartedError.new('The handshake has not started. Call #start_handshake.')
+        when :transport
+          Noise::Exceptions::HandshakeAlreadyFinishedError.new('The handshake has already finished.')
+        else
+          if allowed.include?(:transport)
+            Noise::Exceptions::HandshakeNotFinishedError.new('The handshake has not finished.')
+          else
+            Noise::Exceptions::HandshakeTurnError.new(TURN_MESSAGES.fetch(@state))
+          end
+        end
+      end
     end
   end
 end

data/lib/noise/connection/initiator.rb

@@ -3,8 +3,11 @@
 module Noise
   module Connection
     class Initiator < Base
-      def initialize_next_message
-        @next_message = :write
+      # The initiator writes the first handshake message of the pattern.
+      #
+      # @return [Symbol] the state start_handshake moves this party into.
+      def initial_turn
+        :handshake_write
       end
 
       def initiator?
@@ -14,7 +17,7 @@ module Noise
       def handshake_done(c1, c2)
         super
         @cipher_state_encrypt = c1
-        @cipher_state_decrypt = @protocol.pattern.one_way? ? nil : c2
+        @cipher_state_decrypt = other_direction_cipher_state(c1, c2)
       end
     end
   end

data/lib/noise/connection/responder.rb

@@ -3,8 +3,11 @@
 module Noise
   module Connection
     class Responder < Base
-      def initialize_next_message
-        @next_message = :read
+      # The responder reads the first handshake message of the pattern.
+      #
+      # @return [Symbol] the state start_handshake moves this party into.
+      def initial_turn
+        :handshake_read
       end
 
       def initiator?
@@ -14,7 +17,7 @@ module Noise
       def handshake_done(c1, c2)
         super
         @cipher_state_decrypt = c1
-        @cipher_state_encrypt = @protocol.pattern.one_way? ? nil : c2
+        @cipher_state_encrypt = other_direction_cipher_state(c1, c2)
       end
     end
   end

data/lib/noise/exceptions/handshake_already_finished_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    # Raised when a handshake operation is called after the handshake has already finished.
+    class HandshakeAlreadyFinishedError < NoiseHandshakeError
+    end
+  end
+end

data/lib/noise/exceptions/handshake_not_finished_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    # Raised when a transport operation is called while the handshake is still running.
+    class HandshakeNotFinishedError < NoiseHandshakeError
+    end
+  end
+end

data/lib/noise/exceptions/handshake_not_started_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    # Raised when an operation needs a handshake that Connection#start_handshake has not begun yet.
+    class HandshakeNotStartedError < NoiseHandshakeError
+    end
+  end
+end

data/lib/noise/exceptions/handshake_turn_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    # Raised when a handshake message is written where one has to be read, or read where one has to
+    # be written. A Noise handshake alternates between the two parties, so only one of the two is
+    # legal at any point.
+    class HandshakeTurnError < NoiseHandshakeError
+    end
+  end
+end

data/lib/noise/exceptions/read_timeout_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    # Raised when a transport layer gave up waiting for the rest of a message to arrive.
+    class ReadTimeoutError < RuntimeError
+    end
+  end
+end

data/lib/noise/exceptions/truncated_message_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    # Raised when a stream ends part way through a message that a transport layer was reading.
+    class TruncatedMessageError < RuntimeError
+    end
+  end
+end