crypto 包

介绍

crypto 包提供生成安全随机数功能。

使用本包需要外部依赖 OpenSSL 3 的 crypto 动态库文件，故使用前需安装相关工具：

对于 Linux 操作系统，可参考以下方式：
- 如果系统的包管理工具支持安装 OpenSSL 3 开发工具包，可通过这个方式安装，并确保系统安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，例如 Ubuntu 22.04 系统上可使用 sudo apt install libssl-dev 命令安装 libssl-dev 工具包；
- 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.so 和 libcrypto.so.3 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件:
  - 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
  - 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 LD_LIBRARY_PATH 以及 LIBRARY_PATH 中。
对于 Windows 操作系统，可按照以下步骤：
- 自行下载 OpenSSL 3.x.x 源码编译安装 x64 架构软件包或者自行下载安装第三方预编译的供开发人员使用的 OpenSSL 3.x.x 软件包；
- 确保安装目录下含有 libcrypto.dll.a(或 libcrypto.lib)、libcrypto-3-x64.dll 这两个库文件；
- 将 libcrypto.dll.a(或 libcrypto.lib) 所在的目录路径设置到环境变量 LIBRARY_PATH 中，将 libcrypto-3-x64.dll 所在的目录路径设置到环境变量 PATH 中。
对于 macOS 操作系统，可参考以下方式：
- 使用 brew install openssl@3 安装，并确保系统安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件；
- 如果无法通过上面的方式安装，可自行下载 OpenSSL 3.x.x 源码编译安装软件包，并确保安装目录下含有 libcrypto.dylib 和 libcrypto.3.dylib 这两个动态库文件，然后可选择下面任意一种方式来保证系统链接器可以找到这些文件:
  - 在系统未安装 OpenSSL 的场景，安装时选择直接安装到系统路径下；
  - 安装在自定义目录的场景，将这些文件所在目录设置到环境变量 DYLD_LIBRARY_PATH 以及 LIBRARY_PATH 中。

如果未安装OpenSSL 3软件包或者安装低版本的软件包，程序可能无法使用并抛出相关异常 SecureRandomException：Can not load openssl library or function xxx.。

主要接口

class SecureRandomException

public class SecureRandomException <: Exception {
    public init()
    public init(message: String)
}

crypto 包的异常类。

init

public init()

功能：创建默认的 SecureRandomException 实例，异常提示消息为空。

init

public init(message: String)

功能：根据异常提示消息创建 SecureRandomException 实例。

参数：

message：异常提示字符串

class SecureRandom

public class SecureRandom {
    public init(priv!: Bool = false)
}

该类用于生成加密安全的伪随机数。

和 std.random.Random 相比，主要有三个方面不同：

随机数种子： Random 使用系统时钟作为默认的种子，时间戳一样，结果就相同，SecureRandom 使用操作系统或者硬件提供的随机数种子，生成的几乎是真随机数。
随机数生成： Random 使用了梅森旋转伪随机生成器，SecureRandom 则使用了 openssl 库提供的 MD5 等随机算法，使用熵源生成真随机数。如果硬件支持，还可以使用硬件随机数生成器来生成安全性更强的随机数。
安全性： Random 不能用于加密安全的应用或者隐私数据的保护。

init

public init(priv!: Bool = false)

功能：创建 SecureRandom 实例，可指定是否使用更加安全的加密安全伪随机生成器，加密安全伪随机生成器可用于会话密钥和证书私钥等加密场景。

参数：

priv：为 true 表示使用加密安全伪随机生成器

func nextBytes

public func nextBytes(length: Int32): Array<Byte>

功能：获取一个指定长度的随机字节的数组。

参数：

length：要生成的随机字节数组的长度

返回值：一个随机字节数组

异常：

异常 IllegalArgumentException：当参数 length 小于等于 0，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextBool

public func nextBool(): Bool

功能：获取一个随机的 Bool 类型实例。

返回值：一个随机的 Bool 类型实例

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt8

public func nextUInt8(): UInt8

功能：获取一个 UInt8 类型的随机数。

返回值：一个 UInt8 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt16

public func nextUInt16(): UInt16

功能：获取一个 UInt16 类型的随机数。

返回值：一个 UInt16 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt32

public func nextUInt32(): UInt32

功能：获取一个 UInt32 类型的随机数。

返回值：一个 UInt32 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt64

public func nextUInt64(): UInt64

功能：获取一个 UInt64 类型的随机数。

返回值：一个 UInt64 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt8

public func nextInt8(): Int8

功能：获取一个 Int8 类型的随机数。

返回值：一个 Int8 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt16

public func nextInt16(): Int16

功能：获取一个 Int16 类型的随机数。

返回值：一个 Int16 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt32

public func nextInt32(): Int32

功能：获取一个 Int32 类型的随机数。

返回值：一个 Int32 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt64

public func nextInt64(): Int64

功能：获取一个 Int64 类型的随机数。

返回值：一个 Int64 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt8

public func nextUInt8(max: UInt8): UInt8

功能：获取一个 UInt8 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 UInt8 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为 0 时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt16

public func nextUInt16(max: UInt16): UInt16

功能：获取一个 UInt16 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 UInt16 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为 0 时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt32

public func nextUInt32(max: UInt32): UInt32

功能：获取一个 UInt32 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 UInt32 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为 0 时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextUInt64

public func nextUInt64(max: UInt64): UInt64

功能：获取一个 UInt64 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 UInt64 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为 0 时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt8

public func nextInt8(max: Int8): Int8

功能：获取一个 Int8 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 Int8 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为非正数时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt16

public func nextInt16(max: Int16): Int16

功能：获取一个 Int16 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 Int16 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为非正数时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt32

public func nextInt32(max: Int32): Int32

功能：获取一个 Int32 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 Int32 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为非正数时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextInt64

public func nextInt64(max: Int64): Int64

功能：获取一个 Int64 类型且在区间 [0, max) 内的随机数。

参数：

max：区间最大值

返回值：一个 Int64 类型的随机数

异常：

异常 IllegalArgumentException：当 max 为非正数时，抛出异常
异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextFloat16

public func nextFloat16(): Float16

功能：获取一个 Float16 类型且在区间 [0.0, 1.0) 内的随机数。

返回值：一个 Float16 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextFloat32

public func nextFloat32(): Float32

功能：获取一个 Float32 类型且在区间 [0.0, 1.0) 内的随机数。

返回值：一个 Float32 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextFloat64

public func nextFloat64(): Float64

功能：获取一个 Float64 类型且在区间 [0.0, 1.0) 内的随机数。

返回值：一个 Float64 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextGaussianFloat16

public func nextGaussianFloat16(mean!: Float16 = 0.0, sigma!: Float16 = 1.0): Float16

功能：默认获取一个 Float16 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值,可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。

参数：

mean：均值
sigma：标准差

返回值：一个 Float16 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextGaussianFloat32

public func nextGaussianFloat32(mean!: Float32 = 0.0, sigma!: Float32 = 1.0): Float32

功能：默认获取一个 Float32 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值，可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。

参数：

mean：均值
sigma：标准差

返回值：一个 Float32 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

func nextGaussianFloat64

public func nextGaussianFloat64(mean!: Float64 = 0.0, sigma!: Float64 = 1.0): Float64

功能：默认获取一个 Float64 类型且符合均值为 0.0 标准差为 1.0 的高斯分布的随机数，其中均值是期望值,可解释为位置参数，决定了分布的位置，标准差可解释为尺度参数，决定了分布的幅度。

参数：

mean：均值
sigma：标准差

返回值：一个 Float64 类型的随机数

异常：

异常 SecureRandomException：当生成器不能正确生成随机数或生成随机数失败时，抛出异常

示例

SecureRandom 使用

下面是 Random 创建随机数对象的示例。

代码如下：

from crypto import crypto.*
main() {
    let r = SecureRandom()
    for (i in 0..10) {
        let flip = r.nextBool()
        println(flip)
    }
    return 0
}

可能出现的运行结果如下（true/false 的选择是随机的）：

false
true
false
false
false
true
true
false
false
true

仓颉用户手册