andiolsi/olsica

olsica 镜像文档

镜像概述和主要用途

olsica是一个证书授权容器，设计用于Kubernetes环境中的initContainer，旨在通过配置的CA证书和密钥生成客户端证书相关文件。其核心功能是接收CA证书和密钥（通常通过ConfigMap提供），生成客户端CSR、密钥和证书，并将这些文件写入挂载的emptyDir卷。此外，该镜像还支持生成Java密钥库/信任库及PKCS8格式密钥，可用于管理实际CA或作为证书生成流程的参考工具。

注意：该镜像未经过过度测试，部分功能可能存在问题。

核心功能和特性

• 证书生成：基于提供的CA证书和密钥，自动生成客户端CSR、密钥和证书
• 算法支持：支持RSA和EC两种密钥生成算法
• 证书定制：可配置证书有效期、主题、SubjectAltNames等内容
• 格式转换：支持生成PKCS8格式密钥
• Java支持：可生成Java KeyStore和TrustStore
• 权限控制：可自定义生成文件的所有者（UID/GID）和权限模式
• 灵活配置：通过环境变量控制源文件路径、目标文件路径及各类参数

使用场景和适用范围

• Kubernetes initContainer：作为etcd等服务部署的初始化容器，自动生成客户端证书
• 证书自动化：在需要动态生成客户端证书的场景中使用
• CA管理参考：作为CA证书管理和客户端证书生成流程的参考实现

使用方法和配置说明

环境变量配置

调试模式

• OLSICA_DEBUG：启用调试模式，默认不启用

客户端名称和主题

• OLSICA_CLIENT_NAME：客户端名称，用于自动生成主题（默认主题为/CN=${OLSICA_CLIENT_NAME}/）
• OLSICA_CLIENT_SUBJECT：自定义客户端证书主题，默认值为/CN=${OLSICA_CLIENT_NAME}/

证书有效期

• OLSICA_CERTIFICATE_VALIDITY_DAYS：证书有效期天数，默认值为7300天

密钥生成算法

支持RSA和EC两种算法：

• OLSICA_KEY_ALGORITHM：密钥算法，可选值为RSA或EC，默认值为EC
• OLSICA_ECPARAM：EC算法参数，默认值为prime256v1（仅当算法为EC时有效）
• OLSICA_RSA_BITS：RSA密钥位数，默认值为4096（仅当算法为RSA时有效）

源文件和目录

• OLSICA_SOURCE_DIRECTORY：CA文件源目录，默认值为/certificates_ca
• OLSICA_SOURCE_CA_CERTIFICATE_FILENAME：CA证书文件名，默认值为ca.crt
• OLSICA_SOURCE_CA_KEY_FILENAME：CA密钥文件名，默认值为ca.key
• OLSICA_SOURCE_CA_CONFIG_PATH：CA配置文件路径，默认未设置
• OLSICA_SOURCE_CA_SERIAL_PATH：CA序列号文件路径，默认值为/tmp/ca.srl
• OLSICA_SOURCE_CA_DATABASE_PATH：CA数据库文件路径，默认值为/tmp/certificate.db
• OLSICA_SOURCE_CA_SERIAL_MODE：CA序列号模式，默认值为rand_serial
• OLSICA_SOURCE_CA_DIGEST：CA摘要算法，默认值为sha256

目标文件权限

• OLSICA_TARGET_UID：目标文件所有者UID，默认值为1000
• OLSICA_TARGET_GID：目标文件所有者GID，默认值为0
• OLSICA_TARGET_MODE_CERTS：证书文件权限模式，默认值为644
• OLSICA_TARGET_MODE_KEY：密钥文件权限模式，默认值为600

证书内容

• OLSICA_CLIENT_SUBJECTALTNAMES：客户端证书SubjectAltNames，默认未设置（格式示例：foo.com,*.foo.com,127.0.0.1）

目标文件和目录

• OLSICA_TARGET_DIRECTORY：证书输出目录，默认值为/certificates_out
• OLSICA_TARGET_CA_CERTIFICATE_FILENAME：输出CA证书文件名，默认值为ca.crt
• OLSICA_TARGET_CLIENT_KEY_FILENAME：输出客户端密钥文件名，默认值为client.key
• OLSICA_TARGET_CLIENT_CSR_FILENAME：输出客户端CSR文件名，默认值为client.csr
• OLSICA_TARGET_CLIENT_CERTIFICATE_FILENAME：输出客户端证书文件名，默认值为client.crt
• OLSICA_TARGET_CLIENT_PKCS12：PKCS12文件名称，默认值为client.p12
• OLSICA_TARGET_CLIENT_PKCS12_PASSWORD：PKCS12文件密码，默认值为client
• OLSICA_TARGET_CLIENT_KEYSTORE_FILENAME：Java KeyStore文件名，默认未设置（设置后生成KeyStore）
• OLSICA_TARGET_CLIENT_KEYSTORE_PASSWORD：Java KeyStore密码，默认值为client
• OLSICA_TARGET_CLIENT_TRUSTSTORE_FILENAME：Java TrustStore文件名，默认未设置（设置后生成TrustStore）
• OLSICA_TARGET_CLIENT_TRUSTSTORE_PASSWORD：Java TrustStore密码，默认值为client
• OLSICA_TARGET_CLIENT_PKCS8_FILENAME：PKCS8格式密钥文件名，默认未设置（设置后生成PKCS8密钥）

Docker运行示例

1. 准备CA文件

bash
# 创建CA目录和输出目录
mkdir /tmp/certificates_ca
mkdir /tmp/certificates_out

# 生成CA密钥（EC算法）
openssl ecparam -out /tmp/certificates_ca/ca.key -name prime256v1 -genkey

# 生成自签名CA证书
openssl req -new -days 365 -nodes -x509 -key /tmp/certificates_ca/ca.key -out /tmp/certificates_ca/ca.crt -subj "/CN=olsica/"

2. 运行容器生成客户端证书

bash
docker run -it --rm \
  -v /tmp/certificates_ca:/certificates_ca \
  -v /tmp/certificates_out:/certificates_out \
  -e OLSICA_CLIENT_NAME="test" \
  -e OLSICA_KEY_ALGORITHM=RSA \
  -e OLSICA_CLIENT_SUBJECTALTNAMES="foo.com,*.foo.com,127.0.0.1" \
  -t andiolsi/olsica:latest

运行后，生成的证书文件将保存在/tmp/certificates_out目录中，包括客户端密钥、CSR、证书等文件。