tergent/README.md

tergent - a cryptoki library for termux keystore

A cryptoki/PKCS#11 library for Termux that uses Android Keystore as its backend.

This library enables the use of keys securely stored in termux-api with PKCS#11 protocol capable applications. These include the applications provided by openssh, such as ssh and scp.

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.
Cryptographic actions are performed by the hardware itself.

This library is aimed to be compliant with PKCS#11 version 2.40. For now it implements all the APIs required for ssh and the related applications to function. If you encounter any issues trying to use tergent with any other PKCS#11 capable application, please open a bug report.

Compiling

Install Rust and Android 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
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 precompiled deb package from the releases page, or install it from the termux package repo:

pkg i tergent

Upgrading from 0.1

Keys generated for tergent 0.1 will not work for the latest version. If you do not want to lose access to your server, generate new keys using step 2 below and copy it to your server before upgrading.
If you have already upgraded, you can download a copy of an older version from the releases page.
After upgrading, any modifications made in .bash_profile or similar files should be removed. There is no need to keep running a background process anymore.

Usage

1. Make sure you have the latest version of Termux:API installed. Don't forget to install the scripts using the command pkg install termux-api.

2. As of now termux-keystore cannot generate keys compatible with tergent. Use one of these commands instead:

• To generate an RSA key:

/data/data/com.termux/files/usr/libexec/termux-api Keystore -e command generate -e alias ALIAS -e algorithm ALGORITHM --ei purposes 12 --esa digests NONE,SHA-1,SHA-256,SHA-384,SHA-512 --ei size SIZE --ei validity VALIDITY

• To generate an EC key:

/data/data/com.termux/files/usr/libexec/termux-api Keystore -e command generate -e alias ALIAS -e algorithm EC --ei purposes 12 --esa digests NONE,SHA-1,SHA-256,SHA-384,SHA-512 -e curve CURVE --ei validity VALIDITY

• ALIAS is the name you want to give to the key.
• SIZE can be 2048, 3072 or 4096, this is only used for RSA keys.
• CURVE can be secp256r1, secp384r1 or secp521r1, this determines the EC key size.
• VALIDITY can be used for user validity, see Auto-locking below. Use 0 to disable.

3. List the keys to verify using the standard ssh tool: ssh-keygen -D $PREFIX/lib/libtergent.so. Even though the command is called ssh-keygen, -D switch lists cryptoki keys instead of generating new keys.

4. Copy the public key to your server.

   1. First export the public keys using: ssh-keygen -D $PREFIX/lib/libtergent.so > keys.pub.
   2. Optionally, remove any keys from the generated file using a text editor if needed: nano keys.pub.
   3. Copy the keys to your server using ssh-copy-id -f -i keys.pub example.com.

5. Connect to your server using the command ssh -I $PREFIX/lib/libtergent.so example.com.

To make ssh remember the library path, modify your ~/.ssh/config file. For a single host:

Host example.com
	PKCS11Provider /data/data/com.termux/files/usr/lib/libtergent.so

Or alternatively you can make tergent apply to all connections:

Host *
	PKCS11Provider /data/data/com.termux/files/usr/lib/libtergent.so

After saving this file you can just run ssh example.com to connect.

How do I...

• list keys: run either ssh-keygen -D $PREFIX/lib/libtergent.so or termux-keystore list
• create a new key: see step 2 from instructions above
• use a key: run ssh -I $PREFIX/lib/libtergent.so
• delete a key: use termux-keystore delete
• import a key: not supported, generate a new key instead

Auto-locking

tergent does not provide password protected sessions yet. However, Android provides a mechanism to automatically lock the keys after a specified time has passed since the last device unlock. To take advantage of this feature, use the flag while generating the keys, e.g. --ei validity 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.

Alternatively, you can invoke a biometric prompt (fingerprint or face unlock) which might also reset this timer depending on your device. Tergent will automatically try invoking the termux Fingerprint API to prompt biometric authentication.