Secret key (32 bytes).

Compressed public key.

Derive a keypair from 32 bytes of entropy.

Returns Nothing if the entropy is invalid (zero or >= curve order).

>>> let ent = BS.replicate 32 0x11
>>> case keypair ent of { Just _ -> "ok"; Nothing -> "fail" }
"ok"
>>> keypair (BS.replicate 31 0x11) -- wrong length
Nothing

Parse a 33-byte compressed public key.

>>> let Just (_, pub) = keypair (BS.replicate 32 0x11)
>>> let bytes = serialize_pub pub
>>> case parse_pub bytes of { Just _ -> "ok"; Nothing -> "fail" }
"ok"
>>> parse_pub (BS.replicate 32 0x00) -- wrong length
Nothing

Serialize a public key to 33-byte compressed form.

>>> let Just (_, pub) = keypair (BS.replicate 32 0x11)
>>> BS.length (serialize_pub pub)
33

Initiator: generate Act 1 message (50 bytes).

Takes local static key, remote static pubkey, and 32 bytes of entropy for ephemeral key generation.

Returns the 50-byte Act 1 message and handshake state for Act 3.

>>> let Just (i_sec, i_pub) = keypair (BS.replicate 32 0x11)
>>> let Just (r_sec, r_pub) = keypair (BS.replicate 32 0x21)
>>> let eph_ent = BS.replicate 32 0x12
>>> case act1 i_sec i_pub r_pub eph_ent of { Right (msg, _) -> BS.length msg; Left _ -> 0 }
50

Initiator: process Act 2 and generate Act 3 (66 bytes), completing the handshake.

Returns the 66-byte Act 3 message and the handshake result.

>>> let Just (i_sec, i_pub) = keypair (BS.replicate 32 0x11)
>>> let Just (r_sec, r_pub) = keypair (BS.replicate 32 0x21)
>>> let Right (msg1, i_hs) = act1 i_sec i_pub r_pub (BS.replicate 32 0x12)
>>> let Right (msg2, _) = act2 r_sec r_pub (BS.replicate 32 0x22) msg1
>>> case act3 i_hs msg2 of { Right (msg, _) -> BS.length msg; Left _ -> 0 }
66

Responder: process Act 1 and generate Act 2 message (50 bytes).

Takes local static key and 32 bytes of entropy for ephemeral key, plus the 50-byte Act 1 message from initiator.

Returns the 50-byte Act 2 message and handshake state for finalize.

>>> let Just (i_sec, i_pub) = keypair (BS.replicate 32 0x11)
>>> let Just (r_sec, r_pub) = keypair (BS.replicate 32 0x21)
>>> let Right (msg1, _) = act1 i_sec i_pub r_pub (BS.replicate 32 0x12)
>>> case act2 r_sec r_pub (BS.replicate 32 0x22) msg1 of { Right (msg, _) -> BS.length msg; Left _ -> 0 }
50

Responder: process Act 3 (66 bytes) and complete the handshake.

Returns the handshake result with authenticated remote static pubkey.

>>> let Just (i_sec, i_pub) = keypair (BS.replicate 32 0x11)
>>> let Just (r_sec, r_pub) = keypair (BS.replicate 32 0x21)
>>> let Right (msg1, i_hs) = act1 i_sec i_pub r_pub (BS.replicate 32 0x12)
>>> let Right (msg2, r_hs) = act2 r_sec r_pub (BS.replicate 32 0x22) msg1
>>> let Right (msg3, _) = act3 i_hs msg2
>>> case finalize r_hs msg3 of { Right _ -> "ok"; Left e -> show e }
"ok"

Post-handshake session state.

Internal handshake state (exported for benchmarking).

Result of a successful handshake.

Encrypt a message (max 65535 bytes).

Returns the encrypted packet and updated session. Key rotation is handled automatically at nonce 1000.

Wire format: encrypted_length (2) || MAC (16) || encrypted_body || MAC (16)

>>> let Just (i_sec, i_pub) = keypair (BS.replicate 32 0x11)
>>> let Just (r_sec, r_pub) = keypair (BS.replicate 32 0x21)
>>> let Right (msg1, i_hs) = act1 i_sec i_pub r_pub (BS.replicate 32 0x12)
>>> let Right (msg2, _) = act2 r_sec r_pub (BS.replicate 32 0x22) msg1
>>> let Right (_, i_result) = act3 i_hs msg2
>>> let sess = session i_result
>>> case encrypt sess "hello" of { Right (ct, _) -> BS.length ct; Left _ -> 0 }
39

Decrypt a message, requiring an exact packet with no trailing bytes.

Returns the plaintext and updated session. Key rotation is handled automatically at nonce 1000.

This is a strict variant that rejects any trailing data. For streaming use cases where you need to handle multiple frames in a buffer, use decrypt_frame instead.

>>> let Just (i_sec, i_pub) = keypair (BS.replicate 32 0x11)
>>> let Just (r_sec, r_pub) = keypair (BS.replicate 32 0x21)
>>> let Right (msg1, i_hs) = act1 i_sec i_pub r_pub (BS.replicate 32 0x12)
>>> let Right (msg2, r_hs) = act2 r_sec r_pub (BS.replicate 32 0x22) msg1
>>> let Right (msg3, i_result) = act3 i_hs msg2
>>> let Right r_result = finalize r_hs msg3
>>> let Right (ct, _) = encrypt (session i_result) "hello"
>>> case decrypt (session r_result) ct of { Right (pt, _) -> pt; Left _ -> "fail" }
"hello"

Decrypt a single frame from a buffer, returning the remainder.

Returns the plaintext, any unconsumed bytes, and the updated session. Key rotation is handled automatically every 1000 messages.

This is useful for streaming scenarios where multiple messages may be buffered together. The remainder can be passed to the next call to decrypt_frame.

Wire format consumed: encrypted_length (18) || encrypted_body (len + 16)

>>> let Just (i_sec, i_pub) = keypair (BS.replicate 32 0x11)
>>> let Just (r_sec, r_pub) = keypair (BS.replicate 32 0x21)
>>> let Right (msg1, i_hs) = act1 i_sec i_pub r_pub (BS.replicate 32 0x12)
>>> let Right (msg2, r_hs) = act2 r_sec r_pub (BS.replicate 32 0x22) msg1
>>> let Right (msg3, i_result) = act3 i_hs msg2
>>> let Right r_result = finalize r_hs msg3
>>> let Right (ct, _) = encrypt (session i_result) "hello"
>>> case decrypt_frame (session r_result) ct of { Right (pt, rem, _) -> (pt, BS.null rem); Left _ -> ("fail", False) }
("hello",True)

Decrypt a frame from a partial buffer, indicating when more data needed.

Unlike decrypt_frame, this function handles incomplete buffers gracefully by returning NeedMore with the number of additional bytes required to make progress.

• If the buffer has fewer than 18 bytes (encrypted length + MAC), returns NeedMore n where n is the bytes still needed.
• If the length header is complete but the body is incomplete, returns NeedMore n with bytes needed for the full frame.
• MAC or decryption failures return FrameError.
• A complete, valid frame returns FrameOk with plaintext, remainder, and updated session.

This is useful for non-blocking I/O where data arrives incrementally.

Result of attempting to decrypt a frame from a partial buffer.

Handshake errors.