IBM API Connect (APIC) uses multiple types of certificates. It is critical to understand the different types of certificates and how to use them correctly to enforce security and reduce operational effort.2. Enhancing Security using Certificates
Certificates can be used throughout both the platform and with gateway applications (APIs) to verify and be verified by trusted parties. Certificates provide channel level and message level security on the platform and can be used for authorization within APIs and to encrypt messages flowing through the system.3. Certificate Operational Impact
Certificate management is an important operational activity. Due to the importance of certificates, maintenance is a high-risk avenue. If a certificate expires no APIs run, if certificates are poorly constructed, they will be rejected. In API Connect, multiple teams using Catalogs, Spaces, Gateway Domains all may need different certificates, certificate types and in some cases, different Certificate Authorities.
This means a system must be in place to ensure a complex network of certificates can be deployed, updated and revoked in a safe and agile manner.4. Certificate Usage Design
When designing the platform, it is important to ensure the right level of complexity is found. Channels need to be independently secured, but this could increase the number of certificates that need to be managed.
From the application aspect, improper design can lead to “brittle” applications that either accept too many applications or reject too many applications. Design decision that over enhance security create complicated applications which are hard to support, hard to use and thus may reduce the impact of a positive system.5. Certificate Types
APIC certificates can be broadly categorized in the following three types:
a. Transport Layer Security (TLS) Certificates: The transport layer – which is typically HTTP REST is secured between API Providers and API Consumers using TLS certificates via TLS profiles. APIC v10 provides support for the latest standard TLS 1.3 too.
b. Message Level Certificates: Message level security is the most commonly used way to secure APIs. Message signing is used to verify the identity of the sender while encryption can be used to ensure privacy of the messages.
c. APIC Platform Certificates – for in-platform communication: To secure the communications amongst various sub systems, APIC uses the provided certificates as described at https://www.ibm.com/support/knowledgecenter/SSMNED_v10/com.ibm.apic.install.doc/certs_overview_vm.html
. These are also TLS certificates but are being described separately as these are used exclusively within the product.6. Certificate Security Pattern
Using Certificates as part of the wider APIC architecture is a well-known, advised method that uses industry good practice to achieve security goals. The following patterns can be used in application design to ensure security:
a. Authentication: The TLS certificates can be used to authenticate the partner. These TLS certificates are endorsed by public certificate authorities allowing to build a chain of trust. APIC uses TLS profiles to implement it and they can be used to protect inbound and outbound traffic separately. They can be one-way or enforce mutual authentication. The profiles can also be segregated by provider. Please refer to https://www.ibm.com/support/knowledgecenter/SSMNED_v10/com.ibm.apic.cmc.doc/capic_cmc_tlsprofiles_concepts.html
for more details.
b. Message Encryption: can be used to ensure privacy of the messages. The message is obfuscated by using receiver's public certificate and can be read only by them using their private key.
c. Message Signing: is used to validate the authenticity of the sender and the integrity of the message. On signing, the original message is appended with the encrypted hash value of the message. The receiving party can use the public certificate of the sender to validate the message.
APIC gateway scripts can use the jose
module from DataPower to implement encryption and signing. Please refer to https://www.ibm.com/support/knowledgecenter/en/SS9H2Y_10.0/com.ibm.dp.doc/jose_js.html
for more details.
d. Mutual Authentication using Application Certificate: An API deployed into API Connect may supply a TLS Profile to be used when it makes invocations from within its flow. This relies on the Provider Organization both having an accepted certificate in its TLS Profile and trusting the certificate presented from the API’s invoked service. In this way both the API and the service can ensure who is sending and who is receiving secure messages.7. Certificate Storage
Certificates need to be stored in a safe, secure location where they cannot be accessed without proper permissions. These locations are often locked down by specific customer requirements but might generally be kept in one of the following locations:
a. IBM DataPower Gateway (DataPower): The certificates can be stored in various folders on the DataPower Device. Please refer to the link https://www.ibm.com/support/pages/difference-among-certificate-folders-datapower-appliances
to learn more about them. Please note DataPower appliance is also available with factory fitted Hardware Security Module (HSM), if additional security is required.
It is important to note that certificates stored on one DataPower must be replicated across the cluster, and if the certificates differ, they might have inconsistencies such as expiration date or even signee details.
b. Network High Security Module (HSM): DataPower also allows Certificates to be stored on network Luna HSM, which provides FIPS 140-2 Level 3 mode support. Customers already having SafeNet Luna HSM can re-use their existing asset to store the cryptographic content. The same HSM can be used across multiple DataPower devices too. HSMs provide extra security features like the keys never leave the hardware and the boxes are tamper resistant so they are often used in settings where highest level of security is required.
c. JWKS: JSON Web Key (JWK) standardizes the representation of certificates in JSON format while JSON Web Key Set (JWKS) represents a collection of JWKs. It allows the partners to fetch the public certificate dynamically from a REST service. As the certificates are fetched at runtime, it allows the owners to rotate the keys without breaking partner applications so JWKS is often used to for signature validation.8. Certificate Usage
This section describes how the certificates are used. This is an important consideration from certificate renewal perspective.
a. To generate short lived shared secret key as in TLS certificates.
b. Use the certificate for “immediate” transaction. For example, APIC application signs the message and the client validate the signature before using it. All this happens in quick succession.
c. Use the certificate for long lived transactions, for example APIC signs a long-lived token which can be used later, say after 60 days. In such cases it is important that the certificate used for signing is still available and valid after 60 days so that when the token is used later, it can be validated with the certificate.9. Access Patterns: Using Crypto Objects to access Certificates
When utilising certificates stored in other locations, the API runtime needs to be able to communicate with the DataPower Gateway which certificate it wants to use and where it is located. APIC DataPower uses Crypto Objects to provide a layer of indirection to the certificates. Similarly, API Manager uses TLS profiles to define the certificates used for making secure connections. APIC uses one of the following access patterns to use the right certificate:
a. Always looks for the same hardcoded crypto object name or the TLS profile name, as applicable.
b. Use variable object names. For example, if we define year as the variable key, the API will seek crypto object named “partner-functionality-encryption-public-2020" in 2020 while in 2021, it will look for “partner-functionality-encryption-public-2021".
c. Use the crypto objects as specified in the message, for example as kid in JWT. This can also be used for JWKS certificates.
d. Use Certificate SKI value as specified in the message to search for the certificate, for example as kid in JWT
To learn more about c) and d), please refer to https://developer.ibm.com/apiconnect/2019/09/13/identifying-keys-in-api-connect-for-json-security-objects/
It is important to note that any strategy chosen will have an impact on the management of the certificates e.g. using a year or month variable requires a new certificate in place and tested ahead of time.10. External Dependencies
In some cases, it is essential that the certificates are changed in synchronisation with external parties, otherwise it might break the integration.
This might be a passive relationship where one or the other changes certificates and gives notice of actions to be performed, or it is an active relationship which need coordination to complete a certificate change.
a. There are multiple scenarios where there is no dependency on the external party. For example, where certificate is being used for authentication and as long as certificates match a specific criterion e.g. the CN name matches a pre-defined value or it can be validated with Root CA, the external party will still be able to use the new certificate.
b. Certificates needs to be changed in co-ordination with partner and is used immediately, for example in Pattern (9.a). If the partner is using an older set of keys, the security integration might not work. For example, if the Sender changes its certificates and signs using the new key while the Receiver is still using the old certificate, the message validation will fail.
c. Certificates can be added independently, for example in Patterns (9.b, 9.c, 9.d). In all these examples, the certificates can be added before the cut over, preferably validated too so that the transition is smooth.11. Rotation timeline
All certificates have an expiration. Some certificates are short lived e.g. a few days, others are long lived and expire after a few years, and in extreme cases certificates can be made to practically never expire by being set well into the future. These rotations depend heavily on the needs of application, organization and the actors at play for each security use case. It is important therefore that the rotation or renewing of certificates is managed and the integrity of the security is retained.
a. In cases where the certificate is used immediately, then rotation can be done any time before it expires.
b. In case where long-lived tokens use certificates, the certificates need to be rotated based on combination of certificate expiry and token life time. For example, if the certificate is expiring on 31 March and the signed tokens are valid for 3 months, that implies that the certificates should be rotated by 31st December. This will ensure that the tokens generated on 20th December use the certificates that are still valid on 20th March.12. Revocation
Existing valid certificates can be invalidated by its issuing certificate authority through Certificate Revocation. It is used to prevent validation with a “tainted” certificate.
Please refer to this link https://www.ibm.com/support/pages/how-do-you-configure-crl-validation-application-domain-ibm-websphere-datapower-soa-appliance
to understand how certificate revocation can be configured with DataPower.
Additionally, consider the impact of DataPower handling a revocation list in a cluster system. There is a need to synchronise the cluster which takes a period of time which may be greater than the accepted Service Level Agreement (SLA) of the platform. In these cases, an external revocation service might be a better solution.13. Suggestions
Here are few suggestions that should be considered while using certificates with APIC:
a) Use Certificate Lifecycle Management tools for maintaining the certificates. They are very useful in tracking the certificate usage and their expiry. If certificates are stored only on DataPower, use Certificate Monitor to track expiring certificates: https://www.ibm.com/support/knowledgecenter/en/SS9H2Y_10.0/com.ibm.dp.doc/certificatemonitor_defining.html
. It can be used to email to the operations team about certificate expiry in advance as the alert is generated only once.
b) In a DataPower cluster, keep certificates in sharedcert folder, as they can be shared across a cluster domain e.g. you don’t need to put them into each DataPower server as they are shared across the cluster. This does have some security concerns for DataPower with multiple domain clusters.
c) Keep partner public certificates on external JWKS application, if possible, to reduce certificate management overheads. They can be managed by the partners and the certificate rotation becomes seamless.
d) In case of JWTs or its variants, use certificate SKI as the kid as it most “flexible”. The corresponding certificates can be kept with any crypto object name but it will still available.
e) Use Past/Current/Future crypto object naming pattern for easier rotation of message level certificates. “Future” can be used to keep the forthcoming certificates, “Past” for rollback in case of issues while the application should always use the “Current” set. Test applications can be designed to use “Future” crypto objects too, so that the certificates can be tested in advance. At the time of the certificate rotation, “Current” certificate content can be moved to “Past”, while “Future” can be moved to “Current”.
f) Use consistent naming standards for both crypto object and certificate names. For example, consider the following factors
- Certificate type
- Security pattern
- Partner name
in arriving at the standards.
This blog post has been written in collaboration with @Aiden Gallagher
. The authors thank @RAVINDRA BAVISKAR
for reviewing the article.