docs: add more documentation

README.md

@@ -181,7 +181,7 @@ Open your `Package.swift` file and add the `jose-swift` package to your `depende
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/your-username/jose-swift.git", .upToNextMinor(from: "1.0.0")),
+    .package(url: "https://github.com/beatt83/jose-swift.git", .upToNextMinor(from: "2.4.0")),
     // ... other dependencies ...
 ]
 ```

Sources/JSONWebAlgorithms/KeyManagement/KeyEncryptionAlgorithm.swift

@@ -12,67 +12,67 @@ import Foundation
 ///
 /// For more information, see [RFC7518 Section 4.1](https://www.rfc-editor.org/rfc/rfc7518#section-4.1)
 public enum KeyManagementAlgorithm: String, Equatable, Codable {
-    // RSA algorithm with PKCS #1 v1.5 padding.
+    /// RSA algorithm with PKCS #1 v1.5 padding.
     case rsa1_5 = "RSA1_5"
 
-    // RSA algorithm with OAEP padding.
+    /// RSA algorithm with OAEP padding.
     case rsaOAEP = "RSA-OAEP"
 
-    // RSA algorithm with OAEP-256 padding.
+    /// RSA algorithm with OAEP-256 padding.
     case rsaOAEP256 = "RSA-OAEP-256"
 
-    // AES algorithm with a 128-bit key.
+    /// AES algorithm with a 128-bit key.
     case a128KW = "A128KW"
 
-    // AES algorithm with a 192-bit key.
+    /// AES algorithm with a 192-bit key.
     case a192KW = "A192KW"
 
-    // AES algorithm with a 256-bit key.
+    /// AES algorithm with a 256-bit key.
     case a256KW = "A256KW"
 
-    // Direct use of a shared symmetric key.
+    /// Direct use of a shared symmetric key.
     case direct = "dir"
 
-    // Elliptic Curve Diffie-Hellman Ephemeral Static key agreement.
+    /// Elliptic Curve Diffie-Hellman Ephemeral Static key agreement.
     case ecdhES = "ECDH-ES"
 
-    // ECDH-ES followed by AES key wrap with a 128-bit key.
+    /// ECDH-ES followed by AES key wrap with a 128-bit key.
     case ecdhESA128KW = "ECDH-ES+A128KW"
 
-    // ECDH-ES followed by AES key wrap with a 192-bit key.
+    /// ECDH-ES followed by AES key wrap with a 192-bit key.
     case ecdhESA192KW = "ECDH-ES+A192KW"
 
-    // ECDH-ES followed by AES key wrap with a 256-bit key.
+    /// ECDH-ES followed by AES key wrap with a 256-bit key.
     case ecdhESA256KW = "ECDH-ES+A256KW"
 
-    // AES GCM algorithm with a 128-bit key.
+    /// AES GCM algorithm with a 128-bit key.
     case a128GCMKW = "A128GCMKW"
 
-    // AES GCM algorithm with a 192-bit key.
+    /// AES GCM algorithm with a 192-bit key.
     case a192GCMKW = "A192GCMKW"
 
-    // AES GCM algorithm with a 256-bit key.
+    /// AES GCM algorithm with a 256-bit key.
     case a256GCMKW = "A256GCMKW"
 
-    // PBES2 with HMAC-SHA256 and AES Key Wrap with a 128-bit key.
+    /// PBES2 with HMAC-SHA256 and AES Key Wrap with a 128-bit key.
     case pbes2HS256A128KW = "PBES2-HS256+A128KW"
 
-    // PBES2 with HMAC-SHA384 and AES Key Wrap with a 192-bit key.
+    /// PBES2 with HMAC-SHA384 and AES Key Wrap with a 192-bit key.
     case pbes2HS384A192KW = "PBES2-HS384+A192KW"
 
-    // PBES2 with HMAC-SHA512 and AES Key Wrap with a 256-bit key.
+    /// PBES2 with HMAC-SHA512 and AES Key Wrap with a 256-bit key.
     case pbes2HS512A256KW = "PBES2-HS512+A256KW"
 
-    // Elliptic Curve Diffie-Hellman 1-Party Unilateral key agreement.
+    /// Elliptic Curve Diffie-Hellman 1-Party Unilateral key agreement.
     case ecdh1PU = "ECDH-1PU"
 
-    // ECDH-1PU followed by AES key wrap with a 128-bit key.
+    /// ECDH-1PU followed by AES key wrap with a 128-bit key.
     case ecdh1PUA128KW = "ECDH-1PU+A128KW"
 
-    // ECDH-1PU followed by AES key wrap with a 192-bit key.
+    /// ECDH-1PU followed by AES key wrap with a 192-bit key.
     case ecdh1PUA192KW = "ECDH-1PU+A192KW"
 
-    // ECDH-1PU followed by AES key wrap with a 256-bit key.
+    /// ECDH-1PU followed by AES key wrap with a 256-bit key.
     case ecdh1PUA256KW = "ECDH-1PU+A256KW"
 
     /// Provides a `KeyWrapping` instance suitable for the key management algorithm.

Sources/JSONWebEncryption/JWE.swift

@@ -17,7 +17,7 @@
 import Foundation
 import Tools
 
-/// `JWE` struct represents a JSON Web Encryption (JWE) object.
+/// `JWE` struct represents a JSON Web Encryption (JWE) structure as defined in [RFC7516](https://tools.ietf.org/html/rfc7516).
 /// It provides mechanisms to encrypt content, represented as the `cipher`, along with various headers and authentication data.
 public struct JWE {
     /// The `protectedHeader` is a JWE header with registered fields that are integrity protected.

Sources/JSONWebToken/JWT.swift

@@ -19,7 +19,7 @@ import JSONWebSignature
 import JSONWebEncryption
 import JSONWebKey
 
-/// `JWT` represents a JSON Web Token which is a compact, URL-safe means of representing claims to be transferred between two parties.
+/// `JWT` represents a JSON Web Token (JWT) structure as defined in [RFC7519](https://tools.ietf.org/html/rfc7519).
 public struct JWT {
     /// `Format` is an enumeration that defines the two possible formats for a JWT: JWE and JWS.
     public enum Format {

Sources/jose-swift/jose-swift.docc/Articles/ClaimsValidation.md

@@ -0,0 +1,25 @@
+# Claims Validation
+
+Claims validation is a crucial aspect of JSON Web Tokens (JWTs) to ensure that the token is valid, trustworthy, and has not been tampered with. This article explains the concepts behind claims validation, how to perform claims validation using the **jose-swift** library, and practical examples to get you started.
+
+## What are Claims?
+
+Claims are pieces of information asserted about a subject. They are statements about an entity (typically, the user) and additional metadata. Claims are used to pass information between two parties.
+
+### Common Types of Claims
+
+1. **Registered Claims**: Predefined claims that are recommended to provide a set of useful, interoperable claims. Examples include `iss` (issuer), `exp` (expiration time), `sub` (subject), `aud` (audience), `nbf` (not before), and `iat` (issued at).
+
+2. **Public Claims**: Custom claims that can be defined by those using JWTs. These claims should be collision-resistant, typically using namespaces like `http://example.com/claim`.
+
+3. **Private Claims**: Custom claims agreed upon by parties that use JWTs and are not registered or public.
+
+## Validating Claims
+
+Claims validation involves verifying that the claims contained in a JWT meet certain criteria. This typically includes checking the token's expiration time, ensuring the token is not used before a certain time, and verifying that the token was issued by a trusted source.
+
+## Conclusion
+
+Claims validation is a fundamental part of ensuring the integrity and trustworthiness of JSON Web Tokens. By validating claims, you can ensure that tokens are used appropriately and have not been tampered with. The jose-swift library provides robust tools for performing standard and custom claims validation, enabling you to build secure applications.
+
+Explore the tutorials and reference documentation to learn more about claims validation and how to leverage it in your applications.

Sources/jose-swift/jose-swift.docc/Articles/JWEEncryption.md

@@ -0,0 +1,190 @@
+# JWE Encryption
+
+JSON Web Encryption (JWE) provides a mechanism for securely encrypting data, ensuring both confidentiality and integrity. This article explains the concepts behind JWE, how to create and decrypt encrypted payloads using the **jose-swift** library, and practical examples to get you started.
+
+## What is a JWE?
+
+A JSON Web Encryption (JWE) is a compact, URL-safe token format that represents encrypted content using JSON data structures. It is used to ensure the confidentiality of the data by encrypting the payload.
+
+## Supported Algorithms
+
+The **jose-swift** library supports a wide range of cryptographic algorithms for JSON Web Encryption (JWE). The supported algorithms are:
+
+### Key Management Algorithms
+- **RSA1_5**: RSAES-PKCS1-v1_5
+- **RSA-OAEP**: RSAES OAEP using default parameters
+- **RSA-OAEP-256**: RSAES OAEP using SHA-256 and MGF1 with SHA-256
+- **A128KW**: AES Key Wrap with default 128-bit key
+- **A192KW**: AES Key Wrap with 192-bit key
+- **A256KW**: AES Key Wrap with 256-bit key
+- **dir**: Direct use of a shared symmetric key
+- **ECDH-ES**: Elliptic Curve Diffie-Hellman Ephemeral Static key agreement
+- **ECDH-ES+A128KW**: ECDH-ES using Concat KDF and A128KW wrapping
+- **ECDH-ES+A192KW**: ECDH-ES using Concat KDF and A192KW wrapping
+- **ECDH-ES+A256KW**: ECDH-ES using Concat KDF and A256KW wrapping
+- **ECDH-1PU**: Elliptic Curve Diffie-Hellman One-Pass Unified Model
+- **ECDH-1PU+A128KW**: ECDH-1PU using Concat KDF and A128KW wrapping
+- **ECDH-1PU+A192KW**: ECDH-1PU using Concat KDF and A192KW wrapping
+- **ECDH-1PU+A256KW**: ECDH-1PU using Concat KDF and A256KW wrapping
+- **A128GCMKW**: Key wrapping with AES GCM using 128-bit key
+- **A192GCMKW**: Key wrapping with AES GCM using 192-bit key
+- **A256GCMKW**: Key wrapping with AES GCM using 256-bit key
+- **PBES2-HS256+A128KW**: PBES2 with HMAC SHA-256 and "A128KW" wrapping
+- **PBES2-HS384+A192KW**: PBES2 with HMAC SHA-384 and "A192KW" wrapping
+- **PBES2-HS512+A256KW**: PBES2 with HMAC SHA-512 and "A256KW" wrapping
+- Note: ECDH-1PU is specified in [draft-ietf-jose-cfrg-curves-10](https://datatracker.ietf.org/doc/draft-ietf-jose-cfrg-curves/10/)
+
+### Content Encryption Algorithms
+- **A128CBC-HS256**: AES CBC using 128-bit key with HMAC SHA-256
+- **A192CBC-HS384**: AES CBC using 192-bit key with HMAC SHA-384
+- **A256CBC-HS512**: AES CBC using 256-bit key with HMAC SHA-512
+- **A128GCM**: AES GCM using 128-bit key
+- **A192GCM**: AES GCM using 192-bit key
+- **A256GCM**: AES GCM using 256-bit key
+- **C20PKW**: ChaCha20-Poly1305
+- Note: ChaChaPoly20-Poly1305 is specified in [draft-amringer-jose-chacha-02](https://datatracker.ietf.org/doc/html/draft-amringer-jose-chacha-02)
+
+### Compression Algorithms
+- **DEFLATE**: (zip)
+
+These algorithms provide flexibility in choosing the level of security and compatibility with different cryptographic standards. You can specify the algorithms to be used in the `alg` (key management algorithm) and `enc` (content encryption algorithm) fields of the JWE header when creating or decrypting a JWE.
+
+## Structure of a JWE
+
+A JWE is composed of five parts, separated by dots (`.`):
+
+1. **Protected Header**
+2. **Encrypted Key**
+3. **Initialization Vector**
+4. **Ciphertext**
+5. **Authentication Tag**
+
+### 1. Protected Header
+
+The JWE protected header contains metadata about the encryption algorithm, key management algorithm, and other parameters. The header is Base64Url encoded.
+
+Example:
+
+```
+{
+    “alg”: “RSA-OAEP”,
+    “enc”: “A256GCM”
+}
+```
+
+### 2. Encrypted Key
+
+The encrypted key is used to encrypt the Content Encryption Key (CEK). It is Base64Url encoded.
+
+### 3. Initialization Vector
+
+The initialization vector (IV) is used in the encryption process to provide randomness. It is Base64Url encoded.
+
+### 4. Ciphertext
+
+The ciphertext is the encrypted payload. It is Base64Url encoded.
+
+### 5. Authentication Tag
+
+The authentication tag is used to ensure the integrity and authenticity of the ciphertext. It is Base64Url encoded.
+
+## Creating a JWE
+
+Using the **jose-swift** library, creating a JWE is straightforward. Here’s an example of how to create a JWE:
+
+```swift
+let payload = “Hello, World!”.data(using: .utf8)!
+let recipientKey = try RSA(publicKey: Data(base64Encoded: “your-public-key”)!)
+
+let jwe = try JWE(
+    payload: payload,
+    keyManagementAlg: .rsaOAEP,
+    encryptionAlgorithm: .a256GCM,
+    recipientKey: recipientKey
+)
+
+print(“JWE: (jwe.compactSerialization)”)
+```
+
+In this example, the `JWE` initializer encrypts the payload using the RSA-OAEP key management algorithm and the A256GCM content encryption algorithm.
+
+## Decrypting a JWE
+
+To decrypt a JWE, you need to use the private key corresponding to the public key that was used to encrypt the token. Here’s an example:
+
+```swift
+let jweString = “your.jwe.token.here”
+let recipientKey = try RSA(privateKey: Data(base64Encoded: “your-private-key”)!)
+let jwe = try JWE(compactString: jweString)
+
+let decryptedPayload = try jwe.decrypt(recipientKey: recipientKey)
+print(“Decrypted payload: (String(data: decryptedPayload, encoding: .utf8)!)”)
+```
+
+In this example, the `decrypt` method decrypts the JWE using the private key.
+
+## Using Custom Headers
+
+You can include custom headers in your JWE to add additional metadata. Here’s an example:
+
+```swift
+let payload = “Hello, World!”.data(using: .utf8)!
+let recipientKey = try RSA(publicKey: Data(base64Encoded: “your-public-key”)!)
+
+var header = DefaultJWEHeaderImpl(keyManagementAlgorithm: .a256GCMKW, encodingAlgorithm: .a256GCM)
+header.keyID = “key-id”
+
+let jwe = try JWE(
+    payload: payload,
+    protectedHeader: header,
+    recipientKey: recipientKey
+)
+
+print(“JWE: (jwe.compactSerialization)”)
+```
+
+In this example, the `kid` (key ID) field is added to the header to specify which key was used for encryption.
+
+## Nested JWE
+
+A Nested JWE is a JWE that is encrypted and then encrypted again. This provides an additional layer of security by ensuring both the confidentiality and authenticity of the message. Here’s how to create a nested JWE:
+
+```swift
+let nestedPayload = “Nested payload”.data(using: .utf8)!
+let nestedRecipientKey = try RSA(publicKey: Data(base64Encoded: “nested-public-key”)!)
+
+let nestedJwe = try JWE(
+    payload: nestedPayload,
+    keyManagementAlg: .rsaOAEP,
+    encryptionAlgorithm: .a256GCM,
+    recipientKey: nestedRecipientKey
+)
+
+let outerRecipientKey = try RSA(publicKey: Data(base64Encoded: “outer-public-key”)!)
+let outerJwe = try JWE(
+    payload: JSONEncoder().encode(nestedJwe.compactSerialization),
+    keyManagementAlg: .rsaOAEP,
+    encryptionAlgorithm: .a256GCM,
+    recipientKey: outerRecipientKey
+)
+
+print(“Nested JWE: (outerJwe.compactSerialization)”)
+```
+
+## Conclusion
+
+JSON Web Encryption (JWE) is a powerful way to ensure the confidentiality of your data. The **jose-swift** library provides robust support for creating and decrypting JWEs, including custom headers and nested tokens. Explore the tutorials and reference documentation to learn more about how to leverage JWE in your applications.
+
+## Topics
+
+### Supported Key Management Algorithms
+
+- ``KeyManagementAlgorithm``
+
+### Supported Content Encryption Algorithms
+
+- ``ContentEncryptionAlgorithm``
+
+### Supported Compression Algorithms
+
+- ``ContentCompressionAlgorithm``