Perform the Fulcio key ceremony

Initialize the HSM token and generate the Fulcio certificate authority signing key and root CA certificate.

Before you begin

  • HSM prerequisites are configured, including ConfigMaps, Secrets, and PersistentVolumeClaims.
  • Access to your HSM vendor’s key ceremony tools, or for SoftHSM, access to create Kubernetes Jobs.
  • Understanding of your organization’s key ceremony policies and procedures.

Procedure

  1. Initialize the HSM token with a label and generate a P-256 key pair:
    • Initialize the HSM token with label PKCS11CA
    • Generate a P-256 ECDSA key pair with CKA_ID 99
    • Create a self-signed root CA certificate using the HSM-resident key
    • Extract the root CA certificate in PEM format

    For production HSMs, use your vendor’s key ceremony tools (for example, Luna cmu or CloudHSM key_mgmt_util) to generate the key pair and certificate. Export the root CA certificate in PEM format.

  2. For SoftHSM, create a Kubernetes Job to perform the ceremony: 
    apiVersion: batch/v1
kind: Job
metadata:
  name: fulcio-key-ceremony
  namespace: trusted-artifact-signer
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: ceremony
          image: HSM_INIT_IMAGE
          command: ["/bin/bash", "-c"]
          args:
            - |
              softhsm2-util --init-token --free --label PKCS11CA \
                --pin $HSM_PIN --so-pin $HSM_PIN
              pkcs11-tool --module /usr/lib64/pkcs11/libsofthsm2.so \
                --login --pin $HSM_PIN --token-label PKCS11CA \
                --keypairgen --key-type EC:prime256v1 \
                --id 63 --label PKCS11CA
              cat > /tmp/crypto11.conf <<EOF
              {"Path":"/usr/lib64/pkcs11/libsofthsm2.so","TokenLabel":"PKCS11CA","Pin":"$HSM_PIN"}
              EOF
              fulcio createca --org YOUR_ORG --country CC --province STATE \
                --locality CITY --hsm-caroot-id 99 \
                --pkcs11-config-path /tmp/crypto11.conf --out /tmp/root-ca.pem
              cat /tmp/root-ca.pem
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop: ["ALL"]
          env:
            - name: HSM_PIN
              valueFrom:
                secretKeyRef:
                  name: hsm-credentials
                  key: pin
            - name: SOFTHSM2_CONF
              value: /etc/softhsm/softhsm2.conf
          volumeMounts:
            - name: hsm-config
              mountPath: /etc/softhsm
              readOnly: true
            - name: hsm-tokens
              mountPath: /var/run/hsm-tokens
      volumes:
        - name: hsm-config
          configMap:
            name: softhsm-config
        - name: hsm-tokens
          persistentVolumeClaim:
            claimName: hsm-tokens-pvc

    where:

    HSM_INIT_IMAGE
    The container image containing SoftHSM and Fulcio tools.
    YOUR_ORG
    Your organization name.
    CC
    Your two-letter country code.
    STATE
    Your state or province.
    CITY
    Your city or locality.
  3. Wait for the Job to complete: 
    $ oc wait --for=condition=complete job/fulcio-key-ceremony \
  -n trusted-artifact-signer --timeout=5m
  4. Extract the root CA certificate from the Job logs: 
    $ oc logs job/fulcio-key-ceremony -n trusted-artifact-signer > /tmp/root-ca.pem
  5. Create a Secret containing the root CA certificate: 
    $ oc create secret generic fulcio-root-ca \
  --from-file=cert.pem=/tmp/root-ca.pem \
  -n trusted-artifact-signer
  6. Create the Fulcio crypto11 configuration Secret: 
    $ oc create secret generic fulcio-pkcs11-config \
  --from-literal=crypto11.conf='{"Path":"/var/run/hsm-lib/libsofthsm2.so","TokenLabel":"PKCS11CA","Pin":"'$HSM_PIN'"}' \
  -n trusted-artifact-signer
    Important

    The Path field must point to /var/run/hsm-lib/<module-filename> because the RHTAS Operator mounts the PKCS #11 library at /var/run/hsm-lib/ via the init container and hsm-lib volume.