intel/ctk_loadkey

KMRA - 带SGX的密钥管理参考应用 - Docker镜像

KMRA（密钥管理参考应用）是一个概念验证软件，用于演示SGX非对称/对称密钥能力与第三方HSM的集成。源代码和文档请访问：https://www.intel.com/content/www/us/en/developer/topic-technology/open/key-management-reference-application/overview.html

前置条件

在主机上安装SGX内核驱动。树外SGX内核驱动可使用kmaas/ansible/sgx-infra-setup目录中的KMRA ansible脚本安装。

标签

• KMRA v1.4 - v1
• KMRA v2.0.1 - v2
• KMRA v2.1 - v2.1
• KMRA v2.2 - v2.2
• KMRA v2.2.1 - v2.2.1
• KMRA v2.2.2 - v2.2.2
• KMRA v2.3 - v2.3

KMRA Docker镜像部署

准备工作

1. 下载KMRA源代码：https://www.intel.com/content/www/us/en/developer/topic-technology/open/key-management-reference-application/overview.html

2. 生成mTLS证书和密钥以与容器共享：

   bash
   $ cd /kmra/apphsm/ca
   $ bash -c "APPHSM_HOSTNAME=apphsm ./gen_all.sh"
   

   注意：APPHSM_HOSTNAME必须与AppHSM容器名称匹配

3. 创建自定义桥接网络：

   bash
   $ docker network create kmra-net
   

PCCS容器部署

准备证书和配置文件

在主机上执行以下命令：

bash
$ cd /kmaas/containers/pccs
$ mkdir -p certs && rm -rf certs/*
$ cd certs
$ bash ../scripts/pccs_generate_certificates.sh

订阅的主键将用于后续步骤，可在以下网站随时获取：https://api.portal.trustedservices.intel.com/provisioning-certification

设置环境变量并生成配置文件

在主机上导出PCCS_*环境变量：

bash
$ export PCCS_ADMIN_PASS="example-admin-pass"
$ export PCCS_API_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

运行配置生成脚本：

bash
$ bash ../scripts/pccs_generate_config.sh

说明：PCCS_API_KEY是必填环境变量，其他为可选，可选变量将使用默认值。

运行PCCS容器

bash
$ cd /kmra/containers/pccs
$ docker run --user "65333:65333" --rm --network kmra-net --name pccs -it --cpu-shares 512 --pids-limit 100 --memory=512m --security-opt=no-new-privileges -v `pwd`/certs/private.pem:/opt/intel/pccs/ssl_key/private.pem -v `pwd`/certs/file.crt:/opt/intel/pccs/ssl_key/file.crt -v `pwd`/config/pccs.config:/opt/intel/pccs/config/default.json --read-only --tmpfs /opt/intel/pccs/logs/ --tmpfs /tmp --cap-drop=all pccs

构建参数

• USER - 容器内用户名（默认：kmra）
• UID - 上述用户的UID（默认：1000）

环境变量

• PCCS_API_KEY - 订阅中的"primary key"值，可从https://api.portal.trustedservices.intel.com/provisioning-certification获取
• PCCS_ADMIN_PASS - PCCS管理员密码（本演示未使用，但可提供值）
• PCCS_USER_PASS - PCCS用户密码（本演示未使用，但可提供值）
• http_proxy, https_proxy - 如在企业代理后使用PCCS需设置，格式：-e https_proxy="http://proxy:port"（需在镜像构建时设置）
• PCCS_PORT - PCCS服务监听端口（默认：8081）
• PCCS_LOCAL_ONLY - 是否仅监听本地网络接口的标志（Y/N，默认：N）

AppHSM容器部署

基本运行命令

从主目录执行：

bash
$ cd /kmra
docker run -it --rm --cpu-shares 512 --pids-limit 100 --memory=2048m --security-opt=no-new-privileges --read-only --tmpfs /var/lib/softhsm/tokens --tmpfs /tmp -v `pwd`/containers/apphsm/sgx_default_qcnl.conf:/etc/sgx_default_qcnl.conf:ro -v `pwd`/apphsm/ca/:/opt/intel/ca:ro --name apphsm --env no_proxy="pccs" --cap-drop=all --network kmra-net apphsm:latest

[可选] 使用自定义配置

1. 生成自定义密钥和证书：

   bash
   $ cd containers/apphsm/custom_config
   $ bash ./gen_key_cert.sh
   

2. 编辑配置文件apphsm.conf，添加所需密钥。token_name字段对每个密钥必须唯一，key_name和certificate_file字段必须与custom_config目录中的密钥和证书文件名对应。

3. 挂载自定义配置目录：

   bash
   $ cd kmra/
   $ docker run -it --rm --cpu-shares 512 --pids-limit 100 --memory=2048m --security-opt=no-new-privileges --read-only --tmpfs /var/lib/softhsm/tokens --tmpfs /tmp -v `pwd`/containers/apphsm/sgx_default_qcnl.conf:/etc/sgx_default_qcnl.conf:ro -v `pwd`/apphsm/ca/:/opt/intel/ca:ro -v `pwd`/containers/apphsm/custom_config:/opt/apphsm_config:ro --name apphsm --env no_proxy="pccs" --cap-drop=all --network kmra-net apphsm:latest
   

构建参数

• DCAP_VERSION - 默认：1.15
• DCAP_LIB_VERSION - 默认：1.15.100.3
• SGX_LIB_VERSION - 默认：2.18.101.1
• USER - 容器内用户名（默认：kmra）
• UID - 上述用户的UID（默认：1000）

环境变量

• APPHSM_PORT - AppHSM服务监听端口（默认：5000）
• no_proxy - 不使用代理的主机名、IP地址或子网列表
• APPHSM_KEY_IN_TOKEN_NAME - softhsm中AppHSM的密钥标签（默认：key_1）
• APPHSM_TOKEN_NAME - softhsm中AppHSM的令牌标签（默认：token_1）
• TEST_CTK_LOADKEY_CERT_USER_ID - 客户端证书"OU"字段中显示的客户端名称，需在apphsm.conf的"clients"部分定义（默认：ctk_loadkey_user_id_01234）
• TEST_UNIQUE_UID - AppHSM端apphsm.conf中定义的密钥唯一ID，客户端可通过ctk_loadkey请求此密钥
• DEFAULT_USER_PIN - softhsm用户PIN，长度4-16字符（默认：1234）
• DEFAULT_SO_PIN - softhsm安全管理员PIN，长度4-16字符（默认：***）
• APPHSM_CUSTOM_CONFIG_DIR - 容器内自定义配置位置（默认：/opt/apphsm_config）

PCCS配置文件（containers/apphsm/sgx_default_qcnl.conf）

• PCCS_URL - PCCS服务的有效URL（默认：<[***]>）
• USE_SECURE_CERT - 是否接受PCCS URL的不安全HTTPS证书，设为FALSE接受（默认：FALSE）

gen_key_cert.sh脚本参数

• DEFAULT_KEY_NAME - 生成的密钥文件名
• DEFAULT_CERTIFICATE_NAME - 生成的证书文件名

Ctk_loadkey容器部署

运行命令

从主目录执行：

bash
$ cd /kmra
docker run -it --rm --device /dev/sgx_enclave --cpu-shares 512 --pids-limit 100 --memory=2048m --security-opt=no-new-privileges --device /dev/sgx_provision --cap-drop=all --env PCCS_HOSTNAME=pccs --env APPHSM_HOSTNAME=apphsm --env no_proxy="apphsm,pccs" --name ctk_loadkey --network kmra-net --read-only --tmpfs /opt/intel/cryptoapitoolkit/tokens --tmpfs /tmp -v `pwd`/containers/ctk/sgx_default_qcnl.conf:/etc/sgx_default_qcnl.conf:ro -v `pwd`/containers/nginx/p11_proxy_tls.psk:/etc/p11_proxy_tls.psk:ro -v `pwd`/apphsm/ca/:/opt/intel/ca:ro --user kmra:$(getent group sgx_prv | cut -d: -f3) ctk_loadkey:latest

注意：在某些主机系统（如Ubuntu 22）上，可能需要添加额外参数以在容器内挂载/dev/sgx_***：

bash
--group-add $(getent group sgx | cut -d: -f3)

可通过以下命令检查是否需要sgx组：

bash
$ ls -lg /dev/sgx_enclave
crw-rw---- 1 sgx 10, 125 Dec 13 10:54 /dev/sgx_enclave

构建参数

• DCAP_VERSION - 默认：1.15
• DCAP_LIB_VERSION - 默认：1.15.100.3
• SGX_VERSION - 默认：2.18.1
• SGX_LIB_VERSION - 默认：2.18.101.1
• USER - 容器内用户名（默认：kmra）
• UID - 上述用户的UID（默认：1000）

环境变量

• APPHSM_HOSTNAME - AppHSM服务所在主机（默认：localhost），通常应设为AppHSM容器名称"apphsm"
• APPHSM_PORT - AppHSM服务监听端口（默认：5000）
• NGINX_HOSTNAME - nginx监听的主机名（默认：0.0.0.0）
• NGINX_PORT - nginx监听端口（默认：8082）
• no_proxy - 不使用代理的主机名、IP地址或子网列表
• CLIENT_TOKEN - ctk_loadkey存储nginx证书私钥的令牌标签（默认：client_token）
• CLIENT_KEY_LABEL - nginx用于查找密钥的标签（默认：client_key_priv）
• TEST_UNIQUE_UID - AppHSM端apphsm.conf中定义的密钥唯一ID，客户端可通过ctk_loadkey请求此密钥
• DEFAULT_USER_PIN - ***-Api-Toolkit用户PIN，长度4-16字符（默认：1234）
• DEFAULT_SO_PIN - -Api-Toolkit安全管理员PIN，长度4-16字符（默认：）
• DEFAULT_CLIENT_TOKEN_ID - 密钥对ID，十六进制格式，用于pkcs11-tool将证书写入令牌
• KEEP_TOKENS - 启动时不清理*** api toolkit令牌

PCCS配置文件（containers/ctk/sgx_default_qcnl.conf）

• PCCS_URL - PCCS服务的有效URL（默认：<[***]>）
• USE_SECURE_CERT - 是否接受PCCS URL的不安全HTTPS证书，设为FALSE接受（默认：FALSE）

NGINX容器部署

运行命令

bash
$ cd /kmra
docker run -it --rm --cpu-shares 512 --pids-limit 100 --memory=2048m --read-only --tmpfs /tmp --env PKCS11_PROXY_SOCKET=tls://<ctk_loadkey容器IP地址>:<端口号> --env no_proxy="ctk_loadkey" -v `pwd`/containers/nginx/p11_proxy_tls.psk:/etc/p11_proxy_tls.psk:ro --name nginx --network kmra-net -p 8082:8082 nginx:latest

环境变量

• PKCS11_PROXY_SOCKET - ctk_loadkey容器的IP地址和pkcs11-proxy暴露端口
• NGINX_HOSTNAME - nginx监听的主机名（默认：0.0.0.0）
• NGINX_PORT - nginx监听端口（默认：8082）
• CLIENT_TOKEN - 包含nginx私钥的令牌名称（默认：client_token）
• CLIENT_KEY_LABEL - nginx用于查找密钥的标签（默认：client_key_priv）
• DEFAULT_USER_PIN - ***-Api-Toolkit用户PIN，长度4-16字符（默认：1234）

备注：TLS预共享密钥文件格式为key_name:16字节十六进制密钥，该密钥对ctk和nginx容器通用，示例文件见源代码中的p11_proxy_tls.psk。

常见问题

1. 任务 '[create_e***y_token_in_hsm: Create token ...]' 失败

错误日志：

TASK [create_empty_token_in_hsm : Create token with name 'client_token'] *
fatal: [localhost]: FAILED! => {"changed": true, "cmd": ["softhsm2-util", "--module", "/usr/local/lib/libp11sgx.so.0.0.0", "--init-token", "--free", "--label", "client_token", "--pin", "1234", "--so-pin", "12345678"], ... Could not initialize the PKCS#11 library/module: /usr/local/lib/libp11sgx.so.0.0.0\nERROR: Please check log files for additional information.", "stderr_lines": ["[get_driver_type /home/sgx/jenkins/ubuntuServer2004-release-build-trunk-213.3/build_target/PROD/label/Builder-UbuntuSrv20/label_exp/ubuntu64/linux-trunk-opensource/psw/urts/linux/edmm_utility.cpp:111] Failed to open Intel SGX device.", "ERROR: Could not initialize the PKCS#11 library/module: /usr/local/lib/libp11sgx.so.0.0.0", "ERROR: Please check log files for additional information."], "stdout": "", "stdout_lines": []}

根本原因：SGX服务共享存在问题（例如，运行容器时未传递--device /dev/sgx/enclave参数）

2. 任务 [install_ctk_loadkey: Copy ca cert and ctk_loadkey keys ...] 失败

错误日志：

TASK [install_ctk_loadkey : Copy ca cert and ctk_loadkey keys to /opt/intel/ctk_loadkey] 
changed: [localhost] => (item=ctk_loadkey.crt)
fatal: [localhost]: FAILED! => {"msg": "an error occurred while trying to read the file '/opt/intel/ca/ctk_loadkey.key': [Errno 13] Permission denied: b'/opt/intel/ca/ctk_loadkey.key'. [Errno 13] Permission denied: b'/opt/intel/ca/ctk_loadkey.key'"}

根本原因：容器内用户ID与共享证书/密钥文件的所有者不匹配。确保ctk_loadkey的证书/密钥文件对容器内的'kmra'用户可访问。

3. 任务 [provision_ctk_with_key_from_apphsm ...] 中***未授权运行

错误日志：

TASK [provision_ctk_with_key_from_apphsm : Provision token client_token with key client_key_priv from AppHSM] 
fatal: [localhost]: FAILED! => {"changed": true, "cmd": "cd /opt/intel/ctk_loadkey; https_proxy=\"\" ./ctk_loadkey -t client_token -p 1234 -u unique_id_1234 -P 5000 -H silpixa00400537", "delta": "0:00:00.478