KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Document the encryption used by remote_control_password

Browse Source
This commit is contained in:
Kovid Goyal 2022-08-11 06:35:25 +05:30
parent ac9c85e783
commit 84ca83ef69
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
2 changed files with 26 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/glossary.rst
View File

@ -143,7 +143,7 @@ Variables that kitty sets when running child programs
.. envvar:: KITTY_PUBLIC_KEY
A public key that programs can use to communicate securely with kitty using
the remote control protocol.
the remote control protocol. The format is: :code:`protocol:key data`.
.. envvar:: KITTY_PREWARM_SOCKET

25
docs/rc_protocol.rst
View File

@ -38,4 +38,29 @@ with the following command line::
echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .
Encrypted communication
--------------------------
When using the :opt:`remote_control_password` option communication to the terminal is
encrypted to keep the password secure. A public key is used from the
:envvar:`KITTY_PUBLIC_KEY` environment variable. Currently, only one encryption
protocol is supported. The protocol number is present in
:envvar:`KITTY_PUBLIC_KEY` as ``1``. The key data in this environment variable is Base-85 encoded.
The algorithm used is Elliptic Curve Diffie Helman with the X25519 curve. A
time based nonce is used to avoid replay attacks. The original JSON command has
the fields: ``password`` and ``timestamp`` added. The timestamp is the number
of nanoseconds since the epoch, excluding leap seconds. Commands with a
timestamp more than 5 minutes from the current time are rejected. The command is then
encrypted using AES-256-GCM in AEAD mode, with a secret key that is derived from the ECDH
key-pair by running the shared secret through SHA-256 hashing, once. An IV of
96 bits of CSRNG data is used. The tag for AEAD must be 128 bits long. A new
command is created that contains the fields::
version: copied form the original command
iv: base85 encoded IV
tag: base85 encoded AEAD tag
pubkey: base85 encoded ECDH public key of sender
enc_proto: The first field from KITTY_PUBLIC_KEY, currently always ``1``
encrypted: The original command encrypted
.. include:: generated/rc.rst