KES is a cloud-native distributed key management and encryption server designed to secure modern applications at scale.
What is KES?
KES is a distributed key management server that scales horizontally. It can either be run as edge server close to the applications reducing latency to and load on a central key management system (KMS) or as central key management server. Edge servers are self-contained stateless nodes close to the application that can be scaled up/down automatically. Central KES servers or clusters are stateful systems that store and manage cryptographic keys and secrets securely.
Install
The KES server and CLI is available as a single binary, container image or can be build from source.
Homebrew
brew install minio/stable/kes
Binary Releases
OS | ARCH | Binary |
---|---|---|
Linux | amd64 | linux-amd64 |
Linux | arm64 | linux-arm64 |
Linux | ppc64le | linux-ppc64le |
Linux | s390x | linux-s390x |
Apple M1 | arm64 | darwin-arm64 |
Apple | amd64 | darwin-amd64 |
Windows | amd64 | windows-amd64 |
You can also verify the binary with minisign by downloading the corresponding .minisig
signature file. Then run:
minisign -Vm kes-<OS>-<ARCH> -P RWTx5Zr1tiHQLwG9keckT0c45M3AGeHD6IvimQHpyRywVWGbP1aVSGav
Build from source
Download and install the binary via your Go toolchain:
go install github.com/minio/kes/cmd/kes@latest
Quick Start
We run a public KES instance at https://play.min.io:7373
for you to experiment with.
You can interact with our play instance either via the KES CLI or cURL. Alternatively, you can
get started by setting up your own KES server in less than five minutes.
CLI
1. Configure CLI
We point the KES CLI to the KES server at https://play.min.io:7373
and use the following API key:
export KES_SERVER=https://play.min.io:7373
export KES_API_KEY=kes:v1:AD9E7FSYWrMD+VjhI6q545cYT9YOyFxZb7UnjEepYDRc
3. Create a Key
Next, we can create a new root encryption key - e.g. my-key
.
kes key create my-key
Note that creating a new key will fail with
key already exist
if it already exist.
4. Generate a DEK
Now, you can use that key to derive a new data encryption keys (DEK).
kes key dek my-key
The plaintext part of the DEK would be used by an application to encrypt some data. The ciphertext part of the DEK would be stored alongside the encrypted data for future decryption.
Server
For a quickstart setup take a look at our FS guide. For further references checkout our list of key store guides.
cURL
1. Fetch Admin Credentials
As an initial step, you will need to download the private key and certificate to authenticate to the KES server as the admin.
curl -sSL --tlsv1.2 \
-O 'https://raw.githubusercontent.com/minio/kes/master/root.key' \
-O 'https://raw.githubusercontent.com/minio/kes/master/root.cert'
2. Create a Key
Next, we can create a new root encryption key - e.g. my-key
.
curl -sSL --tlsv1.3 \
--key root.key \
--cert root.cert \
-X POST 'https://play.min.io:7373/v1/key/create/my-key'
Note that creating a new key will fail with
key already exist
if it already exist.
3. Generate a DEK
Now, you can use that key to derive a new data encryption keys (DEK).
curl -sSL --tlsv1.3 \
--key root.key \
--cert root.cert \
--data '{}' \
-X POST 'https://play.min.io:7373/v1/key/generate/my-key'
The plaintext part of the DEK would be used by an application to encrypt some data. The ciphertext part of the DEK would be stored alongside the encrypted data for future decryption.
4. Further References
For a comprehensive list of REST API endpoints refer to the KES API overview.
Docs
If you want to learn more about KES checkout our documentation.
FAQs
I have received an insufficient permissions
error
This means that you are using a KES identity that is not allowed to perform a specific operation, like creating or listing keys.
The KES admin identity
can perform any general purpose API operation. You should never experience a not authorized: insufficient permissions
error when performing general purpose API operations using the admin identity.
In addition to the admin identity, KES supports a policy-based access control model.
You will receive a not authorized: insufficient permissions
error in the following two cases:
-
You are using a KES identity that is not assigned to any policy. KES rejects requests issued by unknown identities.
This can be fixed by assigning a policy to the identity. Checkout the examples.
-
You are using a KES identity that is assigned to a policy but the policy either not allows or even denies the API call.
In this case, you have to grant the API permission in the policy assigned to the identity. Checkout the list of APIs. For example, when you want to create a key you should allow the
/v1/key/create/<key-name>
. The<key-name>
can either be a specific key name, likemy-key-1
or a pattern allowing arbitrary key names, likemy-key*
.Also note that deny rules take precedence over allow rules. Hence, you have to make sure that any deny pattern does not accidentally matches your API request.
License
Use of KES
is governed by the AGPLv3 license that can be found in the LICENSE file.