JOSESwift 2.4.0

JOSESwift 2.4.0

×

由 Florian Häser、Markus Bürgler、Daniel Egger 维护。

JOSESwift 2.4.0

  • 由
  • Daniel Egger、Carol Capek 和 Christoph Gigi Fuchs

JOSESwift


JOSESwift 是一个模块化和可扩展的框架，用于实现 JOSE 标准 JWS、JWE 和 JWK，使用 Swift 编写。

CircleCI

💡请注意，此 JOSE 标准实现的实现尚未完全完成。例如，目前只有有限的可用算法集合。此外，我们目前仅支持 JOSE 类型的紧凑化序列化。如果您缺少特定的功能、算法或序列化，请随时 提交拉取请求。

内容

功能

  • JWS：使用 JWS 标准对任意数据进行数字签名和验证。
  • JWE：使用 JWE 标准对任意数据进行加密和解密。
  • JWK：编解码加密密钥。

如果您缺少特定的功能、算法或序列化，请随时 提交拉取请求。

加密算法

🔏JWS 🔐JWE 🔑JWK
数字签名和消息认证码（MAC） 密钥管理 内容加密 密钥
HS256 RSA1_5✅ A128CBC-HS256✅ RSA✅
HS384 RSA-OAEP✅ A192CBC-HS384 EC✅
HS512 RSA-OAEP-256✅ A256CBC-HS512✅ 字节（oct）✅
RS256✅ A128KW✅ A128GCM
RS384✅ A192KW✅ A192GCM
RS512✅ A256KW✅ A256GCM
ES256✅ 方向性（dir）✅
ES384✅ ECDH-ES
ES512✅ ECDH-ES+A128KW
PS256✅ ECDH-ES+A192KW
PS384✅ ECDH-ES+A256KW
PS512✅ A128GCMKW
A192GCMKW
A256GCMKW
PBES2-HS256+A128KW
PBES2-HS384+A192KW
PBES2-HS512+A256KW

序列化

为了可互操作性，JOSESwift 目前支持 JWS 的紧凑序列化 和 JWE 的紧凑序列化 。

紧凑序列化 JSON 序列化
✅

压缩算法

JOSESwift 支持用于 JWE 的 DEFLATE 压缩算法。

安装

JOSESwift 很好地集成到您的 iOS 和 macOS 项目中。我们支持以下包管理器

CocoaPods

要将 JOSESwift 集成到您的 Xcode 项目中，请将其包含在您的 Podfile 中

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'JOSESwift'
end

然后运行 pod install 进行安装。有关使用 CocoaPods 的更多信息，请参阅此处。

Carthage

要将 JOSESwift 集成到您的 Xcode 项目中，请将其包含在您的 Cartfile 中。

github "airsidemobile/JOSESwift"

然后运行 carthage update 命令来构建它，并将生成的框架拖放到您的 Xcode 项目中。有关使用 Carthage 的更多信息，请参阅此处。

Swift 包管理器

要将 JOSESwift 集成到您的 Xcode 项目作为 Swift 包，请遵循 Apple 撰写的关于如何 将包依赖项添加到您的应用程序 的文章。简而言之，在您的 Package.swift 文件中包含以下依赖项：

.package(url: "https://github.com/airsidemobile/JOSESwift.git")

使用方法

JOSESwift 覆盖了三个功能面

  1. JWS：数字签名
  2. JWE：加密和解密
  3. JWK：表示密钥

JWS：数字签名

一个 JWS 使用数字签名封装和加密数据，该签名可以通过接收者来验证。

签名数据

为了构建一个 JWS，我们需要提供以下部分：

  1. 头部信息
  2. 负载
  3. 签名者
头部
let header = JWSHeader(algorithm: .RS512)

可选地，您可以设置额外的参数

header.kid = "2018-10-08"

header.typ = "JWS"
负载
let message = "Summer ⛱, Sun ☀️, Cactus 🌵".data(using: .utf8)!

let payload = Payload(message)
签名者

签名算法必须与头部算法匹配。

let privateKey: SecKey = /* ... */

let signer = Signer(signingAlgorithm: .RS512, privateKey: privateKey)!
序列化

JWS 紧凑序列化是一个 URL 安全字符串，您可以使用自己的选择方法轻松将其传输给第三方。

guard let jws = try? JWS(header: header, payload: payload, signer: signer) else { ... }

print(jws.compactSerializedString) // ey (...) J9.U3 (...) LU.na (...) 1A

有关构建 JWS 的更多详细信息，请参阅wiki。

验证数据

let publicKey: SecKey = /* ... */

let serialization = "ey (..) n0.HK (..) pQ.yS (..) PA.AK (..) Jx.hB (..) 7w"
do {
    let jws = try JWS(compactSerialization: serialization)
    let verifier = Verifier(verifyingAlgorithm: .RS512, publicKey: publicKey)!
    let payload = try jws.validate(using: verifier).payload
    let message = String(data: payload.data(), encoding: .utf8)!

    print(message) // Summer ⛱, Sun ☀️, Cactus 🌵
}

有关验证现有、序列化 JWS 的更多详细信息，请参阅wiki。

JWE：加密和解密

JWE 通过加密数据来封装和保证数据安全，它可以由 JWE 接收者解密。

数据加密

为了构建一个JWE，我们需要提供以下部分：

  1. 头部信息
  2. 负载
  3. 加密器
头部
let header = JWEHeader(keyManagementAlgorithm: .RSA1_5, contentEncryptionAlgorithm: .A256CBCHS512)

你可以选择设置 附加参数

header.kid = "2018-10-08"

header.typ = "JWE"
负载
let message = "Summer ⛱, Sun ☀️, Cactus 🌵".data(using: .utf8)!

let payload = Payload(message)
加密器

加密算法必须与头部算法匹配。

let publicKey: SecKey = /* ... */

let encrypter = Encrypter(keyManagementAlgorithm: .RSA1_5, contentEncryptionAlgorithm: .A256CBCHS512, encryptionKey: publicKey)!

注意，提供的加密密钥类型必须与以下表格中所示的关键管理算法匹配。

密钥管理算法 加密密钥类型
RSA1_5 SecKey
RSAOAEP SecKey
RSAOAEP256 SecKey
A128KW Data
A192KW Data
A256KW Data
direct Data
序列化

JWE紧凑序列化是一个URL安全的字符串，可以很容易地使用您选择的方法传输给第三方。

guard let jwe = try? JWE(header: header, payload: payload, encrypter: encrypter) else { ... }

print(jwe.compactSerializedString) // ey (..) n0.HK (..) pQ.yS (..) PA.AK (..) Jx.hB (..) 7w

有关构建JWE的更多详细信息，请参阅Wiki。

数据解密

let privateKey: SecKey = /* ... */

let serialization = "ey (..) n0.HK (..) pQ.yS (..) PA.AK (..) Jx.hB (..) 7w"
do {
    let jwe = try JWE(compactSerialization: serialization)
    let decrypter = Decrypter(keyManagementAlgorithm: .RSA1_5, contentEncryptionAlgorithm: .A256CBCHS512, decryptionKey: privateKey)!
    let payload = try jwe.decrypt(using: decrypter)
    let message = String(data: payload.data(), encoding: .utf8)!

    print(message) // Summer ⛱, Sun ☀️, Cactus 🌵
}

有关现有序列化JWE的详细信息，请参阅维基。

请注意，提供的解密密钥类型必须与以下表中指定的密钥管理算法相匹配。

密钥管理算法 解密密钥类型
RSA1_5 SecKey
RSAOAEP SecKey
RSAOAEP256 SecKey
A128KW Data
A192KW Data
A256KW Data
direct Data

JWK：表示密钥

JWK是一种表示加密密钥的JSON数据结构。您可以用它，例如，作为JWS或JWE的有效负载向服务器发送您的公钥。

编码RSA公钥

let publicKey: SecKey = /* ... */

let jwk = try! RSAPublicKey(publicKey: publicKey)

let json = jwk.jsonString()! // {"kty":"RSA","n":"MHZ4L...uS2d3","e":"QVFBQg"}

有关编码RSA公钥的详细信息，请参阅维基。

解码RSA公钥

let json: Data = /* ... */

let jwk = try! RSAPublicKey(data: json)

let publicKey: SecKey = try! jwk.converted(to: SecKey.self)

有关解码RSA公钥的详细信息，请参阅维基。

⚠️我们在解码时忽略密钥参数 "key_ops" 和 "x5c"。这是由于我们的解码实现中的错误。有关详细信息，请参阅#117。

安全性

JOSESwift使用Apple的安全框架和Apple的CommonCrypto进行加密。

有关安全公告或相关事项，请联系[email protected]。

请参阅我们的安全策略获取更多信息。

贡献

鼓励并非常欢迎为项目贡献。🤓

如果您想贡献，请提交拉取请求。对于新功能请求、讨论或错误报告，只需打开一个问题。

请参阅我们的贡献指南获取更多信息。

资源

您可以在各自的RFC中找到关于相关JOSE标准的详细信息

不要忘记查看我们的Wiki以获取更详细的文档。

联系方式

请随时联系项目维护者：[email protected]。

致谢

JOSESwift由Airside Mobile维护。

项目作者和维护者

@carol-mohemian，@daniel-mohemian，@gigi-mohemian

审阅者

@haeser, @michael-mohemian

标志

该标志由Ivan Leuzzi设计。

感谢

以下项目在我们开发过程中提供了参考和灵感：

许可协议

JOSESwift采用Apache License 2.0许可。有关详细信息，请参阅LICENSE。