Skip to main content

boho design and technical details

boho is a shared-key library for authentication and encryption between devices and applications you administer. Its name comes from the Korean word for protection. Arduino C/C++ and Node.js/browser JavaScript implementations use compatible message formats.

When you control both endpoint programs and can provision keys in advance, you can build communication on a pre-shared symmetric key without a public-key trust system. boho combines SHA-256-based keystreams, XOR, shared-key authentication, and binary packet formats.

Choosing a symmetric-key deployment model and evaluating the security of boho's construction are separate decisions. Using standard SHA-256 does not give the complete custom protocol the guarantees of standard authenticated encryption (AEAD) or TLS.

For IOSignal connection authentication see authentication and encryption; for methods see the client API.

Why this library exists​

Encrypted communication on small devices needs more than an algorithm: peer authentication, key provisioning, message formats, memory use, transport integration, and key management.

boho focuses on verifying already-provisioned peers and protecting data the same way on Arduino, Node.js, and browsers. Encryption is independent of transport and can be used with TCP, WebSocket, serial links, or MQTT payloads; IOSignal supplies connection management and message routing around it.

Provision keys through a path you already trust​

EnvironmentExample provisioning method
Embedded devices you buildUSB/serial or a trusted setup tool, with a key per device
Your web app and personal devicesA device key the user received separately, or a trusted pairing procedure
Servers under common administrationSSH, an existing TLS connection, or a secret manager
A defined device/user groupPer-peer keys with rotation and revocation procedures

Trust does not disappear; it moves to the provisioning path and the endpoint software. Sharing one key among many devices makes senders indistinguishable and increases the impact of a leak. A common key in a public JavaScript bundle is readable by every visitor; writing the code yourself does not make an embedded key secret.

Protection scope and limits​

Connection keys protect client–server traffic; a separate E2E data key protects payloads between final endpoints. The present construction does not automatically have TLS or standard AEAD guarantees and does not provide forward secrecy. Review nonce reuse, replay handling, and key management for your application.

The sections below describe boho JS 2.2.0 and boho Arduino 1.0.0; boho is versioned independently of IOSignal.

XOR, hashes, and one-time pads​

For plaintext P and keystream S, ciphertext is C = P XOR S; XOR with the same S restores P. A true one-time pad (OTP) uses an unpredictable secret stream as long as the message, only once. Reusing it exposes C1 XOR C2 = P1 XOR P2.

SHA-256 outputs 32 bytes; it is a hash, not encryption. Hashing a public nonce alone does not create a secret stream, and hashing a weak password does not add entropy. boho's "virtual OTP" is a deterministic pseudorandom construction, not an information-theoretically secure OTP. ChaCha20 also expands secret material into a keystream, but its construction and level of analysis differ.

Keystream generation​

K = SHA256(input key)
B = SHA256(K || salt12)
S_i = SHA256(B || LE32(i)), i = 1, 2, ...

|| is byte concatenation. salt12 consists of seconds (4 bytes), milliseconds (2), a counter (2), and a nonce (4), and is not secret. The block index is appended little-endian. A 70-byte plaintext uses 32 + 32 + 6 keystream bytes. In the source, resetOTP, getIndexOTP (JS) / generateIndexOTP (Arduino), and xotp handle block generation and XOR. Arduino generates one 32-byte block at a time, but packet and application buffers still use memory.

Repeating the same key and salt repeats the keystream. Uniqueness must hold across devices, directions, reboots, and counter reuse, not only within one message loop.

Integrity and authentication​

The packet integrity value is the first eight bytes of:

SHA256(K || salt12 || plaintext)

The receiver decrypts, checks this value, and uses only messages that pass. Source names such as generateHMAC and hmac are historical: this is not standard HMAC (inner/outer pad construction), so HMAC guarantees do not carry over.

Connection authentication runs in this order:

Authentication uses 32-byte values rather than the packet's 8-byte value. The key itself is never sent; both sides prove knowledge of the configured key. This is neither a public-CA identity check nor a fresh public-key key exchange.

Packet formats​

OperationAPIOverhead beyond plaintext
Standalone data encryptionencryptPack / decryptPack25 bytes
Messages on an authenticated connectionencrypt_488 / decrypt_48821 bytes (the authentication nonce is known, so only 8 bytes of time/counter are sent)
Separate data key (E2E)encrypt_e2e / decrypt_e2eInternal ENC_PACK 25 bytes plus outer routing data

These sizes describe packet fields, not total Ethernet/TCP/WebSocket overhead or a performance benchmark.

TLS and end-to-end encryption​

TLS handles transport peer authentication, key agreement, and symmetric encryption. Certificate-based TLS is common, but TLS 1.3 also has PSK modes, including ones with ephemeral key exchange. CPU, memory, and bandwidth costs depend on hardware and configuration.

AspectCertificate-based TLSboho
Initial trustCertificates, trust roots, name validationShared key provisioned through a separate path
Protection unitTransport connectionApplication packets and connection authentication
Unknown web visitorsServer authentication without a prior secretRequires a key-provisioning step first
BasisStandard protocol and constructionsCustom protocol built from SHA-256

IOSignal AUTO mode applies boho encryption to connections without TLS once boho authentication succeeds. Anonymous connections are not encrypted by it, so check the actual connection's encryption mode.

Connection keys and E2E data keys serve different purposes. A connection key proves each client's right to connect to the server; an E2E key, which the server never has, protects payloads between final endpoints.

With E2E, routing information such as tags remains visible to the server. In browsers, the code that handles the key must itself arrive safely over HTTPS, so boho does not replace HTTPS.

Conditions to check before use​

  • Use sufficiently random keys. set_key applies a single SHA-256, not a slow password KDF.
  • JS uses crypto.getRandomValues(), but Arduino nonces come from micros(), which is not a cryptographic random source. Assess nonce/salt reuse across reboots and devices.
  • boho itself does not enforce challenge expiry or keep a complete replay cache. Clock, lifetime, and duplicate rules belong to IOSignal, the server, or the application.
  • There is no forward secrecy, and standard AEAD guarantees cannot be claimed.
  • A leaked key exposes traffic protected with it. Separate connection and E2E keys and define replacement procedures.

Implementation and references​

For implementation review, use the boho JS and boho Arduino sources at the versions above. IOSignal's connection authentication and E2E delivery live in iosignal (src/auth/BohoAuth.js, src/client/IOCore.js, src/server/RemoteCore.js) and iosignal-arduino (src/IOSignal.cpp).

Related standards: SHA-256, FIPS 180-4, ChaCha20/Poly1305, RFC 8439, HMAC, RFC 2104, TLS 1.3, RFC 8446. These describe the standards; they do not certify boho as an implementation of them.