>NoiseFramework
API Documentation

API Reference

Complete reference for all public APIs in NoiseFramework

Quick Navigation
NoiseHandshake ClassNoiseTransport ClassPattern SystemCryptographic Primitives

NoiseHandshake

Main class for orchestrating Noise Protocol handshakes.

NoiseHandshake(pattern_string)
Initialize a Noise handshake with a pattern string

Parameters:

pattern_string (str): Noise pattern in format Noise_PATTERN_DH_CIPHER_HASH

Example: "Noise_XX_25519_ChaChaPoly_SHA256"

Example:

from noiseframework import NoiseHandshake

handshake = NoiseHandshake("Noise_XX_25519_ChaChaPoly_SHA256")

Methods

set_as_initiator()
Configure this handshake instance as the initiator (client)
handshake.set_as_initiator()

NoiseTransport

Transport layer for encrypted communication after handshake completion.

Import
from noiseframework import NoiseTransport
send(plaintext, ad)
Encrypt and send a message

Parameters:

plaintext (bytes): Data to encrypt

ad (bytes): Associated data (optional)

ciphertext = transport.send(b"Hello!")
receive(ciphertext, ad)
Receive and decrypt a message

Parameters:

ciphertext (bytes): Encrypted data

ad (bytes): Associated data (optional)

plaintext = transport.receive(ciphertext)

Pattern System

Supported Patterns
NoiseFramework supports all 12 fundamental interactive patterns

One-way patterns

  • NN
  • NK
  • NX

Initiator auth

  • KN
  • KK
  • KX

Interactive (most common)

  • XX (recommended)
  • XK
  • XN
Pattern Selection Guide
XX

Mutual authentication, no pre-shared keys

Best for most use cases

IK

Client knows server's public key

Faster handshake, requires pre-shared keys

NN

Anonymous communication

No authentication - not recommended for production

Cryptographic Primitives

DH Functions

  • 25519

    Curve25519 (X25519) - 32 bytes

  • 448

    Curve448 (X448) - 56 bytes

Cipher Functions

  • ChaChaPoly

    ChaCha20-Poly1305 (recommended)

  • AESGCM

    AES-256-GCM

Hash Functions

  • SHA256

    SHA-256 - 32 bytes

  • SHA512

    SHA-512 - 64 bytes

  • BLAKE2s

    BLAKE2s - 32 bytes

  • BLAKE2b

    BLAKE2b - 64 bytes

Complete Example

XX Pattern (Mutual Authentication)
Full handshake and transport setup
from noiseframework import NoiseHandshake, NoiseTransport

# Setup
initiator = NoiseHandshake("Noise_XX_25519_ChaChaPoly_SHA256")
initiator.set_as_initiator()
initiator.generate_static_keypair()
initiator.initialize()

responder = NoiseHandshake("Noise_XX_25519_ChaChaPoly_SHA256")
responder.set_as_responder()
responder.generate_static_keypair()
responder.initialize()

# Handshake
msg1 = initiator.write_message(b"")
responder.read_message(msg1)

msg2 = responder.write_message(b"")
initiator.read_message(msg2)

msg3 = initiator.write_message(b"")
responder.read_message(msg3)

# Transport
i_send, i_recv = initiator.to_transport()
r_send, r_recv = responder.to_transport()

i_transport = NoiseTransport(i_send, i_recv)
r_transport = NoiseTransport(r_send, r_recv)

# Encrypt/Decrypt
ciphertext = i_transport.send(b"Hello!")
plaintext = r_transport.receive(ciphertext)
print(plaintext.decode()) # "Hello!"

Error Handling

ValueError Exceptions
All functions raise ValueError for invalid inputs or cryptographic failures
try:
  handshake = NoiseHandshake("Invalid_Pattern")
except ValueError as e:
  print(f"Error: {e}")