From 84ca83ef69f748b4445023c6e56d86d12b5eb8c8 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Thu, 11 Aug 2022 06:35:25 +0530 Subject: [PATCH] Document the encryption used by remote_control_password --- docs/glossary.rst | 2 +- docs/rc_protocol.rst | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/glossary.rst b/docs/glossary.rst index 1ecbc116c..2833fc49d 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -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 diff --git a/docs/rc_protocol.rst b/docs/rc_protocol.rst index 2890430f3..7d04591e9 100644 --- a/docs/rc_protocol.rst +++ b/docs/rc_protocol.rst @@ -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