home | help 
himitsu-ipc(5)		       File Formats Manual		  himitsu-ipc(5)

NAME
     himitsu-ipc - IPC protocol implemented by himitsud(1)

DESCRIPTION
     The  Himitsu  IPC protocol is a line-oriented text protocol using the UTF-8
     encoding and LF line endings. It is transmitted over a Unix socket which is
     located at $XDG_RUNTIME_DIR/himitsu.

     Interactions with this interface are command/reply oriented, with	commands
     initiated	by  the client and replies sent by the server. Both commands and
     replies have the same semantic structure. Each begins with a  command  word
     (an  alphanumeric	string) which defines the operation requested. There may
     or may not be additional arguments provided. If there are no additional ar-
     guments the command word is immediately followed by LF. Otherwise,  follow-
     ing  the  command	word  is a space, then a sequence of arbitrary printable
     UTF-8 characters until the line terminator is reached. The structure of the
     argument string depends on the command word.

     This man page assumes knowledge of the KEY  FORMAT  and  QUERY  SYNTAX  de-
     scribed  in  himitsu(7). Note also that commands which accept flags process
     them in a manner compatible with getopt(3).

     All commands are subject to a significant delay before the reply while  the
     user is prompted to provide consent or to unlock the keyring.

COMMANDS
     The following commands are recognized by the server:

     add key...
	 Adds a new key to the key store. The server will send a key reply echo-
	 ing the new key (without secrets), followed by an end reply.

     del [-s] query...
	 Removes  keys	from  the  key store which match the provided query. The
	 user will be prompted to consent to this  operation.  The  server  will
	 send a key reply for each deleted key (without secrets), followed by an
	 end reply. The option -s will enable the strict query mode.

     persist [-rs] query
	 Persists  a  query  after  user consent for current connection. Private
	 values that match the given query will be decrypted without  user  con-
	 sent,	if  the store is unlocked. The server will answer with a persist
	 reply.

	 *   -r <remember options>: as a comma separated list that are	send  to
	     the prompter. Allowed values are the strings session, skip, refuse,
	     or   a   timeout	in   section   as  an  integer.  Eg.:  "-r  ses-
	     sion,3600,300,refuse". The first value is	the  default  value  and
	     should  be preselected by the prompter. See the remember command in
	     himitsu-prompter(5) for a description of the options.
	 *   -s: will enable the strict query mode.

     query [-drs] query...
	 Queries the key store for keys matching the  provided	query.	Matching
	 keys  are  returned via a series of key replies, terminated with an end
	 reply to signal the end of the list.

	 *   -d: the private values will be decrypted after requesting user con-
	     sent.
	 *   -r <remember options>: as a comma separated  list	similar  to  the
	     same option of the persist command. If the user agrees, the entries
	     matched  by  given query will be remembered for the current connec-
	     tion.
	 *   -s: will enable the strict query mode.

     update [-s] query...
	 Begins an transaction that will update all keys matching  the	provided
	 query. The server will answer wit the update reply. Requires a set com-
	 mand  next,  to  complete the update. There must be no other command in
	 between update and set.

	 *   -s: will enable the strict query mode.

     set query...
	 Set must directly follow the update command. It changes  the  key/value
	 pairs	of  the keys that are matched by the update command according to
	 the values provided by the query. If a key/value pair doesn't exist, it
	 will be added. Otherwise the existing key will be updated with the  new
	 value.  If  there is a key without a value, then the matching key/value
	 pair will be removed.

	 Updated keys are returned via a series of key replies, terminated  with
	 and end reply to signal the end of the list.

     status
	 Requests the secret store lock status. Responds with the status reply.

     lock [-s]
	 Locks	the keyring clearing all entries and removes the secret key from
	 memory. The server will answer with the locked reply.

	 *   -s: Soft lock: Only the secret key will be cleared. Entries without
	     their secret values can still be accessed.

     quit
	 Requests that the daemon terminate itself. This command is only  recog-
	 nized if himitsud(1) was started with the -D flag. No reply is sent.

REPLIES
     The following replies are sent to the client:

     key key...
	 Provides a single key store entry to the user.

     end
	 Signals the end of a list of key replies.

     persist session|timeout <value>|skip|refuse
	 Returns the selected remember option on persist.

     locked
	 Indicates that the lock command was successful.

     status unlocked|soft_locked|hard_locked
	 Current key store status as reply to the status command.

     update
	 Update command has been received without errors.

     error message...
	 Indicates  that a requested operation resulted in an error. The message
	 is both human-friendly and consistent, such that it can be displayed to
	 the user or matched against an  internal  database  of  semantic  error
	 strings in the client.

EXAMPLE SESSION
     An  example  session,  with  <=  indicating messages from the server to the
     client, and => vice-versa. Any of the commands may be separated from  their
     replies by several seconds while the user interacts with the prompter.

	 => query proto=web
	 <= key proto=web host=a.example.org user=jdoe password!
	 <= key proto=web host=b.example.org user=jdoe password!
	 <= key proto=web host=c.example.org user=jdoe password!
	 <= key proto=web host=d.example.org user=jdoe password!
	 <= end
	 => add proto=web host=e.example.org user=jdoe password!=hunter2
	 <= key proto=web host=e.example.org user=jdoe password!
	 <= end
	 => query -d proto=web host=e.example.org
	 => key proto=web host=e.example.org user=jdoe password!=hunter2
	 <= end

SEE ALSO
     himitsu(7)

AUTHORS
     Maintained  by  Drew DeVault <sir@cmpwn.com>, who is assisted by other con-
     tributors. Up-to-date source code can be found at https://git.sr.ht/~sircm-
     pwn/himitsu, and bugs/patches can be submitted by email  to  ~sircmpwn/him-
     itsu-devel@lists.sr.ht.

				   2026-08-27			  himitsu-ipc(5)
home | help