Home

Awesome

Keymaster

Build Status

Keymaster is usable short-term certificate based identity system. With a primary goal to be a single-sign-on (with optional second factor with Symantec VIP, U2F tokens, OKTA (requires using also using OKTA for password), or TOTP compatible apps (FreeOTP/google authenticator ) ) for CLI operations (both SSHD and TLS).

As a secondary role keymaster is compliant openidc provider intended for easy use for internal web based applications.

This system is easy to use, configure and administer. Keymaster has the following components:

From the user's perspective a single command is needed with no flags (after the first run). After running the client command successfully users get a 16h (or less) SSH and TLS certificates. On systems with a running ssh-agent the command also injects the certificate (with matching expiration time) so that no other interaction is needed to start using it with SSH.

For the service operators it requires adding the Keymaster certificates to the set of trusted certificates.

In general, the relationship between components is shown here:

keymaster-keymasterd interaction image

Please see the design document for more information.

Getting Started

Pre-build binaries (both RPM and DEB) can be found here: releases page or you can build it from source (please see instructions below). The RPM and DEB packages contain both server and client binaries. The tarballs only contain the client binaries.

Building from Source

Prerequisites

In addition for linux you will also need:

For Windows (both gcc and gnu-make) use: TDM-GCC (64 bit). Recent windows builds fail when using TDM-GCC 5.x. Successful builds are known with golang 1.21.X and gcc 10.X.

Building

  1. make get-deps
  2. make

The make process will build the four binaries (keymasterd, keymaster, keymaster-unlocker, and keymaster-eventmond) described above.

Running

Once you've installed (or compiled) the binaries follow the following instructions to setup a Keymaster environment

keymasterd (server)

The keymasterd service runs the following services:

To run keymasterd you will need to generate a config file. keymasterd facilitates this through the command-line arguments -generateConfig and -alsoLogToStderr. Running the keymasterd binary with these arguments will generate the following:

Notice: Keymaster has a bug where the directory locations are not written correctly to the config file. Depending on the platform you're running Keymaster on the following workaround will apply:

Supported backend authentication methods

Several authentication methods are supported by the keymasterd service. You can separately specify which authentication methods you accept for the web backend (allowed_auth_backends_for_webui) and for obtaining certificates (allowed_auth_backends_for_certs).

Credential and Token Storage

Keymaster supports SQLite and PostgreSQL to store u2f tokens or username and passwords. The storage_url field in config.yml contains the connection information for the database. If no storage_url is defined Keymaster will use an SQLite database located in the configured data directory for Keymaster. An example of a PostgreSQL url is: postgresql://dbusername:dbpassword.example.com/keymasterdbname

Openid Connect IDP

To use keymasterd as an openid connect IDP please consult the documents here

SSH Cerfificate exteansion expansion

Some systems like github.com allow the use of ssh certificates to authenticate users. To do so it is required to have speficic extensions in the ssh certificate. To accomodate this we have a bash like extension mechanism for expanding the username (some deployments require prefixes and some require some character subsituttions). We use posix expression expanding system, but we also reserve the pipe "|" so that we can do some future expansions. As of Feb 2024 only character replacement is part of the test-suite, so any other more complicated replacements are not considered forward compatible (as in the configuration may as expected in future versions).

keymaster-unlocker

The keymaster-unlocker binary allows you to 'unseal' the Keymaster environment. This binary requires a client side certificate signed by the adminCA.

keymaster (client)

The first time you run the client it requires you to specify the Keymaster server with the option -configHost. The client will connect, retrieve and store the configuration from the server. Keymaster will always use TLS. For testing you can use the -rootCAFilename option to specify a (e.g self signed) certificate for testing. The Keymaster clients will use the running OS CA store by default.

Your certificate will be created in the home directory of the user that is running the keymaster command.

Note: Your username on your target (SSH) host and the username used to authenticate to the Keymaster server should be the same.

Contributions

All contributions must be unencumbered. It is the responsibility of the contributor to ensure compliance with all laws, copyrights, patents and contracts.

LICENSE

Copyright 2016-2019 Symantec Corporation.

Copyright 2019-2024 Cloud-Foundations.org

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Versioning

Keymaster versions follow the Sementic Versioning guidelines.