######################################################################################
#                                                                                    #
#                       ----==== SIGNER CONFIGURATION ====----                       #
#                                                                                    #
#       The settings below can be used to configure the signer used by Krill.        #
#                                                                                    #
######################################################################################


# Signers
# -------
#
# A signer is a cryptographic token, either hardware or software, local or remote,
# that can create RSA public/private key pairs and can sign data with the private key.
#
# Supported signer types
# ----------------------
#
# Krill supports three types of signer:
#
#   - OpenSSL based: Uses the OpenSSL library installed on the host O/S. On older
#     operating systems it might be that a newer version of OpenSSL than is supported
#     by the host O/S has been compiled into Krill itself and will be used instead.
#
#   - PKCS#11 based: Uses a PKCS#11 v2.20 conformant library file from the filesystem.
#     How the library handles the requests on behalf of Krill is library specific. A
#     library such as SoftHSMv2 contains all of the code needed to handle the request
#     and stores generated keys on the host filesystem. Libraries provided by well
#     known HSM vendors will dispatch requests to one or a cluster of hardware 
#     security modules connected either physically or by network connection to the
#     host on which Krill is running.
#
#   - KMIP based: Makes TLS encrypted TCP connections to an operator specified server
#     running a KMIP v1.2 conformant service.
#
# Key creation policy
# -------------------
#
# Krill creates keys at different times for different purposes. Some keys are fixed
# such as the identity key for the RFC 8183 defined provisioning protocol, others can
# be rolled (e.g. the keys used for RPKI CA certificates in resource classes) and
# still others are one-off keys (e.g. keys used for EE certificates in CMS) that are
# discarded after use.
#
# Signer roles
# ------------
#
# Signers can be assigned to roles to implement the desired policy. Roles are assigned
# by setting the following top level configuration file settings:
#
#   - default_signer: The signer will be used to generate new long-term key pairs.
#     Only one signer may be designated as the default. If only one signer is defined
#     it will be the default. If more than one signer is defined one must be
#     explicitly set as the default.
#
#   - one_off_signer: The signer will be used to generate, sign with and destroy
#     one-off key pairs. Only one signer may be designated as the oneoff signer. When
#     not specified an OpenSSL signer will be used for this.
#
# These settings must be set to the name of a single signer, e.g.:
#
#   default_signer = "My signer"
#
#   [[signers]]
#   type = "OpenSSL"
#   name = "My signer"
#
# Required capabiliites
# ---------------------
#
# When Krill first connects to a new signer it will verify that the signer meets its
# requirements. In particular it will require the signer to generate an RSA key pair
# and to demonstrate that it can sign data correctly using the generated private key.
#
# Config file settings
# --------------------
#
# At a minimum the "name" and "type" must be specified for a signer.
#
# One optional setting can also be set for all signers:
#
# - signer_probe_retry_seconds: When initially connecting to the signer on first use
#   after Krill startup, wait at least N seconds between attempts to connect and
#   test the signer for compatibility with Krill. Defaults to 30 seconds.
#
# The remaining details that must be supplied to configure a signer vary by signer
# type and by specific implementation. For example an OpenSSL signer doesn't require
# a path to a library file to load, while a PKCS#11 signer does, and one PKCS#11
# vendor may require login by PIN code while another might allow operations to be
# performed with external PIN entry or no PIN entry at all.
#
# Default configuration
# ---------------------
#
# The default configuration is equivalent to:
#
#   [[signers]]
#   type = "OpenSSL"
#   name = "Default OpenSSL signer"
#
# Changing the configuration
# --------------------------
#
# The number, type, order, settings, names of signers can be changed at any time.
# Krill will apply the changes when next restarted. Via the use of identity key
# based signer binding Krill will still find the keys that it has created as long as
# the same backend is connected to, irrespective of name or connection details, and
# that the identity key in the signer has not been deleted.
#
# Warning about removing an in-use signer
# ---------------------------------------
#
# Removing a signer that owns keys that Krill is still using will prevent Krill from
# accessing those keys!
#
# Example configuration
# ---------------------
#
# Below is an example configuration. This example defines many signers but normally
# one would define only a single signer, or two signers if migrating from one signer
# to another.
#
#   default_signer = "SoftHSMv2 via PKCS#11"
#
#   [[signers]]
#   type = "OpenSSL"
#   name = "Signer 1"
#
#   [[signers]]
#   type = "OpenSSL"
#   name = "Signer 2"
#   keys_path = "/tmp/keys"
#
#   [[signers]]
#   type = "PKCS#11"
#   name = "Kryptus via PKCS#11"
#   lib_path = "/usr/local/lib/kryptus/libknetpkcs11_64/libkNETPKCS11.so"
#   user_pin = "xxxxxx"
#   slot = 313129207
#
#   [[signers]]
#   type = "PKCS#11"
#   name = "SoftHSMv2 via PKCS#11"
#   lib_path = "/usr/local/lib/softhsm/libsofthsm2.so"
#   user_pin = "xxxx"
#   slot = 0x12a9f8f7
#   public_key_attributes = {
#     CKA_PRIVATE = false
#   }
#
#   [[signers]]
#   type = "KMIP"
#   name = "Kryptus via KMIP"
#   host = "my.hsm.example.com"
#   port = 5696
#   server_ca_cert_path = "/path/to/some/ca.pem"
#   username = "user1"
#   password = "xxxxxx"


# OpenSSL signer configuration
# ----------------------------
#
# This signer uses the operating system provided OpenSSL library (or on older
# operating systems it may use a modern version of the OpenSSL library compiled into
# Krill itself) to generate keys, to sign data using them and to generate random
# values. Keys are persisted as files on disk in a dedicated directory.
#
# Key        Value Type   Default          Req'd  Description
# ====================================================================================
# keys_path  path string  "$datadir/keys"  No     The directory in which key files
#                                                 should be created.
#


# PKCS#11 signer configuration
# ----------------------------
#
# Krill interacts with a PKCS#11 v2.20 compatible cryptographic device via the Cryptoki
# interface which involves loading a library file from disk at runtime to which all
# cryptographic operations will be delegated. The library will in turn communicate
# with the actual cryptographic device.
#
# Note: The PKCS#11 library is not part of Krill nor is it supplied with Krill. Please
# consult the documentation for your PKCS#11 compatible cryptographic device to learn
# where you can find the .so library file and how to set up and configure it. For
# example when using SoftHSMv2 the library is commonly available at filesystem path
# /usr/lib/softhsm/libsofthsm2.so.
#
# Key                 Value Type   Default  Req'd  Description
# ====================================================================================
# lib_path            string       None     Yes    The path to the .so dynamic library
#                                                  file to load.
# slot                integer or   None     Yes    An integer PKCS#11 "slot" ID or a
#                     string                       string "slot" label. Can also be
#                                                  given in hexadecimal, e.g. 0x12AB.
#                                                  When a label is given Krill will
#                                                  inspect all available slots and use
#                                                  the first slot whose label matches.
# ------------------------------------------------------------------------------------
# user_pin            string       None     No     The pin or password or secret value
#                                                  used to authenticate with the
#                                                  PKCS#11 provider. The format varies
#                                                  by provider, SoftHSMv2 uses numeric
#                                                  PINs such as "12345" while AWS
#                                                  CloudHSM expects this to be in the
#                                                  form "username:password".
# login               boolean      true     No     Whether the signer must be logged
#                                                  in to before performing other
#                                                  operations.
# ------------------------------------------------------------------------------------
# retry_seconds       integer      2        No     Wait N seconds before retrying a
#                                                  failed request.
# backoff_multiplier  float        1.5      No     How much longer to wait before
#                                                  retry N+1 compared to retry N.
# max_retry_seconds   integer      30       No     Stop retrying after N seconds.
#
# Overriding PKCS#11 key attributes
# ---------------------------------
#
# If needed, some of the default attributes applied to created public and private keys
# can be overriden by defining 'public_key_attributes' and/or 'private_key_attributes'
# child sections under the PKCS#11 config section.
#
# Note that changing these settings *after* a key pair has been created will have no
# effect on that key pair, only subsequently created key pairs will be affected.
#
# Changing the key attribute values from their Krill defaults may be needed to make
# Krill compatible with your HSM, e.g. if the HSM does not support authenticated
# access to public keys. Changing key attribute values may also be needed to support
# your particular HSM security setup, if for example the default setting of
# CKA_EXTRACTABLE = false would prevent you migrating from one HSM to another. The
# exact key attribute values needed for your setup may differ from the Krill
# defaults. Please consult your HSM documentation for more information.
#
# Each attribute takes a boolean value, or if not present indicates that the PKCS#11
# driver/HSM default should be used.
#
# Possible attributes that can be set are listed below, along with their default
# values. More information about these attributes is available in the PKCS#11 v2.40
# specification [1].
#
#   public_key_attributes = {
#     #CKA_MODIFIABLE = ... # not set by default
#     CKA_PRIVATE = true
#   }
#
#   private_key_attributes = {
#     CKA_EXTRACTABLE = false
#     #CKA_MODIFIABLE = ... # not set by default
#     CKA_PRIVATE = true
#     CKA_SENSITIVE = true
#   }
#
# [1]: http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html


# KMIP signer configuration
#
# Krill interacts with a KMIP v1.2 compatible cryptographic device via the TCP+TTVL
# protocol. This requires knowing the hostname, port number, and details required to
# authenticate with the provider.
#
# Key                 Value Type  Default  Req'd  Description
# ====================================================================================
# host                string      None     Yes    The domain name or IP address to
#                                                 connect to.
# port                integer     5696     No     The port number to connect to.
# ------------------------------------------------------------------------------------
# insecure            boolean     false    No     If true, do not verify the servers
#                                                 TLS certificate.
# force               boolean     false    No     If true, ignore server claims that
#                                                 it lacks functionality that we
#                                                 require. For example PyKMIP 0.10.0
#                                                 says it doesn't support operation
#                                                 ModifyAttribute but sending a
#                                                 modify attribute request succeeds.
# ------------------------------------------------------------------------------------
# server_cert_path                                File system paths to certificate
#                     string      None     No     files (in PEM format) for verifying
# server_ca_cert_path                             the identity of the server.
#                     string      None     No     
# ------------------------------------------------------------------------------------
# client_cert_path                                File system paths to certificate and
#                     string      None     No     key files (in PEM format) for
# client_cert_private_key_path                    proving our identity to the server.
#                     string      None     No     
# ------------------------------------------------------------------------------------
# username            string      None     No     Credentials for authenticating with
# password            string      None     No     the server.
# ------------------------------------------------------------------------------------
# retry_seconds       integer     2        No     Wait N seconds before retrying a
#                                                 failed request.
# backoff_multiplier  float       1.5      No     How much longer to wait before retry
#                                                 N+1 compared to retry N.
# max_retry_seconds   integer     30       No     Stop retrying after N seconds.
# ------------------------------------------------------------------------------------
# connect_timeout_seconds                         Wait at most N seconds to make a TCP
#                     integer     5        No     connection to the KMIP server.
# read_timeout_seconds                            Wait at most N seconds for more
#                     integer     5        No     response bytes to be received from
#                                                 the KMIP server.
# write_timeout_seconds                           Wait at most N seconds to write more
#                     integer     5        No     request bytes to the connection to
#                                                 the KMIP server.
# max_use_seconds     integer     60*30    No     Don't use an idle connection to the 
#                                                 KMIP server if it has been connected
#                                                 for at least N seconds.
# max_idle_seconds    integer     60*10    No     Close open connections to the KMIP
#                                                 server if not used in the last N
#                                                 seconds.
# ------------------------------------------------------------------------------------
# max_connections     integer     5        No     The maximum number of concurrent
#                                                 connections to permit to the server.
# max_response_bytes  integer     64*1024  No     The maximum number of response bytes
#                                                 to accept from the KMIP server, or
#                                                 otherwise treat the request as
#                                                 failed.
