crypto 包

介绍

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

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

  • 对于 Linux 操作系统,可参考以下方式:
    • 如果系统的包管理工具支持安装 OpenSSL 3 开发工具包,可通过这个方式安装,并确保系统安装目录下含有 libcrypto.solibcrypto.so.3 这两个动态库文件,例如 Ubuntu 22.04 系统上可使用 sudo apt install libssl-dev 命令安装 libssl-dev 工具包;
    • 如果无法通过上面的方式安装,可自行下载 OpenSSL 3.x.x 源码编译安装软件包,并确保安装目录下含有 libcrypto.solibcrypto.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.dyliblibcrypto.3.dylib 这两个动态库文件;
    • 如果无法通过上面的方式安装,可自行下载 OpenSSL 3.x.x 源码编译安装软件包,并确保安装目录下含有 libcrypto.dyliblibcrypto.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