Developer Integration Guide

This chapter documents the interfaces a third-party developer can use to integrate with a Seclave 2.0 device: to type credentials, to bulk-load credentials, or to read and write credentials interactively. It is aimed at authors of autofill helpers, command-line tools, importers, and password-manager plugins.

Everything described here is observable at the USB boundary with a device and a protocol analyzer. No host software from Seclave is required to build an integration; the wire formats below are complete and stable.

The three USB personalities

The device shares one USB Vendor ID, 0x20A0, and presents one of three personalities at a time. The user selects the active personality from the on-device menu; a host cannot switch it remotely.

Personality

Product ID

USB class

Purpose

USB keyboard

0x41E1

HID

Types passwords as keystrokes (default use)

USB mass storage

0x41E2

Bulk-only mass storage

Bulk import, backup export, restore

USB slave

0x41E3

CDC-ACM (virtual serial)

Interactive read/write protocol

The USB string descriptors are Manufacturer "SECLAVE" and Product "SECLAVE2" on every personality; host tooling can key off these strings (see the Linux udev note in USB-Slave Serial Protocol).

Which interface should I use?

Keyboard emulation - no integration required

In its default mode the device is a USB HID keyboard (Product ID 0x41E1). When the user selects an entry on the device, it types the username and/or password as keystrokes into whatever field currently has focus on the host. There is no protocol, no driver, and no read-back: the host cannot query the device and the device cannot be driven by the host.

Use this when you need nothing more than “the password appears in the focused field” - a login form, an SSH prompt, a disk-encryption unlock screen. Most users never need anything else.

Mass-storage import - one-way bulk load

The mass-storage import path (Product ID 0x41E2) lets a host write many entries to the device in a single operation. The device mounts a small FAT volume; the host writes an import file; the user starts the import on the device and chooses a merge policy. It is write-only: there is no read-back and no per-item confirmation.

Use this to migrate a whole vault or seed a device from an existing password manager. See Mass-Storage Import and Backup.

USB-slave serial - interactive read/write

The USB-slave interface (Product ID 0x41E3, a CDC-ACM virtual serial port) is a request/response protocol for reading and writing individual credentials, enumerating the store, looking up web passwords by domain, and streaming an encrypted backup. It is bidirectional and interactive, and most operations require the user to confirm on the device.

Use this for autofill helpers, CLIs, and any client that needs to read credentials or add them one at a time. See USB-Slave Serial Protocol.

Summary

Need

Keyboard

Import

USB slave

Notes

Type a password into a field

Yes

–

–

No integration needed

Bulk-load many entries

–

Yes

one-at-a-time

Import is the right tool for a whole vault

Read credentials back

–

–

Yes

Only USB slave can read

Look up by web domain

–

–

Yes

See Web Passwords (wwwfill)

Export an encrypted backup

–

via mass storage (SECLAVE.BKP)

via serial (GET_BACKUP)

Both produce the same opaque archive

Data model shared by all interfaces

Every stored credential, whatever interface created it, is a record with the same five client-visible fields and the same maximum field lengths. These limits apply everywhere - enforce them in your client to avoid silent truncation.

Field

Max bytes

Notes

Label

16

Primary key; unique across the store; required (at least 1 byte).

Group

8

Folder/category; may be empty.

Username

50

Free-form.

Password

50

Free-form.

Optional

83

Free-form. Holds the domain for web-password entries.

Additional shared rules:

  • Encoding is Latin-1 (ISO-8859-1), single-byte. Username, password, and optional accept arbitrary bytes. Label, group, and domain are restricted to a fixed character set (see below).

  • The store holds at most 500 entries total, counting regular and web-password entries together.

  • Labels are unique and compared case-insensitively: myLabel and mylabel collide.

  • Label / group / domain character set: ASCII letters a-z / A-Z (compared case-insensitively), digits 0-9, the punctuation _, -, ., and a fixed set of Latin-1 accented letters (æ Æ å Å ä Ä ö Ö ø Ø ü Ü ß). Any other byte - space, /, @, :, UTF-8 multibyte, control characters - is rejected. When targeting web domains, strip scheme, port, and path and pass a bare host such as example.co.uk (dots are allowed; : and / are not).

Note

Strings are not NUL-terminated when they use the full field width. On the serial protocol every string is length-prefixed; in the import file every field is a fixed-width, zero-padded slot. A client never relies on NUL termination.

Interface references