Server certificate configuration for OCSP stapling

AWS IoT Core supports Online Certificate Status Protocol (OCSP) stapling for server certificate, also known as server certificate OCSP stapling, or OCSP stapling. It is a security mechanism used to check the revocation status on the server certificate in a Transport Layer Security (TLS) handshake. OCSP stapling in AWS IoT Core lets you add an additional layer of verification to your custom domain's server certificate validity.

You can enable server certificate OCSP stapling in AWS IoT Core to check the validity of the certificate by querying the OCSP responder periodically. The OCSP stapling setting is part of the process to create or update a domain configuration with a custom domain. OCSP stapling checks for revocation status on the server certificate continuously. This helps verify that any certificates that have been revoked by the CA are no longer trusted by the clients connecting to your custom domains. For more information, see Enabling server certificate OCSP in AWS IoT Core.

Server certificate OCSP stapling provides real-time revocation status check, reduces the latency associated with checking the revocation status, and improves privacy and reliability of secure connections. For more information about the benefits of using OCSP stapling, see Benefits of using OCSP stapling compared to client-side OCSP checks.

What is OCSP?

The Online Certificate Status Protocol (OCSP) aids in providing a server certificate's revocation status for a Transport Layer Security (TLS) handshake.

Key concepts

The following key concepts provide details about the Online Certificate Status Protocol (OCSP).

OCSP

OCSP is used to check the certificate revocation status during the Transport Layer Security (TLS) handshake. OCSP allows for real-time validation of certificates. This confirms that the certificate hasn't been revoked or expired since it was issued. OCSP is also more scalable compared with traditional Certificate Revocation Lists (CRLs). OCSP responses are smaller and can be efficiently generated, making them more suitable for large-scale Private Key Infrastructures (PKIs).

OCSP responder

An OCSP responder (also known as OCSP server) receives and responds to OCSP requests from clients that seek to verify the revocation status of certificates.

Client-side OCSP

In client-side OCSP, the client uses OCSP to contact an OCSP responder to check the certificate's revocation status during the TLS handshake.

Server-side OCSP

In server-side OCSP (also known as OCSP stapling), the server is enabled (rather than the client) to make the request to the OCSP responder. The server staples the OCSP response to the certificate and returns it to the client during the TLS handshake.

OCSP diagrams

The following diagram illustrates how client-side OCSP and server-side OCSP work.

How OCSP stapling works

OCSP stapling is used during the TLS handshake between the client and the server to check the server certificate revocation status. The server makes the OCSP request to the OCSP responder and staples the OCSP responses to the certificates returned to the client. By having the server make the request to the OCSP responder, the responses can be cached and then used multiple times for many clients.

How OCSP stapling works in AWS IoT Core

The following diagram shows how server-side OCSP stapling works in AWS IoT Core.

Benefits of using OCSP stapling compared to client-side OCSP checks

A few advantages of using server certificate OCSP stapling include the following:

Improved privacy

Without OCSP stapling, the client's device can expose information to third-party OCSP responders, potentially compromising user privacy. OCSP stapling mitigates this issue by having the server obtain the OCSP response and deliver it directly to the client.

Improved reliability

OCSP stapling can improve the reliability of secure connections because it reduces the risk of OCSP server outages. When OCSP responses are stapled, the server includes the most recent response with the certificate. This is so that clients have access to the revocation status even if the OCSP responder is temporarily unavailable. OCSP stapling helps mitigate these problems because the server fetches OCSP responses periodically and includes the cached responses in the TLS handshake. This reduces reliance on the real-time availability of OCSP responders.

Reduced server load

OCSP stapling offloads the burden of responding to OCSP requests from OCSP responders to the server. This can help distribute the load more evenly, making the certificate validation process more efficient and scalable.

Reduced latency

OCSP stapling reduces the latency associated with checking the revocation status of a certificate during the TLS handshake. Instead of the client having to query an OCSP server separately, the server sends the request and attaches the OCSP response with the server certificate during the handshake.

Enabling server certificate OCSP in AWS IoT Core

To enable server certificate OCSP stapling in AWS IoT Core, create a domain configuration for a custom domain or update an existing custom domain configuration. For general information about creating a domain configuration with a custom domain, see Creating and configuring customer managed domains.

Use the following instructions to enable OCSP server stapling using AWS Management Console or AWS CLI.

Configuring server certificate OCSP for private endpoints in AWS IoT Core

OCSP for private endpoints lets you use your private OCSP resources within your Amazon Virtual Private Cloud (Amazon VPC) for AWS IoT Core operations. The process involves setting up a Lambda function that acts as an OCSP responder. The Lambda function might use your private OCSP resources to craft OCSP responses that AWS IoT Core will use.

Lambda function

Before you configure server OCSP for a private endpoint, create a Lambda function that acts as a Request for Comments (RFC) 6960-compliant Online Certificate Status Protocol (OCSP) responder, supporting basic OCSP responses. The Lambda function accepts a base64-encoding of the OCSP request in the Distinguished Encoding Rules (DER) format. The Lambda function's response is also a base64-encoded OCSP response in the DER format. The response size must not exceed 4 kilobytes (KiB). The Lambda function must be in the same AWS account and AWS Region as the domain configuration. The following are example Lambda functions.

Example Lambda functions

JavaScript

import * as pkijs from 'pkijs';
console.log('Loading function');
 
export const handler = async (event, context) => {
    const requestBytes = decodeBase64(event);
    const ocspRequest = pkijs.OCSPRequest.fromBER(requestBytes);
 
    console.log("Here is a better look at the OCSP request");
    console.log(ocspRequest.toJSON());
 
    const ocspResponse = getOcspResponse();
    
    console.log("Here is a better look at the OCSP response");
    console.log(ocspResponse.toJSON());
 
   const responseBytes = ocspResponse.toSchema().toBER();
   return encodeBase64(responseBytes);
};
 
function getOcspResponse() {
    const responseString = "MIIC/woBAKCCAvgwggL0BgkrBgEFBQcwAQEEggLlMIIC4TCByqFkMGIxJzAlBgNVBAoMHlJpY2hhcmQncyBEaXNjb3VudCBMYW1iZGEgT0NTUDEZMBcGA1UEAwwQcm91bmRhYm91dE5hdGlvbjEPMA0GA1UEBwwGQ2FybWVsMQswCQYDVQQGEwJJThgPMjAyNDA0MjMxODUzMjVaMFEwTzA6MAkGBSsOAwIaBQAEFD2L7Ol/6ieNMaJbwRbxFWFweXGPBBSzSThwzTc3/p5w7WOtPjp3otNtVgIBAYAAGA8yMDI0MDQyMzE4NTMyNVowDQYJKoZIhvcNAQELBQADggIBAJFRyjDAHfazNejo704Ra3FOsGq/+s82R1spDarr3k7Pzkod9jJhwsZ2YgushlS4Npfe4lHCdwFyZR75WXrW55aXFddy03KLz01ZLNYyxkleW3f5dgrUcRU3PMW9TU2gZ0VOV8L5pmxKBoBRFt6EKtyh4CbiuqkTpLdLIMZmTyanhl5GVyU5MBHdbH8YWZoT/DEBiyS7ZsyhKo6igWU/SY7YMSKgwBvFsqSDcOa/hRYQkxWKWJ19gcz8CIkWN7NvfIxCs6VrAdzEJwmE7y3v+jdfhxW9JmI4xStE4K0tAR9vVOOfKs7NvxXj7oc9pCSG60xl96kaEE6PaY1YsfNTsKQ7pyCJ0s7/2q+ieZ4AtNyzw1XBadPzPJNv6E0LvI24yQZqN5wACvtut5prMMRxAHbOy+abLZR58wloFSELtGJ7UD96LFv1GgtC5s+2QlzPc4bEEof7Lo1EISt3j2ibNch8LxhqTQ4ufrbhsMkpSOTFYEJVMJF6aKj/OGXBUUqgc0Jx6jjJXNQd+l5KCY9pQFeb/wVUYC6mYqZOkNNMMJxPbHHbFnqb68yO+g5BE9011N44YXoPVJYoXxBLFX+OpRu9cqPkT9/vlkKd+SYXQknwZ81agKzhf1HsBKabtJwNVMlBKaI8g5UGa7Bxi6ewH3ezdWiERRUK7F56OM53wto/";
    const responseBytes = decodeBase64(responseString);
    return pkijs.OCSPResponse.fromBER(responseBytes);
}
 
function decodeBase64(input) {
    const binaryString = atob(input);
 
    const byteArray = new Uint8Array(binaryString.length);
    for (var i = 0; i < binaryString.length; i++) {
        byteArray[i] = binaryString.charCodeAt(i);
    }
 
    return byteArray.buffer;
}
 
function encodeBase64(buffer) {
    var binary = '';
    const bytes = new Uint8Array( buffer );
    const len = bytes.byteLength;
 
    for (var i = 0; i < len; i++) {
        binary += String.fromCharCode( bytes[ i ] );
    }
 
    return btoa(binary);
}

Java

package com.example.ocsp.responder;
import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.LambdaLogger;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import org.bouncycastle.cert.ocsp.OCSPReq;
import org.bouncycastle.cert.ocsp.OCSPResp;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Base64;
 
public class LambdaResponderApplication implements RequestHandler<String, String> {
    @Override
    public String handleRequest(final String input, final Context context) {
        LambdaLogger logger = context.getLogger();
        
        byte[] decodedInput = Base64.getDecoder().decode(input);
 
        OCSPReq req;
        try {
            req = new OCSPReq(decodedInput);
        } catch (IOException e) {
            logger.log("Got an IOException creating the OCSP request: " + e.getMessage());
            throw new RuntimeException(e);
        }
 
        try {
            OCSPResp response = businessLogic.getMyResponse();
            String toReturn = Base64.getEncoder().encodeToString(response.getEncoded());
            return toReturn;
        } catch (Exception e) {
            logger.log("Got an exception creating the response: " + e.getMessage());
            return "";
        }
    }
}

Authorizing AWS IoT to invoke your Lambda function

In the process of creating the domain configuration with a Lambda OCSP responder, you must grant AWS IoT permission to invoke the Lambda function after the function is created. To grant the permission, you can use the add-permission CLI command.

Configuring server OCSP stapling for private endpoints

Important notes for using server certificate OCSP stapling in AWS IoT Core

When you use server certificate OCSP in AWS IoT Core, keep the following in mind:

Troubleshooting server certificate OCSP stapling in AWS IoT Core

AWS IoT Core emits the RetrieveOCSPStapleData.Success metric and the RetrieveOCSPStapleData log entries to CloudWatch. The metric and the log entries can help detect issues related to retrieving OCSP responses. For more information, see Server certificate OCSP stapling metrics and Server certificate OCSP log entries.