Getting Started (original) (raw)

This Quickstart shows you how to setup a local KES server that stores keys in-memory.

Not permanent:

The in-memory key store will lose all state on restarts. It should only be used for testing purposes.

K E S C l i e n t K E S S e r v e r I n - M e m o r y

Quickstart

Development Mode:

For a quick development test server, use

This starts a KES server on 127.0.0.1:7373 and stores keys in memory.

  1. Install the KES binary
    You can install the KES binary by:
    • downloading a pre-compiled Binary Release
    • pulling the Docker image
    • issuing a Homebrew command
    • compiling from Source with your Go toolchain
      Select the tab below for the method you would like to use.
      Binary Releases
      Docker
      Homebrew
      Source
      Confirm command availability by running the following command from your prompt or terminal:
      You may need to adjust the command for your OS structure and PATH, such as with ./kes --help.
  2. Generate KES Server Private Key & Certificate
    Generate a TLS private key and certificate for the KES server. This key is used for domain name verification.
    A KES server is secure-by-default and can only be run with TLS. In this guide, we use self-signed certificates for simplicity.
    The following command generates a new TLS private key (private.key) and a self-signed X.509 certificate (public.crt) issued for the IP 127.0.0.1 and DNS name localhost:
$ kes identity new --ip "127.0.0.1" --key "private.key" --cert "public.crt" localhost  
  Private key:  private.key  
  Certificate:  public.crt  
  Identity:     2e897f99a779cf5dd147e58de0fe55a494f546f4dcae8bc9e5426d2b5cd35680

Existing Key & Certificate:
If you already have a TLS private key & certificate, such as from a WebPKI or internal Certificate Authority, you can use them instead. Remember to adjust the tls config section. 3. Generate Client Credentials
The client application needs credentials to access the KES server. Generate an API key from the client’s key and certificate to verify the client application to the KES server.
The following command generates a new TLS private/public key pair for MyApp: 

$ kes identity new --key=client.key --cert=client.crt MyApp  
  Private key:  client.key  
  Certificate:  client.crt  
  Identity:     02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b

The identity 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b is a unique fingerprint of the public key in client.crt. You can re-compute the fingerprint at anytime: 

$ kes identity of client.crt  
  Identity:  02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b
  1. Configure KES Server
    Create the KES server configuration file: config.yml. Ensure the identity in the policy section matches your client.crt identity.
address: 0.0.0.0:7373 # Listen on all network interfaces on port 7373  
admin:  
  identity: 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b # The client.crt identity  
tls:  
  key: private.key    # The KES server TLS private key  
  cert: public.crt    # The KES server TLS certificate
  1. Start KES Server
    Start the KES server instance:
kes server --config config.yml

KES CLI Access

  1. Set KES_SERVER endpoint
    This variable tells the KES CLI which KES server to access.
export KES_SERVER=https://127.0.0.1:7373
  1. Use Client Credentials
    These variables tell the KES CLI which credentials to use to access to a KES server.
export KES_CLIENT_CERT=client.crt  
export KES_CLIENT_KEY=client.key
  1. Perform Operations
    Now, we can perform any API operation. Since we are using the admin identity, we do not have to worry about policy permissions.
    Then, we can use that key to generate a new data encryption key:
$ kes key dek my-key-1  
{  
  plaintext : UGgcVBgyQYwxKzve7UJNV5x8aTiPJFoR+s828reNjh0=  
  ciphertext: eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaWQiOiIxMTc1ZjJjNDMyMjNjNjNmNjY1MDk5ZDExNmU3Yzc4NCIsIml2IjoiVHBtbHpWTDh5a2t4VVREV1RSTU5Tdz09Iiwibm9uY2UiOiJkeGl0R3A3bFB6S21rTE5HIiwiYnl0ZXMiOiJaaWdobEZrTUFuVVBWSG0wZDhSYUNBY3pnRWRsQzJqWFhCK1YxaWl2MXdnYjhBRytuTWx0Y3BGK0RtV1VoNkZaIn0=  
}

Upgrading KES

To upgrade KES, follow the getting started steps and replace the KES binary with the newer version on each KES server node.

Due to changes in how KES processes ciphertext, it is not possible to revert to an earlier version after upgrading to release 2024-02-29T08-12-28Z or later. MinIO recommends always testing in a lower environment such as staging or development prior to upgrading production.

References