BlueCryptor 2.0.1

BlueCryptor 2.0.1

×

由 Danny Sung、Bill Abt、Swift-at-IBM 维护。

BlueCryptor 2.0.1

  • 作者：
  • IBM & Kitura 项目作者

APIDoc Build Status - Master macOS iOS Linux Apache 2 Slack Status

BlueCryptor

Swift 跨平台加密库，源自 IDZSwiftCommonCrypto。

重要提示：此版本与先前版本不完全兼容源代码。现在有些情况下会抛出异常，而不是框架调用 fatalError()。这意味着库中的可恢复错误比以前更多。仅当指示 编程错误 或 不可恢复的系统错误 时，才会调用 fatalError()。

注意：在 macOS 和 iOS 上，BlueCryptor 使用苹果提供的 CommonCrypto 库。在 Linux 上，它使用从 OpenSSL 项目来的 libcrypto。

前提条件

Swift

  • Swift 开源 swift-5.1-RELEASE 工具链（最低必需，用于最新版本）
  • Swift 开源 swift-5.4-RELEASE 工具链（推荐）
  • Xcode版本 11.0 或更高 中包含的 Swift 工具链。

macOS

  • macOS 10.14.6（莫哈韦）或更高版本。
  • Xcode版本 11.0 或更高 使用上述工具链之一。
  • 使用Xcode 12.5或更高版本，并附带工具链（推荐）。
  • CommonCrypto由macOS提供。

iPhone操作系统

  • iPhone操作系统10.0或更高版本
  • Xcode版本 11.0 或更高 使用上述工具链之一。
  • 使用Xcode 12.5或更高版本，并附带工具链（推荐）。
  • CommonCrypto由iPhone操作系统提供。

Linux

  • Ubuntu 16.04（或16.10，但仅在16.04上测试过）和18.04。
  • 以上列出的Swift开源工具链之一。
  • OpenSSL由发行版提供。注意：支持OpenSSL的1.0.x、1.1.x和更高版本。
  • 构建时需要安装适当的libssl-dev软件包。

构建

从命令行构建Cryptor

% cd <path-to-clone>
% swift build

测试

从命令行运行所提供的Cryptor单元测试

% cd <path-to-clone>
% swift build
% swift test

入门

在你的项目中包含

Swift 包管理器

要将 BlueCryptor 包含到 Swift 包管理器项目中，请将其添加到在 Package.swift 文件中定义的 dependencies 属性中。您可以使用 majorVersion 和 minor 参数选择版本。例如

	dependencies: [
		.Package(url: "https://github.com/Kitura/BlueCryptor.git", majorVersion: <majorVersion>, minor: <minor>)
	]

Carthage

要在使用 Carthage 的项目中包含 BlueCryptor，请在您的 Cartfile 中添加一行，包含GitHub组织名、项目名称和版本。例如

	github "Kitura/BlueCryptor" ~> <majorVersion>.<minor>

CocoaPods

要在使用 CocoaPods 的项目中包含 BlueCryptor，请将 BlueCryptor 添加到您的 Podfile 文件中，例如

    platform :ios, '10.0'

    target 'MyApp' do
        use_frameworks!
        pod 'BlueCryptor'
    end

开始之前

首先，您需要导入 Cryptor 框架。这可以通过以下方式完成

import Cryptor

API

Cryptor

以下代码演示了使用可选链的 AES 单块 CBC 模式进行加密和解密。

let key = CryptoUtils.byteArray(fromHex: "2b7e151628aed2a6abf7158809cf4f3c")
let iv = CryptoUtils.byteArray(fromHex: "00000000000000000000000000000000")
let plainText = CryptoUtils.byteArray(fromHex: "6bc1bee22e409f96e93d7e117393172a")

var textToCipher = plainText
if plainText.count % Cryptor.Algorithm.aes.blockSize != 0 {
	textToCipher = CryptoUtils.zeroPad(byteArray: plainText, blockSize: Cryptor.Algorithm.aes.blockSize)
}
do {
	let cipherText = try Cryptor(operation: .encrypt, algorithm: .aes, options: .none, key: key, iv: iv).update(byteArray: textToCipher)?.final()
		
	print(CryptoUtils.hexString(from: cipherText!))
		
	let decryptedText = try Cryptor(operation: .decrypt, algorithm: .aes, options: .none, key: key, iv: iv).update(byteArray: cipherText!)?.final()

	print(CryptoUtils.hexString(from: decryptedText!))
} catch let error {
	guard let err = error as? CryptorError else {
		// Handle non-Cryptor error...
		return
	}
	// Handle Cryptor error... (See Status.swift for types of errors thrown)
}

摘要

以下示例展示了如何从和实例生成摘要。

let qbfBytes : [UInt8] = [0x54,0x68,0x65,0x20,0x71,0x75,0x69,0x63,0x6b,0x20,0x62,0x72,0x6f,0x77,0x6e,0x20,0x66,0x6f,0x78,0x20,0x6a,0x75,0x6d,0x70,0x73,0x20,0x6f,0x76,0x65,0x72,0x20,0x74,0x68,0x65,0x20,0x6c,0x61,0x7a,0x79,0x20,0x64,0x6f,0x67,0x2e]
let qbfString = "The quick brown fox jumps over the lazy dog."

// String...
let md5 = Digest(using: .md5)
md5.update(string: qfbString)
let digest = md5.final()

// NSData using optional chaining...
let qbfData = CryptoUtils.data(from: qbfBytes)
let digest = Digest(using: .md5).update(data: qbfData)?.final()

HMAC

以下展示使用字节数组作为密钥和数据的 HMAC生成。

let myKeyData = "0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"
let myData = "4869205468657265"
let key = CryptoUtils.byteArray(fromHex: myKeyData)
let data : [UInt8] = CryptoUtils.byteArray(fromHex: myData)

let hmac = HMAC(using: HMAC.Algorithm.sha256, key: key).update(byteArray: data)?.final()

密钥派生

以下示例展示了使用SHA1算法生成密钥，然后使用密码、盐、迭代次数和指定的派生命成长度来生成字符串。

let password = "password"
let salt = salt
let rounds: UInt = 2
let derivedKeyLen = 20
do {
	let key = PBKDF.deriveKey(fromPassword: password, salt: salt, prf: .sha1, rounds: rounds, derivedKeyLength: derivedKeyLen)
	let keyString = CryptoUtils.hexString(from: key)
} catch let error {
	guard let err = error as? CryptorError else {
		// Handle non-Cryptor error...
		return
	}
	// Handle Cryptor error... (See Status.swift for types of errors thrown)
}

随机字节生成

以下示例展示了生成指定长度的随机字节。

let numberOfBytes = 256*256
do {
	let randomBytes = try Random.generate(byteCount: numberOfBytes)
} catch {
  	print("Error generating random bytes")
}

实用工具

加密器还提供了一组数据操作实用函数，用于将数据从各种格式转换为

  • byteArray ([UInt8])
    • 从十六进制字符串
    • 从UTF8字符串
  • To Data
    • 从十六进制字符串
    • 从字节数组 ([UInt8])
  • To NSData
    • 从十六进制字符串
    • 从字节数组 ([UInt8])
  • To NSString
    • 从字节数组 ([UInt8])
  • To hexList (String)
    • 从字节数组 ([UInt8])

还提供了一个API来填充字节数组 ([UInt8])，使其长度为整数的字节块大小。

  • func zeroPad(byteArray: [UInt8], blockSize: Int) -> [UInt8]
  • func zeroPad(string: String, blockSize: Int) -> [UInt8]

限制

以下算法在Linux上不可用，因为它没有得到OpenSSL的支持。

  • 摘要：MD2

在任何情况下，使用不受支持的API或算法将导致Swift执行fatalError()，终止程序，应将其视为编程错误。

社区

我们喜欢讨论服务器端Swift和Kitura。加入我们的Slack，与团队见面！

许可

此库根据Apache 2.0许可。完整的许可文本可在LICENSE中找到。