Utimaco HSM模拟器密钥存储与使用技术咨询

一、错误 B0680021 invalid key size 原因分析 #

importClearKey API 对导入的密钥字节长度有严格要求，必须匹配目标算法的标准密钥长度：

• AES-128：16字节
• AES-192：24字节
• AES-256：32字节
• RSA 密钥：需匹配模长对应的字节数（如2048位=256字节）

直接将密钥字符串转字节数组时，长度大概率不符合算法要求，因此报错；而SHA-256哈希后刚好生成32字节数据，符合AES-256的密钥长度要求，所以导入成功。注意：哈希后的字节数组是新的密钥，和原字符串密钥完全不同，业务场景中需确认是否符合需求。

二、合法密钥存储完整流程 #

1. 生成/准备符合长度要求的密钥
   不要用哈希凑长度（除非业务特殊需求），直接生成对应算法的标准密钥：

// 生成AES-256密钥示例
KeyGenerator keyGen = KeyGenerator.getInstance("AES");
keyGen.init(256);
SecretKey secretKey = keyGen.generateKey();
byte[] aesKeyBytes = secretKey.getEncoded();

2. 导入密钥到HSM
   调用importClearKey时，指定密钥类型为KEY_TYPE_SECRET（对称密钥），并设置必要属性（如标签、可导出标记）：

CryptoServerCXI cxi = new CryptoServerCXI();
cxi.openSession("localhost", 3001, "user", "password");

// 设置密钥属性：标签用于后续查找，EXPORTABLE标记允许导出（按需设置）
int keyFlags = CryptoServerCXI.KEY_ATTR_EXPORTABLE;
int keyHandle = cxi.importClearKey(aesKeyBytes, CryptoServerCXI.KEY_TYPE_SECRET, "my_aes_key", keyFlags);

三、密钥使用实操 #

1. 查找密钥（findKey()） #

通过导入时设置的标签或密钥ID查找密钥句柄：

// 通过标签查找对称密钥
int foundKeyHandle = cxi.findKey("my_aes_key", CryptoServerCXI.KEY_TYPE_SECRET);

2. 用密钥加密（Crypt()） #

使用找到的密钥句柄，指定加密算法模式执行加密操作，以AES/CBC/PKCS5Padding为例：

// 生成随机IV（CBC模式必需）
byte[] iv = new byte[16];
new SecureRandom().nextBytes(iv);

// 明文数据
byte[] plaintext = "需要加密的内容".getBytes(StandardCharsets.UTF_8);

// 执行加密：指定算法模式、密钥句柄、IV、明文
byte[] ciphertext = cxi.Crypt(
    CryptoServerCXI.CRYPT_MODE_ENCRYPT,
    CryptoServerCXI.ALGO_AES_CBC_PKCS5,
    foundKeyHandle,
    iv,
    plaintext
);

3. 导出密钥（exportClearKey/exportKey） #

• 仅当导入时设置了KEY_ATTR_EXPORTABLE标记，才能导出明文密钥
• 对称密钥必须使用KEY_TYPE_SECRET类型：

// 导出明文对称密钥
byte[] exportedKey = cxi.exportClearKey(foundKeyHandle, CryptoServerCXI.KEY_TYPE_SECRET);

如果未设置可导出标记，调用导出API会报错，这是HSM的安全机制，默认禁止导出密钥。

四、官方文档指引 #

详细API参数及用法可参考本地文档：

SecurityServerEvaluation-V4.60.0.0/Documentation/Crypto_APIs/CXI_Java/html/class_crypto_server_c_x_i_1_1_crypto_server_c_x_i.html
该文档包含所有方法的参数说明、返回值、错误码详情，是最权威的参考资料。

内容的提问来源于stack exchange，提问作者suri