intel/apphsm

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

KMRA（密钥管理参考应用）是一款概念验证软件，旨在演示SGX非对称/对称密钥能力与第三方硬件安全模块（HSM）的集成。源代码和文档请访问：[***]

前提条件

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

标签

• 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源代码：[***]

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（Provisioning Certification Certificate Service）

准备证书和配置文件

在主机上准备PCCS容器的证书和配置文件：

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

订阅的主密钥将用于后续步骤，可在以下网站随时获取：[***]

设置环境变量

在生成配置文件前，通过export设置PCCS_*环境变量（在主机上）：

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

生成配置文件

运行pccs_generate_config.sh脚本（在主机上）：

bash
$ bash ../scripts/pccs_generate_config.sh

说明：PCCS_API_KEY是必需的环境变量，其他为可选，未设置时将使用默认值。

运行PCCS容器

挂载生成的证书和配置文件运行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：订阅的“主密钥”值，来自网站：<[***]>
• PCCS_ADMIN_PASS：PCCS管理员密码（本演示未使用，但可提供值）
• PCCS_USER_PASS：PCCS用户密码（本演示未使用，但可提供值）
• http_proxy, https_proxy：如在企业代理后使用PCCS，需设置（镜像构建时设置）
• PCCS_PORT：PCCS服务监听端口（默认：8081）
• PCCS_LOCAL_ONLY：是否仅监听本地网络接口（Y/N，默认：N）

AppHSM

运行AppHSM容器

从主目录运行AppHSM容器：

bash
$ cd /kmra

基础运行命令：

bash
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

[可选] 使用自定义配置运行AppHSM

1. 生成自定义密钥和证书（通过脚本）：

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

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

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/TRUE，默认：FALSE）

gen_key_cert.sh脚本参数

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

Ctk_loadkey

运行Ctk_loadkey容器

从主目录运行Ctk_loadkey容器：

bash
$ cd /kmra

基础运行命令：

bash
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_enclave：

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：nginx证书私钥存储的令牌标签（默认：client_token）
• CLIENT_KEY_LABEL：nginx用于查找密钥的标签（默认：client_key_priv）
• TEST_UNIQUE_UID：AppHSM端apphsm.conf中定义的密钥唯一ID
• 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/TRUE，默认：FALSE）

NGINX

运行NGINX容器

从主目录运行NGINX容器：

bash
$ cd /kmra

基础运行命令：

bash
docker run -it --rm --cpu-shares 512 --pids-limit 100 --memory=2048m --read-only --tmpfs /tmp --env PKCS11_PROXY_SOCKET=tls://<ctk_loakey container IP address>:<port_number> --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_empty_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.
  

• 根本原因：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]  
  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'"}
  

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

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", ... "[error_driver2api sgx_enclave_common.cpp:247] Enclave not authorized to run, .e.g. provisioning enclave hosted in app without access rights to /dev/sgx_provision. You need add the user id to group sgx_prv or run the app as root."
  

• 根本原因：容器内“sgx_prv”组ID与主机上的组ID不匹配。确保两者组ID一致。

4. 任务 [provision_ctk_with_key_from_app