intel/nginx

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

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

前提条件

在主机上安装SGX内核驱动。可使用kmaas/ansible/sgx-infra-setup目录中的KMRA ansible脚本安装树外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容器部署

准备证书和配置文件（在主机上）

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

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

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

bash
$ export PCCS_ADMIN_PASS="example-admin-pass"
$ export PCCS_API_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
$ cd kmra/containers/pccs/config
$ ../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：订阅中的"主密钥"值（来自[***]
• PCCS_ADMIN_PASS：PCCS管理员密码（演示中未使用，但可提供值）
• PCCS_USER_PASS：PCCS用户密码（演示中未使用，但可提供值）
• http_proxy, https_proxy：若在企业代理后使用PCCS需设置（构建镜像时设置）
• 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：服务监听端口（默认：5000）
• no_proxy：不使用代理的主机名/IP列表
• APPHSM_KEY_IN_TOKEN_NAME：softhsm中的密钥标签（默认：key_1）
• APPHSM_TOKEN_NAME：softhsm中的令牌标签（默认：token_1）
• TEST_CTK_LOADKEY_CERT_USER_ID：客户端证书"OU"字段名称（默认：ctk_loadkey_user_id_01234）
• TEST_UNIQUE_UID：AppHSM中密钥定义的唯一ID
• 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：是否接受不安全HTTPS证书（FALSE/TRUE，默认：FALSE）

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）可能需要添加额外参数：--group-add $(getent group sgx | cut -d: -f3)。可通过ls -lg /dev/sgx_enclave检查是否需要sgx组。

构建参数

• 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_PORT：AppHSM服务端口（默认：5000）
• NGINX_HOSTNAME：NGINX监听主机（默认：0.0.0.0）
• NGINX_PORT：NGINX监听端口（默认：8082）
• no_proxy：不使用代理的主机名/IP列表
• CLIENT_TOKEN：证书私钥存储的令牌标签（默认：client_token）
• CLIENT_KEY_LABEL：NGINX使用的密钥标签（默认：client_key_priv）
• TEST_UNIQUE_UID：AppHSM中密钥定义的唯一ID
• DEFAULT_USER_PIN：***-Api-Toolkit用户PIN（4-16字符，默认：1234）
• DEFAULT_SO_PIN：-Api-Toolkit安全管理员PIN（4-16字符，默认：）
• DEFAULT_CLIENT_TOKEN_ID：密钥对ID（十六进制）
• KEEP_TOKENS：启动时不清理***-Api-Toolkit令牌

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_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

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

根本原因：容器内用户ID与共享证书/密钥文件的宿主用户ID不匹配，需确保容器内'kmra'用户可访问证书/密钥文件

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

错误日志：

[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_apphsm..] 中的SSL对等证书错误

错误日志：

rest_api_perform_request: REST API request failed 'SSL peer certificate or SSH remote key was not OK'!

根本原因：AppHSM证书中的通用名称与ctk_loadkey容器连接AppHSM使用的域名不匹配（如证书为'localhost'但应使用'apphsm'）。需重新生成证书并设置正确的APPHSM_HOSTNAME，然后重启apphsm和ctk_loadkey容器。