tergent/README.md

tergent - termux ssh agent
--------------------------

An [ssh-agent implementation](https://tools.ietf.org/id/draft-miller-ssh-agent-02.html) for [Termux](https://termux.com/) that uses [Android Keystore](https://developer.android.com/training/articles/keystore) as its backend.

This application enables the use of keys securely stored in termux-api with ssh-agent protocol capable clients. These clients include the applications provided by openssh, such as `ssh`, `scp`, `ssh-add` and `ssh-copy-id`.

Tergent does not (and cannot) access your private keys as they are stored inside the secure hardware. In fact, they can never leave the chip even with root privileges, thanks to [extraction preventation](https://developer.android.com/training/articles/keystore#ExtractionPrevention).  
Cryptographic actions are performed by the hardware itself.

Compiling
---------
Install [Rust](https://www.rust-lang.org/en-US/install.html) and [Android NDK](https://developer.android.com/ndk/).  
You will need to configure cargo with the correct locations for "ar" and "linker", you can follow this page up to and including the `rustup target add ...` command:  
[https://mozilla.github.io/firefox-browser-architecture/experiments/2017-09-21-rust-on-android.html](https://mozilla.github.io/firefox-browser-architecture/experiments/2017-09-21-rust-on-android.html)  
Then this project can be compiled with the command `cargo build --target=aarch64-linux-android` (or any other Android target).

Alternatively, you can download a debug build for ARM64 Android from the releases page.

Usage
-----
1. Make sure you have the latest version of [Termux:API](https://play.google.com/store/apps/details?id=com.termux.api) installed. Don't forget to install the scripts using the command `pkg install termux-api`.

2. Generate a key using the command `termux-keystore generate myAlias`, where myAlias is the name you want to give to the key.
 - This command creates an RSA key - to create an ECDSA key, use the argument "-a EC": `termux-keystore generate myAlias -a EC`.
 - To specify a key size, use the argument "-s", e.g. `termux-keystore generate myAlias -s 4096` or `termux-keystore generate myAlias -a EC -s 521`.

3. Verify the key is generated by running the command `termux-keystore list`.

4. Run tergent with this command: `eval $(./tergent)`.

5. Again list the keys to verify, but now using the standard ssh tool: `ssh-add -l`.

6. Copy the public key to your server. For this, you have two options:
  - ssh-copy-id is the standard tool for this - invoke it by running `ssh-copy-id example.com`.
  - You can also use `ssh-add -L` (notice the uppercase L), and manually copy and append the output to the `.ssh/authorized_keys` file on your server.

7. Connect to your server using the usual command `ssh example.com`.

You will need to run the command `eval $(./tergent)` every time you start up the terminal. This command can be included in .bash_profile (or a similar script) for convenience.

How do I...
-----------
* **list keys**: run either `ssh-add -l` or `termux-keystore list`
* **create a new key**: use `termux-keystore generate`
* **use a key**: just run `ssh`
* **delete a key**: use `termux-keystore delete`
* **import a key**: not supported, generate a new key instead

Auto-locking
------------
tergent does not yet support locking the agent with a password.  
However, Android [provides a mechanism](https://developer.android.com/training/articles/keystore#UserAuthentication) to automatically lock the keys after a specified time has passed since the last device unlock. To take advantage of this feature, use the "-u" flag while generating the keys, e.g. `termux-keystore generate myAlias -u 10` for a 10-second lock. In this case, the keys are usable only for 10 seconds after the phone is unlocked. To unlock the keys after this time has passed, simply re-lock and unlock your device again.