kpsh-daemon-protocol(7) Miscellaneous Information Manual kpsh-daemon-protocol(7)

KeePass Shell's Daemon Protocol - binary protocol used for inter process communication with kpsh

MSG := <BODY_LEN><BODY>

BODY_LEN := 4-byte integer
BODY := byte stream of encoded string

BODY := <KPSH_COMMAND>

KPSH_COMMAND := command and its arguments available in kpsh

BODY := <TYPE><SPACE><TEXT>

TYPE := string "M" or "E" or "P" or "PS"
SPACE := 0x20 ASCII character
TEXT := any string

kpsh implements IPC based on Unix Domain Sockets stream connection (AF_UNIX, SOCK_STREAM) between kpsh acting as a server and any client which understands its underlying binary protocol. kpsh handles only one connection at a time and clients decide when they disconnect. When one client is handled, other connections are accepted and then immediately closed, without reading any input.

kpsh starts listening for connections when it's started with --daemon switch. By default it creates a socket at $XDG_RUNTIME_DIR/kpsh.sock. If XDG_RUNTIME_DIR_ environment variable is not set, kpsh will fall back to legacy path /tmp/kpsh-$UID.sock. Alternatively, socket path can be configured with --socket-path option.

kpsh and clients exchange the following binary messages:

<BODY_LEN><BODY>

BODY_LEN is a 4-byte int, which tells the length of transmitted BODY. BODY is a byte stream of encoded string.

Please note that BODY_LEN contains length of binary form of string, i.e. a number of transmitted bytes, not a number of letters. These might be the same numbers for some encodings (e.g. ASCII), but Unicode strings typically contain also multi-byte glyphs.

BODY is any command typically available in interactive sessions of kpsh (see: kpsh(1)). kpsh will respond with a series of messages in the following form, followed by "OK" message:

BODY := <TYPE><SPACE><TEXT>
BODY := OK

SPACE is 0x20 ASCII character.

TYPE encodes the meaning of TEXT. Typically clients are encouraged to display TEXT to end user in a suitable way.

TYPE might be one of the following strings:

M: ordinary message (e.g. stdout).

E: error message (e.g. stderr).

P: prompt; client should prompt user for additional input. As soon as client receives a prompt message, it should send back a response, without waiting for OK message.

PS: prompt secure; same as prompt, but client is advised to obtain user input securely. Usually it's a request for a password which shouldn't be displayed when user types it.

After each command kpsh sends "OK" message to indicate to the clients that command won't output anything else.

Typical session (for simplicity we'll skip the header, i.e. first 4 bytes with message length):

(client connects)
C: unlock
S: PS Password:
C: super difficult password chosen by user
S: OK
C: show example-account -n
S: M example-account
S: M some username
S: M some password
S: M https://example.com/login
S: M note note note
S: OK
C: show blablabla
S: E entry not found: blablabla
C: exit
S: OK
(server closes connection)

Note that after the last exit command, kpsh server terminates. To avoid this, clients should simply disconnect.

Example client implementation is available in contrib/kpsh-client script.

kpsh(1), socket(2)

Michał Góral <dev@goral.net.pl>

Source code: https://git.goral.net.pl/keepass-shell.git

2024-12-21