A simple service for interacting with an HSM or other PKCS#11 device.
A simple service for interacting with an HSM or other PKCS #11 device. It supports minting and signing of both SSH and x509 certificates. Crypki is the certificate signing backend for the Athenz RBAC system.
You should be able to run crypki server on any linux platform as long as you have crypki binary and .so file. We have tested it on RHEL 7, RHEL 8, Debian 9 & Ubuntu 18.04.
Prerequisites:
- Go >= 1.22.4
Run:
go install github.com/theparanoids/crypki/cmd/crypki@latest
To start crypki server clone the repo and run the following commands.
-
Build docker image
docker build -f docker-softhsm/Dockerfile -t crypki-local .
If you want to speed up docker image build process, before running the command above, you can cache the dependencies locally using the following command.
go mod vendor
-
Generate certs and keys required for mutual TLS between the front end-client and the crypki backend server
cd docker-softhsm ./gen-crt.sh
-
Start the docker container
docker run -d -p :4443:4443 -v $PWD/log:/var/log/crypki -v $PWD/tls-crt:/opt/crypki/tls-crt:ro -v $PWD/shm:/dev/shm --rm --name crypki -h "localhost" crypki-local
-
Verify whether the server is up and running
curl -X GET https://localhost:4443/ruok --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Disclaimer: the above installation guidelines are to help you to get started with crypki; they should be used only for testing/development purposes. Please do not use this setup for production, because it is not secure.
Take a look at the sample configuration file to see how to configure crypki
APIs for crypki are defined under crypki/proto. If you are familiar with or are using grpc, you can directly invoke the rpc methods defined in the proto file.
Examples:
Get all available SSH signing keys
curl -X GET https://localhost:4443/v3/sig/ssh-user-cert/keys --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Get SSH user public signing key (CA public key for ssh-user-cert)
curl -X GET https://localhost:4443/v3/sig/ssh-user-cert/keys/ssh-user-key --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Sign SSH user certificate
curl -X POST -H "Content-Type: application/json" https://localhost:4443/v3/sig/ssh-user-cert/keys/ssh-user-key --data @ssh_csr.json --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Get all available x509 signing keys
curl -X GET https://localhost:4443/v3/sig/x509-cert/keys --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Get x509 public CA certificate
curl -X GET https://localhost:4443/v3/sig/x509-cert/keys/x509-key --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Sign x509 certificate
curl -X POST -H "Content-Type: application/json" https://localhost:4443/v3/sig/x509-cert/keys/x509-key --data @x509_csr.json --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Get blob signing public key
curl -X GET https://localhost:4443/v3/sig/blob/keys/sign-blob-key --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Sign blob (input is base64 encoded value of raw hash of a blob. example code)
curl -X POST -H "Content-Type: application/json" https://localhost:4443/v3/sig/blob/keys/sign-blob-key --data @sign_blob.json --cert tls-crt/client.crt --key tls-crt/client.key --cacert tls-crt/ca.crt
Note: init_hsm.sh extracts the public keys of each key slot from the SoftHSM, and stores inside the container.
Following script exports the public key (in PEM format) of slot user_ssh_pub
from the container, and converts it into SSH format.
docker cp crypki:/opt/crypki/slot_pubkeys/user_ssh_pub.pem ~/tmp/user_ssh_pub.pem
ssh-keygen -f ~/tmp/user_ssh_pub.pem -i -mPKCS8
Generate a self-signed X509 CA cert for key identifier x509-key
by gen-cacert
binary.
# Get into the shell of crypki container.
docker exec -ti crypki /bin/bash
# Refer to `/opt/crypki/crypki-softhsm.json` and `init_hsm.sh` to find out the attributes $SLOT_NUMBER, $KEY_LABEL, and $USER_PIN.
# In the example, our keyLabel is host_x509, keyType is 3 and signatureAlgorithm is 11 for `x509-key`.
echo $USER_PIN > /tmp/user_pin
cat > /tmp/ca_crt_config.json <<EOF
{
"Identifier": "x509-key",
"CommonName": "www.example.com",
"KeyLabel": "host_x509",
"KeyType": 3,
"SignatureAlgo": 11,
"PKCS11ModulePath": "/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so",
"SlotNumber": $SLOT_NUMBER,
"UserPinPath": "/tmp/user_pin"
}
EOF
/usr/bin/gen-cacert -config=/tmp/ca_crt_config.json -out=/tmp/x509-ca.cert
# You will see a newly signed x509 CA certificate printed and written to the `-out` path.
-
Please refer to Contributing.md for information about how to get involved. We welcome issues, questions and pull requests.
-
You can also contact us for any user and development discussions through our group crypki-dev
This project is licensed under the terms of the Apache 2.0 open source license. Please refer to LICENSE for the full terms.