diff --git a/XX.md b/XX.md new file mode 100644 index 0000000000..fc2108e744 --- /dev/null +++ b/XX.md @@ -0,0 +1,116 @@ +NIP-XX +====== + +Nostr BLE Signing Device Protocol +--------------------------------- + +`draft` `optional` + +This NIP specifies how Nostr signing devices can provide key management and message signing capabilities over BLE. The protocol enables secure communication between a client application and a hardware signing device using standardized BLE UART services. + +## Protocol Details + +### Device Advertisement +The signing device advertises itself with: +- Service UUID: `6E400001-B5A3-F393-E0A9-E50E24DCCA9E` (Nordic UART Service) +- Device Name Format: `NSD-XXXXXX` where XXXXXX is derived from the device's BLE MAC address +- Advertisement Interval: 20ms - 150ms +- Flags: General Discoverable Mode & BR/EDR Not Supported + +### GATT Services +The device exposes a Nordic UART Service with the following characteristics: + +1. RX Characteristic (Write) + - UUID: `6E400002-B5A3-F393-E0A9-E50E24DCCA9E` + - Properties: Write, Write Without Response + - Used by client to send commands to the device + +2. TX Characteristic (Read/Notify) + - UUID: `6E400003-B5A3-F393-E0A9-E50E24DCCA9E` + - Properties: Notify + - Used by device to send command responses + +### Command Format +Commands are sent as UTF-8 encoded strings in the format: +- `/command [parameters]` + +Responses are returned in the format: +- `/command response_data` + +### Supported Commands + +#### Key Management +- `/public-key`: Returns the active public key in hex format +- `/add-key `: Adds a new private key to the device +- `/remove-key `: Removes the private key at specified index +- `/list-keys`: Lists all stored public keys with their indices +- `/switch-key `: Changes the active key to the specified index +- `/new-key`: Generates a new random private key +- `/name-key `: Assigns a human-readable name to a key + +#### Message Signing +- `/sign-message `: Signs message text with the active key +- `/shared-secret `: Performs ECDH with provided public key +- `/encrypt-message-nip04 `: Encrypts a message for recipient (legacy support for NIP-04) +- `/decrypt-message-nip04 `: Decrypts a message from sender (legacy support for NIP-04) +- `/encrypt-message-nip44 `: Encrypts a message for recipient (NIP-44) +- `/decrypt-message-nip44 `: Decrypts a message from sender (NIP-44) + +#### Device Management +- `/help`: Lists available commands +- `/ping`: Tests device connectivity +- `/reboot`: Restarts the device +- `/wipe`: Erases all stored keys and settings + +### Command Queue +The device implements a circular buffer queue (size 10) for BLE commands to handle rapid command transmission. Commands are processed in FIFO order. + +### Message Batching +Due to BLE's inherent packet size limitations (typically 20-23 bytes per packet in BLE 4.2, and up to 255 bytes in BLE 5), a batching mechanism is required to handle larger messages. While BLE does provide its own segmentation and reassembly for large packets, implementing an application-layer batching protocol ensures reliable message delivery across different BLE versions and implementations. + +The device implements a batching mechanism with the following characteristics: + +1. Message Size Limits + - Maximum BLE packet size: 100 bytes (conservative limit accounting for BLE overhead) + - Maximum total message size: 65536 bytes (64KB) + - Batch delimiter: "|||" (chosen for uniqueness and minimal overhead) + +2. Sending Messages + - Messages exceeding the maximum BLE packet size are automatically split into batches + - Each batch is limited to (MAX_BLE_PACKET_SIZE - delimiter_length) bytes + - All batches except the last one are appended with the "|||" delimiter + - A 150ms delay is enforced between batch transmissions to ensure reliable delivery and prevent BLE buffer overflow + +3. Receiving Messages + - The device buffers incoming batches until a complete message is received + - Batches are identified by the "|||" delimiter + - Messages are processed only after all batches are received + - Incomplete messages are discarded after a timeout period + - Messages exceeding the maximum size limit (64KB) are rejected + +4. Reliability Considerations + - The 150ms inter-batch delay accounts for BLE connection interval limitations + - Buffer size limits prevent memory exhaustion on resource-constrained devices + - The batching protocol is transparent to the application layer + - Error detection is handled through message completeness validation + +## Client Implementation Notes + +1. Device Discovery + - Scan for devices advertising Nordic UART Service UUID + - Filter for device names starting with "NSD-" + +2. Connection + - Connect to device + - Discover UART service and characteristics + - Enable notifications on TX characteristic + +3. Command Transmission + - Write commands to RX characteristic + - Listen for responses on TX characteristic + - Implement reasonable timeout handling + +## Reference Implementation + +The reference implementation is available at: +https://github.com/lnbits/nostr-signing-device