You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/reference/policies/verify-jwt-policy). info

> [!NOTE]
> **Note:** This document is applicable for Edge Public and Private Cloud users.


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](https://tools.ietf.org/html/rfc5280#section-4.2.1.3).

### 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.

### Recommended key usage and extended key usages for certificates used in Apigee Edge

| **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](https://en.wikipedia.org/wiki/Chain_of_trust).
- If you aren't familiar with the OpenSSL library, read [OpenSSL](https://en.wikipedia.org/wiki/OpenSSL)
- If you want to learn more about key usage extensions and extended key usage, read [RFC5280](https://tools.ietf.org/html/rfc5280#section-4.2.1.3).
- If you want to use the command-line examples in this guide, install or update to the latest version of [OpenSSL client](https://www.openssl.org/source/)
- Ensure the certificates are in PEM format and if not, [convert the certificates to PEM format](https://docs.apigee.com/how-to-guides/converting-certificates-to-supported-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 <var translate="no">certificate</var> 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 <var translate="no">certificate</var> 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
   ```

> [!NOTE]
> **Note:** If the certificates that you would like to use in Apigee Edge do not have the recommended key usage and extended key usage as explained in [Recommended key usage](https://docs.apigee.com/how-to-guides/validating-certificate-purpose#recommended-key-usage), then you need to work with your Certificate Authority and procure the certificates with the right key usage and extended usage.