Description:

mtls 0.17.0

Mutual TLS Client (mtls)




Runtime Dependencies

python >= 3.7
gnupg2
libnss3 (linux/windows)
security (MacOS)

Overview
A mutual TLS (mTLS) system for authenticating users to services that need to be on the internet, but should only be
accessible to users that specifically need it. This should be used as a initial security measure on top of normal login
to handle multi-factor authentication.
The client generates a Certificate Signing Request (CSR) and use web of trust to ensure user has authentication to
recieve a short-lived client certificate. Short-lived certificates have a default timeout of 18 hours, but can be
expanded per need.
This system uses some of the base NSS primitives found in base tools for the associted operating systems.
This project currently works in the following OSes:

Linux (Arch/Debian/Ubuntu tested)
MacOS

This project is based on the whitepapers for Beyond Corp, which is Googles Zero Trust
Security Model.
Background
What is Mutual TLS?
Mutual TLS is a sub-category of Mutual Authentication, where the
client and server, or server and server are verifying the identity of one another to ensure that both parties should be
allowed to access the requested information.
What is this Good For?
Creating services that inheritely trust no one unless specifically authorized. This provides the basis for a zero
trust, multi-factor authentication scheme while also timeboxing access to the requested service in case of compromise or
loss of access keys.
What parts of my system are affected by this?
This uses 2 certificate stores within your system. The primary is held at ~/.pki/nssdb which is the default nssdb that
most of the OS trusts. A secondary nssdb will exist within .mozilla/firefox/ which is a firefox specific nssdb and is
required to interface with any mozilla products. There are slightly different commands that are required depending on
the operating system.
To list certificates via the commandline on Linux:
certutil -L -d ~/.pki/nssdb
To verify a certificate via the commandline on Linux:
certutil -V -u C -d ~/.pki/nssdb -n '<Server> - <name>@<host>'
A Root certificate is required for this. The CLI will by default pull the Root CA and install it into your Trust Store
as a Trusted Root Certificate.
Installation
Building From Source
$ git clone https://github.com/drGrove/mtls-cli
$ make build
# If you'd like to install directly into ~/.local/bin you can also use
$ make install

Using The Latest Release
There are signed binaries that are shipped along with each release. To use a binary you can do the following:
$ VERSION=<version> (ex. VERSION=v0.8.0)
$ wget https://github.com/drGrove/mtls-cli/releases/download/$VERSION/mtls-$VERSION.tar.gz
$ tar zxvf mtls-$VERSION.tar.gz
$ cd mtls
$ sha256sum mtls && cat mtls.sha256sum
$ gpg --recv-keys C92FE5A3FBD58DD3EC5AA26BB10116B8193F2DBD
$ gpg --verify --trust-model always mtls.sig
# From there you can install the binary wherever you'd like in your path

Configuration
Configuring mtls is done via a config.ini. There is an example in the repo here.
You'll need a similar base configuration:
[DEFAULT]
name=John Doe
email=johndoe@example.com
; PGP Fingerprint
fingerprint=XXXXXXXX
country=US
state=CA
locality=Mountain View
organization=myhost

Then for each server you'd like to connect to you can create a section for that service.
[myserver]
email=johndoe@myserver.com
url=https://certauth.myserver.com

The url should match the base URL of the Certificate Authority you'll connect to. This will allow mtls to make the
requests to generate your client certificate.
Usage
Once configured and provided access by a Certificate Authority Administrator you will be able to begin creating
certificates for yourself. By default the lifetime of your certificate is 18 hours. But Certificate Authorities are able
to set their own minimum and maximum lifetime. Speak to a certificate authority administrator about their settings.
Creating A Certificate
$ mtls -s myserver certificate create

Revoking A Certificate
If you're certificate has become compromised you can revoke your certificate prior to it's expiration. Certificate
Authority Administrators can also expire certificates if they feel that you've been compromised or if they belive you
should no longer have access to the services.
You have a few options as far a certificate revoke goes.
By Serial Number
$ mtls -s myserver certificate revoke --serial <Certificate Serial Number>

By Certificate Name
To get a certificate name, it will follow the following convention: ISSUER - USER@HOSTNAME. On the first connection to
a Certificate Authority, you're ~/.config/mtls/config.ini for a particular server will be updated to provide the
issuer name as found in the Root CA Certificate. You can also find this by running certutil -L -d ~/.pki/nssdb or
viewing the certificate in chrome or firefox
$ mtls -s myserver certicate revoke --name <name>

By Fingerprint
NOTE: This will revoke all certificates related to a particular fingerprint
$ mtls -s myserver certificate revoke --fingerprint <fingerprint>

Administration
Administration of the mtls can be done via the CLI as well. Administrators can add and remove users as they see fit
but currently an administator needs to be removed individually from both trust stores.
Users
Adding Users
By Fingerprint
$ mtls -s myserver user add --fingeprint FINGERPRINT

By Email
This will poll pgp.mit.edu by default and return a list of PGP keys if more than 1 valid PGP key is returned. You can
query any keyserver via the --keyserver KEYSERVER_URL flag
$ mtls -s myserver user add --email johndoe@example.com

Removing Users
By Fingerprint
$ mtls -s myserver user remove --fingeprint FINGERPRINT

By Email
This will poll pgp.mit.edu by default and return a list of PGP keys if more than 1 valid PGP key is returned. You can
query any keyserver via the --keyserver KEYSERVER_URL flag
$ mtls -s myserver user remove --email johndoe@example.com

Administrators
Adding Admins
By Fingerprint
$ mtls -s myserver user add --fingeprint FINGERPRINT --admin

By Email
This will poll pgp.mit.edu by default and return a list of PGP keys if more than 1 valid PGP key is returned. You can
query any keyserver via the --keyserver KEYSERVER_URL flag
$ mtls -s myserver user add --email johndoe@example.com --admin

Removing Users
By Fingerprint
$ mtls -s myserver user remove --fingeprint FINGERPRINT --admin

By Email
This will poll pgp.mit.edu by default and return a list of PGP keys if more than 1 valid PGP key is returned. You can
query any keyserver via the --keyserver KEYSERVER_URL flag
$ mtls -s myserver user remove --email johndoe@example.com --admin

Development
Dependencies

make
pip
pipenv
gnupg
libnss (certutil/pk12util on linux/windows, security on MacOS)

Getting Started
To begin development run the following commands:
make setup
mkdir ~/.config/mtls
cp config.ini.example config.ini

NOTE: You will need to add a server to communicate with. The URL must have a scheme.
You can run without compiling by using:
make run SERVICE=myservice

To build a binary:
make build

NOTE: This will output to an mtls folder within the root of the project. This folder has been gitignored and only
artifacts of the build belong in this directory

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter