Skip to main content

User manual

This document will provide the necessary information to use K1 and introduce essential concepts and terminology.

Configuration​

By default K1 reads its configuration from the TOML file config.toml. This behaviour can be modified by pointing the environment variable K1_CONFIGFILE at the path to the desired config file. The supported file formats are TOML, YAML, and JSON.

All configuration options are documented in the following example configuration:

# Server configuration
[server]
# The address of this instance
endpoint = "localhost:50051"

# Storage configuration
[storage]
# The SQL user that will own the client session.
username = "keyserver"
# Password for the SQL user.
password = "keyserver"
# The host name or address of an SQL database.
host = "localhost"
# The port number of the SQL interface.
port = "5432"
# The name of the database to connect to.
database = "keyserver"
# The TLS mode to use: disable, require, verify-ca, or verify-full.
tlsmode = "disable"
# Path to the CA certificate, when tlsmode is not "disable".
tlscacert = ""
# Path to the client certificate, when tlsmode is not "disable".
tlscert = ""
# Path to the client private key, when tlsmode is not "disable".
tlskey = ""
# Schema file executed on startup.
schema = "./storage/ks_storage.sql"

# Key Provider configuration
[keyprovider]

    [keyprovider.standalone]
    # Key for key wrapping initialization in memory.
    kwpinitkey = "0000000000000000000000000000000000000000000000000000000000000000"

    # [keyprovider.gcloudkms]
    # # The location that supports HSM protection level, used only for key generation.
    # location = ""
    # # The resource name of CryptoKeyVersion to use for symmetric encryption/decryption.
    # keyname = ""

    # [keyprovider.azurekeyvault]
    # # Unique Key Vault URI
    # vaulturi = ""
    # # Name of the key created in Azure Key Vault (as HSM - Premium tier). Must allow `wrap key` and `unwrap key` operations.
    # keyname = ""
    # # Version of the key specified above. Optional, will use current version if not specified.
    # keyversion = ""

    # [keyprovider.awskms]
    # # The region the SDK will use to make AWS API requests to.
    # region = ""
    # # Identifies the KMS key to use in the wrapping operation.
    # keyid = ""

    # [keyprovider.kmip]
    # Server endpoint as "host:port".
    # endpoint = ""
    # Path to CA certificate for TLS config.
    # cacertpath = ""
    # Path to client certificate for TLS config.
    # certpath = ""
    # Path to client private key for TLS config.
    # keypath = ""
    # Identifies the key to use in the wrapping operation.
    # keyid = ""

All configuration options can be overwritten by a corresponding environment variable. For example, the hostname of the Key Storage database can be overwritten by setting K1_STORAGE_HOST.

The configuration is divided into 3 sections. Each section is briefly described below.

Server config​

When K1 is running in server mode, this configuration determines its behaviour. It is important that the endpoint defined here is the same used by any clients.

Storage config​

The storage configuration determines the connection used between K1 and the key storage database. Currently only PostgreSQL is supported.

Key Provider Config​

The Key Provider configuration determines which HSM/KMS is used for managing the key material. Currently the following Key Providers are supported:

CLI Management​

An administrator can interact with K1 through a simple CLI. The following commands are available:

  • newKeySet: Creates a new Key Set.
  • newKik: Creates a new Key Inititalization Key (KIK) for a Key Set.
  • getKsIDs: Returns all saved Key Set IDs.
  • getKikIDs: Returns KIK IDs for a given Key Set.
  • getKik: Returns the KIK with a given ID.
  • serve: Starts K1 in server mode.

For more detailed information, run k1 [command] --help.