class SecureRandom

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

功能:用于生成加密安全的伪随机数。

Random 相比,主要有三个方面不同:

  • 随机数种子: Random 使用系统时钟作为默认的种子,时间戳一样,结果就相同;SecureRandom 使用操作系统或者硬件提供的随机数种子,生成的是真随机数。

  • 随机数生成: Random 使用了梅森旋转伪随机生成器;SecureRandom 则使用了 openssl 库提供的 MD5 等随机算法,使用熵源生成真随机数;如果硬件支持,还可以使用硬件随机数生成器来生成安全性更强的随机数。

  • 安全性: Random 不能用于加密安全的应用或者隐私数据的保护,可以使用 SecureRandom

init(Bool)

public init(priv!: Bool = false)

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

参数:

  • priv!: Bool - 设置为 true 表示使用加密安全伪随机生成器。

func nextBool()

public func nextBool(): Bool

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

返回值:

  • Bool - 一个随机的 Bool 类型实例。

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextBytes(Int32)

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

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

参数:

  • length: Int32 - 要生成的随机字节数组的长度。

返回值:

异常:

func nextFloat16()

public func nextFloat16(): Float16

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextFloat32()

public func nextFloat32(): Float32

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextFloat64()

public func nextFloat64(): Float64

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextGaussianFloat16(Float16, Float16)

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

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

参数:

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextGaussianFloat32(Float32, Float32)

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

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

参数:

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextGaussianFloat64(Float64, Float64)

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

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

参数:

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextInt16()

public func nextInt16(): Int16

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextInt32()

public func nextInt32(): Int32

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextInt16(Int16)

public func nextInt16(max: Int16): Int16

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

参数:

  • max: Int16 - 区间最大值。

返回值:

异常:

func nextInt32(Int32)

public func nextInt32(max: Int32): Int32

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

参数:

  • max: Int32 - 区间最大值。

返回值:

异常:

func nextInt64()

public func nextInt64(): Int64

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextInt64(Int64)

public func nextInt64(max: Int64): Int64

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

参数:

  • max: Int64 - 区间最大值。

返回值:

异常:

func nextInt8()

public func nextInt8(): Int8

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

返回值:

  • Int8 - 一个 Int8 类型的随机数。

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextInt8(Int8)

public func nextInt8(max: Int8): Int8

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

参数:

  • max: Int8 - 区间最大值。

返回值:

  • Int8 - 一个 Int8 类型的随机数。

异常:

func nextUInt16()

public func nextUInt16(): UInt16

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextUInt16(UInt16)

public func nextUInt16(max: UInt16): UInt16

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

参数:

  • max: UInt16 - 区间最大值。

返回值:

异常:

func nextUInt32()

public func nextUInt32(): UInt32

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextUInt32(UInt32)

public func nextUInt32(max: UInt32): UInt32

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

参数:

  • max: UInt32 - 区间最大值。

返回值:

异常:

func nextUInt64()

public func nextUInt64(): UInt64

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextUInt64(UInt64)

public func nextUInt64(max: UInt64): UInt64

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

参数:

  • max: UInt64 - 区间最大值。

返回值:

异常:

func nextUInt8()

public func nextUInt8(): UInt8

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

返回值:

异常:

  • SecureRandomException - 当生成器不能正确生成随机数或生成随机数失败时,抛出异常。

func nextUInt8(UInt8)

public func nextUInt8(max: UInt8): UInt8

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

参数:

  • max: UInt8 - 区间最大值。

返回值:

异常:

class SM4

public class SM4 <: BlockCipher {
    public init(
        optMode: OperationMode,
        key: Array<Byte>,
        iv!: Array<Byte> = Array<Byte>(),
        paddingMode!: PaddingMode = PaddingMode.PKCS7Padding,
        aad!: Array<Byte> = Array<Byte>(),
        tagSize!: Int64 = SM4_GCM_TAG_SIZE
    )
}

功能:提供国密SM4对称加解密。

目前 SM4 支持 的加解密工作模式由 OperationMode 定义,目前支持 ECB、CBC、OFB、CFB、CTR、GCM模式。

不同的工作模式可能对应的加解密实现不同,安全性也不同。需要选择和场景适配的加解密工作模式。

iv 初始化向量在 GCM 模式下可以设置推荐长度是12字节,在 CBC、OFB、CFB、CTR 模式下 iv 长度是16字节,在 ECB 模式下 iv 可以不设置。

paddingMode 填充模式模式由 PaddingMode 定义, 目前支持 NoPadding 非填充、PKCS7Padding PKCS7填充。默认是 PKCS7 填充。

paddingMode 设置对ECB 和 CBC 有效,ECB 和 CBC 分组加解密需要分组长度等于 blockSize。会根据填充模式进行填充。 paddingMode 设置对 OFB、CFB、CTR、GCM 工作模式无效,这些工作模式均无需填充。

如果选择 NoPadding 模式,即不填充。则在 ECB 和 CBC 工作模式下用户需要对数据是否可以分组负责,如果数据不能分组,或者最后一组数据长度不足 blockSize 则会报错。

aad 附加数据,仅在 GCM 模式下使用,由用户填充,参与摘要计算,默认为空。

tagSize 设置摘要长度,仅在 GCM 模式下使用,默认值为 SM4_GCM_TAG_SIZE 16字节,最小不能低于12字节,最大不能超过16字节。

如果是 GCM 工作模式。加密结果的后 tagSize 字节是摘要数据。

注意:

GCM 模式需要 OpenSSL 3.2 或者以上版本。

父类型:

init(OperationMode, Array<Byte>, Array<Byte>, PaddingMode, Array<Byte>, Int64)

    public init(
        optMode: OperationMode,
        key: Array<Byte>,
        iv!: Array<Byte> = Array<Byte>(),
        paddingMode!: PaddingMode = PaddingMode.PKCS7Padding,
        aad!: Array<Byte> = Array<Byte>(),
        tagSize!: Int64 = SM4_GCM_TAG_SIZE
    )

功能:创建 SM4 实例,可指定在不同工作模式下参数。

参数:

异常:

prop aad

public prop aad: Array<Byte> 

功能:附加数据。

类型:Array<Byte>

prop blockSize

public prop blockSize: Int64

功能:分组长度,单位字节。

类型:Int64

prop keySize

public prop keySize: Int64 

功能:密钥长度。

类型:Int64

prop key

public prop key: Array<Byte> 

功能:密钥。

类型:Array<Byte>

prop optMode

public prop optMode: OperationMode

功能:工作模式。

类型:OperationMode

prop paddingMode

public prop paddingMode: PaddingMode

功能:填充模式。

类型:PaddingMode

prop iv

public prop iv: Array<Byte>

功能:初始化向量。

类型:Array<Byte>

prop ivSize

public prop ivSize: Int64

功能:初始化向量长度。

类型:Int64

prop tagSize

public prop tagSize: Int64

功能:摘要长度。

类型:Int64

func encrypt(Array<Byte>)

public func encrypt(input: Array<Byte>): Array<Byte>

功能:加密一段数据数据。

参数:

返回值:

异常:

func encrypt(InputStream, OutputStream)

public func encrypt(input: InputStream, output: OutputStream)

功能:对输入流进行加密,一般如果数据过大无法一次对其加密,可以对数据流进行加密。

参数:

异常:

func decrypt(Array<Byte>)

public func decrypt(input: Array<Byte>): Array<Byte>

功能:解密一段数据数据。

参数:

返回值:

异常:

func decrypt(InputStream, OutputStream)

public func decrypt(input: InputStream, output: OutputStream)

功能:对输入流进行解密,一般如果数据过大无法一次对其解密,可以对数据流进行解密。

参数:

异常: