JOSESwift is a modular and extensible framework for the JOSE standards JWS, JWE, and JWK written in Swift. As of now, its usage is limited to iOS because it relies on the iOS cryptography frameworks.
π‘ 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.
- 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.
π 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 |
For interchangeability JOSESwift currently supports compact serialization for JWS and for JWE.
Compact Serialization | JSON Serialization |
---|---|
β |
JOSESwift supports the DEFLATE compression algorithm for JWE.
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.
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.
To integrate JOSESwift in your Xcode project as a Swift package, follow Apple's article on how to add package dependencies to your app.
JOSESwift covers three functional aspects:
A JWS
encapsulates and secures data using a digital signature which can be verified by the receiver of the JWS
.
In order to construct a JWS we need to provide the following parts:
- Header
- Payload
- Signer
let header = JWSHeader(algorithm: .RS512)
Optionally you can set addtitional parameters:
header.kid = "2018-10-08"
header.typ = "JWS"
let message = "Summer β±, Sun βοΈ, Cactus π΅".data(using: .utf8)!
let payload = Payload(message)
The signer algorithm must match the header algorithm.
let privateKey: SecKey = /* ... */
let signer = Signer(signingAlgorithm: .RS512, privateKey: privateKey)!
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.
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.
A JWE encapsulates and secures data by encrypting it. It can be decrypted by the receiver of the JWE.
In order to construct a JWE we need to provide the following parts:
- Header
- Payload
- Encrypter
let header = JWEHeader(keyManagementAlgorithm: .RSA1_5, contentEncryptionAlgorithm: .A256CBCHS512)
Optionally you can set addtitional parameters:
header.kid = "2018-10-08"
header.typ = "JWE"
let message = "Summer β±, Sun βοΈ, Cactus π΅".data(using: .utf8)!
let payload = Payload(message)
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 |
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.
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 |
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.
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.
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.
"key_ops"
and "x5c"
when decoding. This is due to a bug in our decoding implementation. See #117 for details.
JOSESwift uses the iOS 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.
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.
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.
Feel free to contact the project maintainers at [email protected].
JOSESwift is maintained by Airside Mobile.
@carol-mohemian, @daniel-mohemian, @gigi-mohemian
The logo was designed by Ivan Leuzzi.
To the following projects, which served us as reference and inspiration during development:
JOSESwift is licensed under the Apache License 2.0. See LICENSE for details.