Encryptor 项目技术文档

1. 安装指南

1.1 安装环境要求

• Ruby 版本：2.0.0 或更高版本
• OpenSSL 库：确保系统中已安装 OpenSSL 库，并且 Ruby 编译时使用了该库。

1.2 安装步骤

1. 打开终端或命令行工具。
2. 运行以下命令安装 encryptor gem：

gem install encryptor

3. 安装完成后，您可以在 Ruby 项目中使用 require 'encryptor' 来引入该库。

2. 项目的使用说明

2.1 基本使用

Encryptor 是一个简单的 Ruby 库，用于使用标准的 OpenSSL 库进行字符串加密和解密。默认情况下，Encryptor 使用 AES-256-GCM 算法进行加密。

示例代码

以下是一个基本的加密和解密示例：

require 'encryptor'

# 生成密钥和初始向量（IV）
secret_key = SecureRandom.random_bytes(32)  # 32 字节对应 AES-256
iv = SecureRandom.random_bytes(12)          # 12 字节对应 AES-256-GCM

# 加密字符串
encrypted_value = Encryptor.encrypt(value: 'some string to encrypt', key: secret_key, iv: iv)

# 解密字符串
decrypted_value = Encryptor.decrypt(value: encrypted_value, key: secret_key, iv: iv)

puts decrypted_value  # 输出: some string to encrypt

2.2 注意事项

• IV 的使用：每次加密时必须使用唯一的 IV（初始向量），IV 应与密钥和加密字符串的组合唯一对应。
• 密钥长度：密钥的长度必须与所选算法的要求一致。例如，AES-256-GCM 算法需要 32 字节的密钥。

3. 项目 API 使用文档

3.1 Encryptor.encrypt 方法

方法签名

Encryptor.encrypt(value:, key:, iv:, salt: nil, algorithm: 'aes-256-gcm', auth_data: '', insecure_mode: false, hmac_iterations: 2000, v2_gcm_iv: false)

参数说明

• value：要加密的字符串。
• key：加密密钥，长度必须与算法要求一致。
• iv：初始向量，长度必须与算法要求一致。
• salt：可选参数，用于生成唯一密钥。
• algorithm：加密算法，默认为 aes-256-gcm。
• auth_data：可选参数，用于认证数据。
• insecure_mode：是否启用不安全的模式（用于兼容旧版本）。
• hmac_iterations：用于 PKCS5 的迭代次数，默认为 2000。
• v2_gcm_iv：是否使用 v2.0.0 版本的 IV 设置（用于兼容旧版本）。

返回值

返回加密后的字符串。

3.2 Encryptor.decrypt 方法

方法签名

Encryptor.decrypt(value:, key:, iv:, salt: nil, algorithm: 'aes-256-gcm', auth_data: '', insecure_mode: false, hmac_iterations: 2000, v2_gcm_iv: false)

参数说明

• value：要解密的字符串。
• key：解密密钥，长度必须与算法要求一致。
• iv：初始向量，长度必须与算法要求一致。
• salt：可选参数，用于生成唯一密钥。
• algorithm：解密算法，默认为 aes-256-gcm。
• auth_data：可选参数，用于认证数据。
• insecure_mode：是否启用不安全的模式（用于兼容旧版本）。
• hmac_iterations：用于 PKCS5 的迭代次数，默认为 2000。
• v2_gcm_iv：是否使用 v2.0.0 版本的 IV 设置（用于兼容旧版本）。

返回值

返回解密后的字符串。

4. 项目安装方式

4.1 通过 RubyGems 安装

gem install encryptor

4.2 在 Ruby 项目中使用

在您的 Ruby 项目中，通过以下代码引入 Encryptor：

require 'encryptor'

4.3 检查安装是否成功

您可以通过以下代码检查 Encryptor 是否安装成功：

require 'encryptor'
puts Encryptor.encrypt(value: 'test', key: SecureRandom.random_bytes(32), iv: SecureRandom.random_bytes(12))

如果能够正常输出加密后的字符串，说明安装成功。

---

通过以上文档，您应该能够顺利安装和使用 Encryptor 项目进行字符串的加密和解密操作。如有任何问题，请参考项目的 GitHub Wiki 或联系项目维护者。