JOSE (JSON Object Signing and Encryption) Framework

What is JOSE?

Introduction

The JOSE (JSON Object Signing and Encryption) Framework is a set of specifications that provide a standard way of representing and securing digital content using JSON (JavaScript Object Notation) data structures. JOSE includes:

• JWS: JSON Web Signature, a specification for digitally signing JSON data.
• JWE: JSON Web Encryption, a specification for encrypting JSON data.
• JWK: JSON Web Key, a specification for representing cryptographic keys in JSON format.
• JWT: JSON Web Token, a compact and standardized way of securely transmitting information between parties using JSON data structures.
• JWA: JSON Web Algorithms, a specification for defining cryptographic algorithms used in JWE and JWS.

Digital content security is essential in modern communication systems. It is necessary to ensure that data is not tampered with, that it comes from a verified source, and that it is kept confidential. The JOSE Framework addresses these common data security objectives:

• Integrity: Verifying that data has not been tampered with
• Authenticity: Verifying the origin of the data
• Non-repudiation: Verifying that the origin of the data can be verified by others
• Confidentiality: Keeping data secret from unauthorized parties and processes

In the next sections of this tutorial, we will explore each of the JOSE specifications in detail, starting with JSON Web Signature (JWS).

JWS (JSON Web Signature)

JSON Web Signature (JWS) is a format for digitally signing JSON data, providing integrity and authentication to the content. JWS enables a sender to sign a JSON payload and produce a compact representation of the signed data that can be transmitted to the receiver. The receiver can then verify the signature to ensure that the data has not been tampered with and that it comes from a trusted sender.

JWS is built on top of JSON and provides a standard way of representing digital signatures in JSON format. The JWS format consists of a header, a payload, and a signature, each encoded in base64url format and separated by a dot (‘.’) character.

The header contains metadata about the JWS, such as the signing algorithm used and the key used to sign the data. The payload contains the data being signed. The signature is created by applying the signing algorithm to the concatenation of the header and payload, along with a secret key known only to the sender.

JWS provides data integrity, as any modification to the data will result in an invalid signature. It also provides authenticity, as the signature can only be generated by someone who has access to the secret key. However, JWS does not provide confidentiality, as the signed data can be read by anyone who has access to it.

Example:

Suppose Alice wants to send a message to Bob and wants to ensure that the message has not been tampered with and that it comes from her. Alice can use JWS to sign the message as follows:

• Alice creates a JSON payload containing the message she wants to send:

{
  "message": "Hello Bob!"
}

• Alice creates a JWS header specifying the signing algorithm to use and the key to sign the data. For example:

{
  "alg": "HS256",
  "typ": "JWT"
}

• Here, Alice has chosen to use the HMAC-SHA256 (HS256) algorithm to sign the data and has set the "typ" field to "JWT" to indicate that this is a JSON Web Token.
• Alice encodes the JWS header and payload in base64url format and concatenates them with a '.' character:

eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJtZXNzYWdlIjogIkhlbGxvIEJvYiEifQ

• Alice applies the signing algorithm to the concatenated string using her secret key, which produces a signature. For example:

7N5RZK0fL4zvHyGnc4W_4m0ssDq3q-xWyeviNxMbsm0

• Alice encodes the signature in base64url format and appends it to the JWS header and payload, separated by a '.' character:

eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJtZXNzYWdlIjogIkhlbGxvIEJvYiEifQ.7N5RZK0fL4zvHyGnc4W_4m0ssDq3q-xWyeviNxMbsm0

Now, Alice can send this JWS to Bob. When Bob receives the JWS, he can verify the signature by checking that the signature computed using Alice's secret key matches the signature in the JWS. If the signature is valid, Bob can be sure that the message has not been tampered with and that it comes from Alice.

JWE (JSON Web Encryption)

JWE stands for JSON Web Encryption and is a standard for encrypting JSON data. Like JWS, JWE uses JSON data structures to securely transmit data between parties. JWE provides confidentiality, which means that the contents of the message are kept secret from unauthorized parties.

JWE allows for the encryption of content, and the inclusion of additional authenticated data. JWE also allows for the use of different encryption algorithms, key management techniques, and content encoding methods.

To encrypt a JWE message, the sender follows these steps:

1. Create the plaintext that needs to be encrypted. This plaintext can be any JSON data.
2. Create a JWE header that contains the encryption algorithm and key management algorithm to be used.
3. Choose a key to use for the encryption. This key can be generated by the sender or obtained from a key management service.
4. Use the selected key and encryption algorithm to encrypt the plaintext.
5. Generate an initialization vector (IV) and use it to encrypt the key used for encryption.
6. Create a JWE that includes the ciphertext, the encrypted key, and the initialization vector.
7. Transmit the JWE to the recipient.

When the recipient receives the JWE, they follow these steps to decrypt the message:

1. Parse the JWE and extract the encrypted key, initialization vector, and ciphertext.
2. Use the appropriate key management algorithm to decrypt the encrypted key.
3. Use the decrypted key and initialization vector to decrypt the ciphertext.
4. Parse the decrypted plaintext as JSON data.

By using JWE, parties can securely transmit sensitive data while ensuring its confidentiality.

Example Scenario:

Suppose Alice wants to send a confidential message to Bob. She encrypts the message using Bob’s public key and then creates a JWE as follows:

1. Alice retrieves Bob’s public key from a JWK set.
2. She generates a new symmetric key to encrypt the message.
3. Alice encrypts the message using the symmetric key and the AES-GCM encryption algorithm.
4. Alice encrypts the symmetric key using Bob’s public key and the RSA-OAEP encryption algorithm.
5. Alice constructs the JWE object by combining the encrypted message, the encrypted symmetric key, and the necessary metadata into a JSON object.

Here is an example JWE that Alice creates:

eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.
eyJpc3MiOiJqb2UiLCJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE1MTYyNDA5MjIsImF1ZCI6WyJodHRwOi8vbG9jYWxob3N0OjUwMDAiXSwianRpIjoiMTIzNDU2Nzg5MCJ9.
cZVhpnL47MivTYV7GfhHduRzUhHsxMSAwdpP4I4aFnk.
48V1_ALb6US04U3b.
5eym8TW_c8SuKKS-fv54EyXp10aJpE8rvCvIkDx9dXw

1. Header:

eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ

This section contains the algorithm used for encryption and the encryption method. In this example, the algorithm used is RSAES-OAEP and the encryption method is A256GCM.

2. Encrypted Key:

cZVhpnL47MivTYV7GfhHduRzUhHsxMSAwdpP4I4aFnk

This section contains the encrypted key that was used to encrypt the JWT’s payload.

3. Initialization Vector:

48V1_ALb6US04U3b

This section contains the Initialization Vector (IV) that was used to encrypt the JWT’s payload.

4. Ciphertext:

5eym8TW_c8SuKKS-fv54EyXp10aJpE8rvCvIkDx9dXw

This section contains the encrypted payload of the JWT.

5. Authentication Tag:

5eym8TW_c8SuKKS-fv54EyXp10aJpE8rvCvIkDx9dXw

This section contains the Authentication Tag that was generated during encryption to ensure the integrity of the encrypted JWT.

Now, let’s move on to the next specification: JWK.

JWK (JSON Web Key)

JWK is a JSON format used to represent cryptographic keys. A JWK Set is a JSON object that represents a set of JWKs. JWK provides a standardized way to represent cryptographic keys that can be used for encryption, decryption, signing, and verification.

A JWK consists of a set of key-value pairs, including:

• kty (Key Type): Identifies the type of key. Supported key types include RSA, EC, Octet sequence, and others.
• alg (Algorithm): Identifies the cryptographic algorithm used with the key. For example, "RS256" indicates that the key is used with the RSASSA-PKCS1-v1_5 signature algorithm using SHA-256.
• use (Key Use): Identifies the intended use of the key, whether it's for encryption, signing, or both.
• kid (Key ID): Identifies the key. Can be used to reference a specific key in a JWK set.
• n (Modulus): Used for RSA keys. Contains the modulus value.
• e (Exponent): Used for RSA keys. Contains the exponent value.
• x and y (Coordinates): Used for EC keys. Contain the x and y coordinates for the public key.

Here’s an example of a JWK:

{
  "kty": "RSA",
  "kid": "rsa-key-1",
  "use": "sig",
  "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFVHUvkiDw9iFOjK2kcp--BIKOntVrF9s_mXbpu"
  "e": "AQAB",
  "d": "X4cTteJYGVBA_ECx6FzSX6Uvtv6QbT6KjczuLZSInQgY1YypA24tcI4i4y-l1XXMvLgHF-pG8n2lnDg6f0GuxH-QI6A8PhgG4YoX9-mJGKlDOZzK8sZJfLztWK3ikvMskKjV8RyGx6X9RB2PRhvTfTjKFrRwBYRSFicWSJ2EEY"
}

This example shows an RSA key with a kty of "RSA", a kid of "rsa-key-1", and a use of "sig" (indicating that the key is used for signing). The n and e fields contain the modulus and exponent values for the public key, while the d field contains the private key.

JWKs can be used with both JWS and JWE. In JWS, a JWK can be used to provide the signing key. In JWE, a JWK can be used to provide the encryption key.

JWT (JSON Web Token)

JWT, or JSON Web Tokens, are a compact and self-contained way of securely transmitting information between parties as a JSON object. The information is digitally signed using a secret key, which can be verified and trusted by the recipient of the JWT.

One of the benefits of JWTs is that they can be easily verified without needing to consult a database or other external resource. As long as the recipient knows the secret key used for signing, they can verify the JWT and trust the data it contains.

To use JWTs, a user first needs to obtain a token from an authentication server. This token can then be included in subsequent requests to the server, allowing the user to access protected resources without needing to re-authenticate for every request.

Here’s an example of how a JWT might be used in a web application:

1. User logs in and provides their credentials.
2. Server verifies the credentials and creates a JWT containing the user’s ID and any relevant permissions or metadata.
3. JWT is returned to the client and stored in a cookie or local storage.
4. Subsequent requests to the server include the JWT in the request headers.
5. Server verifies the JWT using the secret key and allows or denies access to protected resources based on the contents of the JWT.

It’s important to note that JWTs are not a replacement for secure communication protocols like HTTPS. While JWTs can provide a layer of security for transmitting data, they should be used in conjunction with other security measures to ensure the overall security of an application.

JWTs consist of three parts, separated by periods: the header, the payload, and the signature.

Header

The header typically consists of two parts: the type of token, which is JWT, and the signing algorithm being used, such as HMAC SHA256 or RSA. It is encoded using Base64Url.

Payload

The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional metadata. The payload is encoded using Base64Url.

Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

Creating a JWT

To create a JWT, you must first create the header and payload. Then, you must sign the header and payload using a secret key and the specified algorithm. Finally, you combine the encoded header, payload, and signature using dots to create the JWT.

Here is an example of a JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

In this example, the header is:

{
  "alg": "HS256",
  "typ": "JWT"
}

And the payload is:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

The signature is created by signing the concatenation of the Base64Url-encoded header and payload with a secret key using the HMAC SHA256 algorithm.

Verifying a JWT

To verify a JWT, you must first decode the JWT to get the header and payload. Then, you must verify the signature using the same secret key and algorithm that was used to sign the JWT. Finally, you can check the claims in the payload to determine whether to trust the JWT.

Comparison table for JWS, JWE, and JWT:

JWA algorithms for JWS

These JWA algorithms define the cryptographic operations used in the JOSE framework to provide data security objectives such as integrity, authenticity, confidentiality, and non-repudiation. The JWS algorithms use these JWA algorithms to digitally sign the content, providing integrity and authenticity.

JWA algorithms for JWE

These JWA algorithms define the cryptographic operations used in the JOSE framework to provide data security objectives such as confidentiality, authenticity, integrity, and non-repudiation. The JWE algorithms use these JWA algorithms to encrypt and sign the content, providing confidentiality, authenticity, and integrity.

HSM (Hardware Security Module) vs JWE (JSON Web Encryption)

HSM (Hardware Security Module) and JWE (JSON Web Encryption) are two different technologies used for securing data in different ways.

HSMs are physical devices that store and manage cryptographic keys securely, perform cryptographic operations, and provide secure storage for sensitive information. HSMs offer high levels of security and are typically used in high-security environments such as financial institutions, government agencies, and large enterprises.

On the other hand, JWE is a standard that provides a way to encrypt and authenticate data in JSON format. It is used to secure data in transit by encrypting it and is often used to protect sensitive data such as personal information or financial transactions. Unlike HSMs, JWE does not provide physical security for keys, but instead uses cryptographic algorithms to protect the data.

In summary, while HSMs and JWE both provide security for data, they are used in different ways and offer different levels of security. HSMs are physical devices that offer high levels of security for managing cryptographic keys, while JWE is a standard used to secure data in transit by encrypting it.

RFCs for JOSE

These RFCs define the specifications and standards for the JOSE family of technologies, including JWS, JWE, JWK, JWT, JWA, and related concepts such as thumbprints and unencoded payloads. They provide guidance and recommendations for implementing secure digital content using JSON data structures.

Conclusion

In conclusion, the JOSE Framework provides a comprehensive set of specifications for securing digital content using JSON data structures. Its components, including JWS, JWE, JWK, and JWT, offer solutions for achieving different security objectives, such as data integrity, authenticity, non-repudiation, and confidentiality.

By using the JOSE Framework, developers can implement secure data transmission and storage mechanisms without needing to reinvent the wheel. The framework has been widely adopted by major organizations and is supported by many programming languages and platforms.

However, it’s important to keep in mind that the JOSE Framework is not a one-size-fits-all solution for all security needs. Developers should carefully consider their security requirements and choose the appropriate components of the JOSE Framework to achieve their desired security objectives.

Overall, the JOSE Framework is a valuable tool in the arsenal of any developer who needs to secure digital content using JSON data structures. Its versatility and flexibility make it a powerful solution for many different use cases, and its continued development and support promise to keep it relevant and useful for years to come.

Here are some of the benefits and advantages of JWS, JWE, and JWT:

1. JWS provides integrity protection: JWS can be used to ensure that the data has not been tampered with during transit. The recipient can verify that the data has not been altered by checking the signature.
2. JWE provides confidentiality: JWE can be used to encrypt the payload so that it can only be read by the intended recipient. This is particularly useful when transmitting sensitive information over an insecure network.
3. JWT provides a lightweight authentication mechanism: JWT can be used to securely transmit information about the user without the need for an additional authentication step. This can help reduce the overhead associated with authentication and authorization.
4. All three provide a standardized way of securing data: JOSE provides a standardized way of securing data using JSON data structures. This makes it easier for developers to implement security features in their applications without having to reinvent the wheel.
5. Platform and language agnostic: JOSE specification is designed to be platform and language agnostic, meaning that it can be used in a variety of programming languages and platforms.
6. Interoperability: JOSE specification ensures that different systems can work together seamlessly, allowing for secure communication and exchange of data between different parties.
7. Wide adoption: JOSE is widely adopted by various industries, including financial services, healthcare, and government, among others, which makes it easier for developers to find resources, tools, and libraries to implement JOSE in their applications.

Next: Full JOSE Implementation with Apinizer