Validating certificate purpose

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

This document explains how to validate a certificate’s purpose before you upload the certificate to a keystore or a truststore. The process relies on OpenSSL for validation and is applicable on any environment where OpenSSL is available.

The TLS certificates are generally issued with one or more purposes for which they can be used. Typically this is done to restrict the number of operations for which a public key contained in the certificate can be used. The purpose of the certificate is available in the following certificate extensions:

  • Key usage
  • Extended key usage

Key usage

The key usage extension defines the purpose (for example, encipherment, signature, or certificate signing) of the key contained in the certificate. If the public key is used for entity authentication, then the certificate extension should have the key usage Digital signature.

The different key usage extensions available for a TLS certificate created using the Certificate Authority (CA) process are as follows:

  • Digital signature
  • Non-repudiation
  • Key encipherment
  • Data encipherment
  • Key agreement
  • Certificate signing
  • CRL signing
  • Encipher only
  • Decipher only

For more information on these key usage extensions, see RFC5280, Key Usage.

Extended key usage

This extension indicates one or more purposes for which the certified public key may be used, in addition to or in place of the basic purposes indicated in the key usage extension. In general, this extension will appear only in end entity certificates.

Some common extended key usage extensions are as follows:

  • TLS Web server authentication
  • TLS Web client authentication
  • anyExtendedKeyUsage

An extended key can be either critical or non-critical.

  • If the extension is critical, the certificate must be used only for the indicated purpose or purposes. If the certificate is used for another purpose, it is in violation of the CA's policy.
  • If the extension is non-critical, it indicates the intended purpose or purposes of the key is informational and does not imply that the CA restricts use of the key to the purpose indicated. However, applications that use certificates may require that a particular purpose be indicated in order for the certificate to be acceptable.

If a certificate contains both the key usage field and the extended key usage field as critical then both fields must be processed independently, and the certificate can be used only for a purpose that satisfies both key usage values. However, if there is no purpose that can satisfy both key usage values, then that certificate must not be used for any purpose.

When you procure a certificate, ensure that it has the proper key usage defined to satisfy the requirements for client or server certificates without which the TLS handshake would fail.

Purpose Key usage

(mandatory)

Extended key usage

(optional)

Server entity certificate used in Apigee Edge keystore of virtual host
  • Digital signature
  • Key encipherment or key agreement
TLS Web server authentication
Client entity certificate used in Apigee Edge truststore of virtual host
  • Digital signature or key agreement
TLS Web client authentication
Server entity certificate used in Apigee Edge truststore of target server
  • Digital signature
  • Key encipherment or key agreement
TLS Web server authentication
Client entity certificate used in Apigee Edge keystore of target server
  • Digital signature or key agreement
TLS Web client authentication
Intermediate and root certificates
  • Certificate sign
  • Certificate revocation list (CRL) sign

Before you begin

Before you use the steps in this document, be sure you understand the following topics:

  • If you aren’t familiar with a certificate chain, read Chain of trust.
  • If you aren’t familiar with the OpenSSL library, read OpenSSL
  • If you want to learn more about key usage extensions and extended key usage, read RFC5280.
  • If you want to use the command-line examples in this guide, install or update to the latest version of OpenSSL client
  • Ensure the certificates are in PEM format and if not, convert the certificates to PEM format.

Validate the purpose of the certificate

This section describes the steps used to validate the purpose of the certificate.

  1. Login to the server where OpenSSL exists.
  2. To get the key usage of a certificate, run the following OpenSSL command: 
    openssl x509 -noout -ext keyUsage < certificate

    Where certificate is the name of the certificate.

    Sample output 

    openssl x509 -noout -ext keyUsage < entity.pem
X509v3 Key Usage: critical
    Digital Signature, Key Encipherment

openssl x509 -noout -ext keyUsage < intermediate.pem
X509v3 Key Usage: critical
    Certificate Sign, CRL Sign
  3. If a key usage is mandatory, then it will be defined as critical as follows: 
    openssl x509 -noout -ext keyUsage < intermediate.pem
X509v3 Key Usage: critical
    Certificate Sign, CRL Sign
  4. Run the following command to get the extended key usage for a certificate. If the extended key usage is not defined as critical, then it is a recommendation and not a mandate. 
    openssl x509 -noout -ext extendedKeyUsage < certificate

    Where certificate is the name of the certificate.

    Sample output 

    openssl x509 -noout -ext extendedKeyUsage < entity.pem
X509v3 Extended Key Usage:
    TLS Web Server Authentication, TLS Web Client Authentication

openssl x509 -noout -ext extendedKeyUsage < intermediate.pem
X509v3 Extended Key Usage:
    TLS Web Server Authentication, TLS Web Client Authentication