GitHub - MikaelRucinsky/JOSESwift: A framework for the JOSE standards JWS, JWE, and JWK written in Swift.

JOSESwift is a modular and extensible framework for the JOSE standards JWS, JWE, and JWK written in Swift.

💡 Please note that this implementation of the JOSE standards is not fully complete yet. For example, there is only a limited set of supported algorithms available at the moment. Moreover we currently only support compact serialization of JOSE types. If you are missing a specific feature, algorithm, or serialization, feel free to submit a pull request.

Features

JWS: Digitally signing and verifying arbitrary data using the JWS standard.
JWE: Encrypting and decrypting arbitrary data using the JWE standard.
JWK: Encoding and decoding cryptographic keys.

If you are missing a specific feature, algorithm, or serialization, feel free to submit a pull request.

Cryptographic Algorithms

🔏 JWS		🔐 JWE				🔑 JWK
Digital Signatures and MACs		Key Management		Content Encryption		Keys
`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`

Serializations

For interchangeability JOSESwift currently supports compact serialization for JWS and for JWE.

Compact Serialization	JSON Serialization
✅

Compression Algorithms

JOSESwift supports the DEFLATE compression algorithm for JWE.

Installation

JOSESwift integrates nicely into your iOS and macOS projects. We support the following package managers:

CocoaPods

To integrate JOSESwift into your Xcode project, include it in your Podfile:

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

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

Then install it by running pod install. More documentation on using CocoaPods can be found here.

Carthage

To integrate JOSESwift in your Xcode project, include it in your Cartfile:

github "airsidemobile/JOSESwift"

Then build it by running carthage update and drag the built framework into your Xcode project. More documentation on using Carthage can be found here.

Swift Package Manager

To integrate JOSESwift in your Xcode project as a Swift package, follow Apple's article on how to add package dependencies to your app. In short, include the following dependency in your Package.swift file:

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

Usage

JOSESwift covers three functional aspects:

JWS: Digital Signatures
- Signing data
- Verifying data
JWE: Encryption and Decryption
- Encrypting data
- Decrypting data
JWK: Representing Keys
- Encoding RSA Public Keys
- Decoding RSA Public Keys

JWS: Digital Signatures

A JWS encapsulates and secures data using a digital signature which can be verified by the receiver of the JWS.

Signing Data

In order to construct a JWS we need to provide the following parts:

Header
Payload
Signer

Header

let header = JWSHeader(algorithm: .RS512)

Optionally you can set addtitional parameters:

header.kid = "2018-10-08"

header.typ = "JWS"

Payload

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

let payload = Payload(message)

Signer

The signer algorithm must match the header algorithm.

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

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

Serializing

The JWS compact serialization is a URL-safe string that can easily be transmitted to a third party using a method of your choice.

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

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

More details about constructing a JWS can be found in the wiki.

Verifying Data

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 🌵
}

More details about verifying an existing, serialized JWS can be found in the wiki.

JWE: Encryption and Decryption

A JWE encapsulates and secures data by encrypting it. It can be decrypted by the receiver of the JWE.

Encrypting Data

In order to construct a JWE we need to provide the following parts:

Header
Payload
Encrypter

Header

let header = JWEHeader(keyManagementAlgorithm: .RSA1_5, contentEncryptionAlgorithm: .A256CBCHS512)

Optionally you can set addtitional parameters:

header.kid = "2018-10-08"

header.typ = "JWE"

Payload

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

let payload = Payload(message)

Encrypter

The encrypter algorithms must match the header algorithms.

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

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

Note that the type of the provided encryption key must match the specified key management algorithm as shown in the following table.

Key Management Algorithm	Encryption Key Type
RSA1_5	`SecKey`
RSAOAEP	`SecKey`
RSAOAEP256	`SecKey`
A128KW	`Data`
A192KW	`Data`
A256KW	`Data`
direct	`Data`

Serialization

The JWE compact serialization is a URL-safe string that can easily be transmitted to a third party using a method of your choice.

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

More details about constructing a JWE can be found in the wiki.

Decrypting Data

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 🌵
}

More details about decrypting an existing, serialized JWE can be found in the wiki.

Note that the type of the provided decryption key must match the specified key management algorithm as shown in the following table.

Key Management Algorithm	Decryption Key Type
RSA1_5	`SecKey`
RSAOAEP	`SecKey`
RSAOAEP256	`SecKey`
A128KW	`Data`
A192KW	`Data`
A256KW	`Data`
direct	`Data`

JWK: Representing Keys

A JWK is a JSON data structure that represents a cryptographic key. You could use it, for instance, as the payload of a JWS or a JWE to transmit your public key to a server.

Encoding RSA Public Keys

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

let jwk = try! RSAPublicKey(publicKey: publicKey)

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

More details about encoding RSA public keys can be found in the wiki.

Decoding RSA Public Keys

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

let jwk = try! RSAPublicKey(data: json)

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

More details about decoding RSA public keys can be found in the wiki.

⚠️ We currently ignore the key parameters "key_ops" and "x5c" when decoding. This is due to a bug in our decoding implementation. See #117 for details.

Security

JOSESwift uses Apple's Security framework and Apple’s CommonCrypto for cryptography.

For security disclosures or related matters, please contact [email protected].

See our security policy for more information.

Contributing

Contributions to the project are encouraged and more than welcome. 🤓

If you want to contribute, please submit a pull request. For feature requests, discussions, or bug reports, just open an issue.

See our contributing guidelines for more information.

Resources

You can find detailed information about the relevant JOSE standards in the respective RFCs:

RFC-7515: JSON Web Signature (JWS)
RFC-7516: JSON Web Encryption (JWE)
RFC-7517: JSON Web Key (JWK)
RFC-7518: JSON Web Algorithms (JWA)

Don’t forget to check our our wiki for more detailed documentation.

Contact

Feel free to contact the project maintainers at [email protected].

Credits

JOSESwift is maintained by Airside Mobile.

Project Authors and Maintainers

@carol-mohemian, @daniel-mohemian, @gigi-mohemian

Reviewers

@haeser, @michael-mohemian

Logo

The logo was designed by Ivan Leuzzi.

Thanks

To the following projects, which served us as reference and inspiration during development:

License

JOSESwift is licensed under the Apache License 2.0. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 145 Commits
.circleci		.circleci
.github		.github
JOSESwift.xcodeproj		JOSESwift.xcodeproj
JOSESwift.xcworkspace		JOSESwift.xcworkspace
JOSESwift		JOSESwift
Tests		Tests
fastlane		fastlane
keys		keys
logo		logo
scripts		scripts
.gitignore		.gitignore
.swiftlint.yml		.swiftlint.yml
Brewfile		Brewfile
CHANGELOG.md		CHANGELOG.md
Dangerfile		Dangerfile
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
JOSESwift.podspec		JOSESwift.podspec
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
SECURITY.md		SECURITY.md
sonar-project.properties		sonar-project.properties

License

MikaelRucinsky/JOSESwift

Folders and files

Latest commit

History

Repository files navigation

Contents

Features

Cryptographic Algorithms

Serializations

Compression Algorithms

Installation

CocoaPods

Carthage

Swift Package Manager

Usage

JWS: Digital Signatures

Signing Data

Header

Payload

Signer

Serializing

Verifying Data

JWE: Encryption and Decryption

Encrypting Data

Header

Payload

Encrypter

Serialization

Decrypting Data

JWK: Representing Keys

Encoding RSA Public Keys

Decoding RSA Public Keys

Security

Contributing

Resources

Contact

Credits

Project Authors and Maintainers

Reviewers

Logo

Thanks

License

About

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages