Identifying Keys in API Connect for JSON Security Objects

View Only

Identifying Keys in API Connect for JSON Security Objects

By Aiden Gallagher posted Fri September 13, 2019 12:11 PM

Like

By Ulas Cubuk and Aiden Gallagher
Special thanks to Dave Hay for his reviews

Introduction

Modern applications often use APIs to interact with sources of data, such as System of Records by allowing connected services and products to communicate with each other through a documented interface.

The data consumed and exposed by APIs may be sensitive, in terms of exposing the organization to the risk of data loss, privacy violations and regulatory enforcement. Thus, these APIs can, and should, be protected, by restricting the ability to use the APIs, and also by protecting the API payloads.

In this article we will look at how API message data can be protected and secured using encryption, decryption and validation using IBM API Connect and IBM DataPower Gateway. We will explore the benefits provided by being able to search for keys in IBM DataPower Gateway using Key Identifiers (KIDs) to obfuscate internal object names providing additional security and protection to an enterprise’s APIs.

Table of Contents

Introduction

Cryptography in the context of APIs

JSON Security Objects

JSON Security Objects Usage in IBM API Connect

Identifying Key Targets in IBM DataPower Gateway

What is the “KID” – A baby goat?

KID Usage in IBM DataPower Gateway

KID Usage Examples

Conclusion

References

Extended Diagrams

Computation of JWS

Cryptography in the context of APIs

In messaging and integration, cryptography is the obfuscation and protection of data through encryption and decryption in order to protect messages either at rest or in transit from malicious entities, or accidental viewing.

Cryptography: The art of writing or solving codes - Oxford Dictionary

There are four main concepts of encryption used to achieve different goals:

Confidentiality: Ensuring that a third party watching the encrypted API traffic cannot see the content of the “message”. Only the receiver can decode the encrypted message.

Integrity: Ensuring that a message has not been interfered with or tampered with through encryption, which is vital to trusting the API transactions.

Authentication: Ensuring we can trust a message really came from the sender by signing a message with a digital signature.

Non-repudiation: Ensuring both that a digital signature is authentic, but also that the signer cannot deny the signing of the message in the first place.

By using these methods, it is possible to protect the data that the API is itself exposing.

JSON Security Objects

In the context of APIs, there are several security specifications in the JSON format which provide the enhanced security described in the previous chapter which fulfill these use cases. These are; JWT, JWK, JWS and JWE.

JSON Web Token (JWT) - Open, Industry standard used to securely represent data between two parties

JSON Web Key (JWK) - Cryptographic key represented in JSON format

JSON Web Signature (JWS) - Open, Industry standard used to sign arbitrary data

JSON Web Encryption (JWE) - Open, Industry standardized syntax used to exchange encrypted data through JSON and Base64

A JSON Web Token (JWT) allows a set of information, to be securely transmitted within APIs between two parties. This information, which might include user data such as a home address, or permission to access personal information is referred to as claims. RFC 7519 - JSON Web Token (JWT)

JWTs are composed of a header, a payload, and a signature in a string format of header.payload.signature.

Note: JWEs have a more complicated structure which does not include a signature. please see the RFC for further details

The header describes information about the signature computation including the algorithm to be used, the name of the key or the type of object

The payload contains the data (claims)

The signature is produced by taking a pseudo code before encoding, hashing and encoding it again

Figure 1 - JWT Composition

JWTs make use of JSON Web Signature (JWS) Specification RFC 7515 in order to form its signature in a specified format. The payload for the JWT can be encrypted inside a JSON Web Encryption (JWE) RFC 7516 which is an encrypted payload wrapper. The key to be used can itself be passed in using a JSON Web Key (JWK) which is JSON representation of the public or private key RFC 7517

JSON Security Objects Usage in IBM API Connect

In API Connect there are two primary methods for securing an API with a JWT by using either of the following methods in the API Assembly in the API Manager for the API:

Generate a token through the jwt-generate policy in the API Manager, and then augment the response payload with your generated token replacing the id token.

Use a token that was generated outside of API Connect and include it into the response payload, which can be validated using the validation policy jwt-validate.

The IBM DataPower Gateway for its part, processes the API YAML including the assembly. The assembly describes what functionality should be performed when a call is made to the defined API address. Included in the assembly, as described above, are references for IBM DataPower Gateway that enable it to perform the relevant encryption, decryption and signature validation.

This functionality can be utilized in one of two methods; either through the IBM DataPower Gateway internal JSON Object Signing and Encryption (JOSE) module or through a custom XSLT policy. However, these tasks require security keys which must be identified during runtime and consumed as part of the task process.

Figure 2 - JWT Processing in IBM DataPower Gateway

However, in order to complete cryptography tasks, the IBM DataPower Gateway needs to be able to target, search, find and consume the key material.

Identifying Key Targets in IBM DataPower Gateway

Keys are needed to perform encryption, decryption and validation tasks which means IBM DataPower Gateway needs to have the keys stored locally or by referencing an external entity where the keys are stored, such as a Hardware Security Module (HSM).

These keys are referenced by an IBM DataPower Gateway Crypto Object which has a logical name and a reference to the key’s location. In the assembly process the definition of what crypto object or key to be used needs to be defined which can be achieved in four distinct ways:

1. A String can be defined at the time of key usage in the API that refers to a configured Crypto Object. This could be the alias of the crypto object or any prefix usage. Some of the prefix usage options are;
  a. cert:base64Cert - Specifies that the target certificate is base-64 encoded.
  b. ski:certSKI - Specifies that the target certificate is the base-64 encoding of the SKI.
  c. thumbprintsha1:sha1string - Specifies a base-64 encoded SHA-1 hash of a certificate.
2. A Buffer is raw data where the PEM file is encoded
3. A JSON Web Key (JWK) is a JSON value with the public key in JSON format as defined in the specification
4. A JSON Web Key Set (JWKS) is a set of unique JWK objects in JSON format. However, where an identifier is described, DataPower can get the correct identifier value from the set.

Of these options, the ‘string’ and ‘JWKS’ might both include a KID value, which can be used to reference a crypto object that is stored on the IBM DataPower Gateway. But what is this KID? How is it used? and why is it so important?

What is the “KID” – A baby goat?

No. A KID is a key identifier.

A KID (key identifier) is a header parameter that gives a clue to the recipient of the token indicating which key was used to secure the JWS and JWE

Each JWT uses a header as metadata to describe how the signature was generated and how cryptographic operations and other additional properties can be applied. This might include:

Type (typ) - Is the object i.e JWT / JWE

Algorithm (alg) - The algorithm used to secure the JWT

Key ID (kid) - the hint indicating the key that was used to secure the JWT

Other metadata types are described in the specifications

Whilst the definitions in the JWS and JWE specifications differ slightly on what exactly the KID is, the general meaning is the same. The KID is a header parameter that gives a clue to the recipient of the token indicating which key was used to secure the JWS/JWE.

Additionally, the KID is meant to be an opaque identifier; meaning it allows identification of the key that was used to sign the JWT, but the actual format or its specific meaning - besides being just an identifier - is not specified.

KID Usage in IBM DataPower Gateway

By using a KID, it is possible to consume keys in IBM DataPower Gateway in order to decrypt and validate API JWT objects. By being able to provide a protected key identifier in a JSON Security object it is possible to reference a key without exposing private details about the IBM DataPower Gateway configuration.

Whilst typically, users of IBM DataPower Gateway might think the KID must be a Crypto Object name, this isn’t necessarily correct. The KID could be any value that would help the recipient to identify the crypto material to decrypt and/or verify a signature.

If the recipient is IBM DataPower Gateway, it must be a value from which DataPower can identify the target key material. These are some available options:

Crypto Object Name - which refers to a configured Crypto Object on the IBM DataPower Gateway. This method provides simplicity but will add dependency on a static object name which will expose internal IBM DataPower Gateway configuration.
SKI Indicates the required literal prefix for a certificate that is identified by Subject Key Identifier (SKI). This method is quite flexible and does not require name mapping. Instead, IBM DataPower Gateway will read all the certificates in the domain to map to one with a matching SKI value. Whilst this is the preferred option, a consideration is that in this approach you need to store the public certificate as well or be able to access it with minimal latency as part of the API call
The SHA-1 hash of the JWK Fingerprint can also be used to identify a key from a JWKS. In one example, this occurs by taking required parameters, sorting them lexicographically (alphabetical ordering), computing this information into a JSON hashing using SHA-1 before finally encoding the hash into a Base64 URL safe format i.e. NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs.

KID Usage Examples

1. IBM DataPower Gateway generating a JWT in JWS format to support some platform security concerns which requires the validation of a signature.

A JWS header is created using the JOSE module and an RS256 algorithm
The JWS header has a KID defined
The JWS is encoded with some claims added
The JWS header and claims are signed and encoded again
The result is a JWT with a JWS Header containing the KID, Claims and a JWS Signature.

Figure 3 - Generation of JWT

2. IBM DataPower Gateway validating a JWT signature

An inbound JWT is parsed by the JOSE module resulting in a JWS Object
The JWS signature is retrieved
The KID is extracted from the protect JWS Header
The KID value is set as the key value
A JWS verifier is created
The JWS is validated by using the key referenced by the KID
The claims are accessible for the rest of the API processing

Figure 4 - JWT Validation

Conclusion

In this article we have looked at how APIs are secured, the benefits of the security provided and how JSON Security objects; JWT, JWS, JKW, JWE are used. We saw the different types of methods for protecting APIs as well as how these are defined in the API Connect product.

By using IBM DataPower Gateway, API Connect provides more protection to confidential messages passed through an API. This protection - security through obscurity - allows IBM DataPower Gateway to support security methods by looking them up using the KID without revealing the actual key itself.