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