View a markdown version of this page

Revogação de certificados - Amazon CloudFront
Online Certificate Status Protocol (OCSP)Revogação de certificados com CloudFront Functions e KeyValueStoreEstratégias avançadas de revogação

Revogação de certificados

Quando os certificados precisam ser revogados — devido a comprometimentos, mudanças de política ou relacionamentos terminados —, você precisa de um mecanismo para rejeitar esses certificados durante o handshake do mTLS. O CloudFront fornece duas abordagens nativas para a revogação de certificados, e você pode combiná-las para um controle em camadas.

  • OCSP (Online Certificate Status Protocol) — O CloudFront consulta o respondente OCSP da Autoridade de Certificação em tempo real para verificar se um certificado de cliente foi revogado. Ative o OCSP em seu repositório confiável e o CloudFront gerenciará a validação automaticamente durante o handshake TLS. Os resultados do OCSP também são visíveis nas Funções de Conexão, oferecendo acesso programático ao status de revogação para tomada de decisão personalizada.

  • CloudFront Functions e KeyValueStore — Você mantém uma lista de números de série de certificados revogados em um KeyValueStore do CloudFront. Uma função de conexão consulta o KeyValueStore durante o handshake TLS e permite ou nega a conexão. Isso confere controle total sobre os dados de revogação, o tempo de atualização e a lógica personalizada, como períodos de carência ou exceções baseadas em IP.

Comparação: OCSP versus CloudFront Functions com KeyValueStore
OCSP CloudFront Functions + KeyValueStore
Fonte de dados Respondente OCSP da Autoridade Certificadora Você gerencia a lista de revogação
Mecanismo de atualização Consulta em tempo real à CA Você envia atualizações push para o KeyValueStore
Lógica personalizada Disponível através do Funções de Conexão Integrado ao seu código de função
Dependência externa Requer a disponibilidade do respondente do CA OCSP Sem dependência externa
Melhor para CAs que mantêm respondedores OCSP; status de autoridade de CA em tempo real Revogação autogerenciada; políticas personalizadas; CAs sem suporte a OCSP

Você pode usar as duas abordagens em conjunto. Ative o OCSP para verificação de revogação autoritativa da CA e, em seguida, use uma função de conexão para colocar lógica adicional sobre o resultado do OCSP — por exemplo, permitindo certificados revogados de intervalos de IP confiáveis durante um período de carência.

Online Certificate Status Protocol (OCSP)

O OCSP é um protocolo em tempo real que verifica o status de revogação de um certificado diretamente com a Autoridade de Certificação (CA). Durante o processo de assinatura do certificado, a CA incorpora uma URL de resposta OCSP no certificado. Quando um cliente apresenta seu certificado durante o handshake do mTLS, o CloudFront envia uma solicitação OCSP para a URL do respondente incorporado e age de acordo com a resposta: certificados válidos continuam, certificados revogados são terminados.

O CloudFront valida toda a cadeia de certificados — o certificado preliminar e até três certificados intermediários — cada um em relação aos respectivos URLs de resposta do OCSP. Os certificados no armazenamento de confiança são tratados como âncoras de confiança e não são submetidos à validação de OCSP. Isso se aplica a qualquer certificado no armazenamento de confiança, seja uma CA raiz ou uma CA intermediária. Quando você coloca uma CA intermediária no armazenamento de confiança, ela se torna uma âncora de confiança e a validação da cadeia é encerrada nesse certificado. Somente os certificados abaixo dele na cadeia são validados por OCSP.

Ativar o OCSP

Ative o OCSP em sua loja confiável. Quando ativado, o CloudFront executa automaticamente a validação de OCSP para qualquer certificado de cliente contendo uma URL de respondente OCSP em sua extensão de Acesso à Informação de Autoridade (AIA). Depois que o OCSP é habilitado, cada certificado na cadeia de certificados do cliente abaixo da âncora de confiança deve ter um URL de OCSP. Se algum certificado abaixo da âncora de confiança não contiver um URL de OCSP, o CloudFront não estabelecerá a conexão. Os certificados no armazenamento de confiança (âncoras de confiança) estão isentos desse requisito.

O CloudFront armazena em cache as respostas do OCSP na borda para reduzir o tempo de ida e volta e proteger contra o tempo de inatividade do respondente do OCSP. As respostas do OCSP são armazenadas em cache por aproximadamente 30 minutos, e o status de revogação atualizado pode levar até 30 minutos para ser refletido.

Resultados OCSP em Funções de Conexão

Quando uma função de conexão é configurada na mesma distribuição, o CloudFront a invoca após a conclusão da validação do OCSP. O objeto de conexão contém o status OCSP dos certificados folha e intermediário:

{
  "clientCertificate": {
    "certificates": {
      "leaf": {
        "subject": "CN=client.example.com, O=Example Org",
        "issuer": "CN=Intermediate CA, O=Example Org",
        "serialNumber": "00:a7:30:9e:73:7b:3e:63:bd:b7:c0:7e:bf:d5:c9:86",
        "validity": {
          "notBefore": "2024-01-01T00:00:00Z",
          "notAfter": "2025-01-01T00:00:00Z"
        },
        "sha256Fingerprint": "AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90",
        "ocspEndpoint": "http://ocsp.example.org"
      },
      "intermediates": [
        {
          "subject": "CN=Intermediate CA, O=Example Org",
          "issuer": "CN=Root CA, O=Example Org",
          "serialNumber": "00:a7:30:9e:73:7b:3e:63:bd:b7:c0:7e:bf:d5:c9:86",
          "validity": {
            "notBefore": "2020-01-01T00:00:00Z",
            "notAfter": "2030-01-01T00:00:00Z"
          },
          "sha256Fingerprint": "12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF",
          "ocspEndpoint": "http://ocsp.example.org"
        }
      ]
    },
    "revocationStatus": {
      "chainValidity": "Valid",           // "Valid" | "Invalid" | "Unknown"
      "certificates": {
        "leaf": {
          "method": "OCSP",               // "OCSP"
          "status": "Good",               // "Good" | "Revoked" | "Unknown" | "Error"
          "serialNumber": "00:a7:30:9e:73:7b:3e:63:bd:b7:c0:7e:bf:d5:c9:86"
        },
        "intermediates": [
          {
            "method": "OCSP",             // "OCSP"
            "status": "Error",            // "Good" | "Revoked" | "Unknown" | "Error"
            "errorType": "InternalError", // "InternalError" | "OCSP response verification failed: {Type}"
            "serialNumber": "00:a7:30:9e:73:7b:3e:63:bd:b7:c0:7e:bf:d5:c9:86"
          }
        ]
      }
    }
  },
  "clientIp":"127.0.0.1",
  "endpoint":"d123.cloudfront.net",
  "distributionId":"E1NXS4MQZH501R",
  "connectionId":"xdzQ6lJUDUt8b7OuqOD8lmzOC9HcMaXPmhH5ZdzLCZpKxqzfCPpR4A=="
}

O campo chainValidity pode ser Valid, Invalid ou Unknown. Os valores individuais do certificado status podem ser Good, Revoked, Unknown ouError. O campo errorType contém InternalError ou OCSP response verification failed: {Type} quando o status é Error.

A função de conexão pode substituir o resultado do OCSP — por exemplo, permitindo um certificado revogado de um intervalo de IP confiável ou negando um certificado que o OCSP relata como “bom” com base em lógica comercial adicional.

nota

O campo errorType só estará presente se o status for Error.

Exemplo: tratamento personalizado de OCSP com exceção de IP confiável

function connectionHandler(connection) {
    var revocationStatus = connection.clientCertificate.revocationStatus;
    var trustedIP = (connection.clientIp === "[IP_ADDRESS]");

    if (revocationStatus.chainValidity === "Invalid") {
        if (trustedIP) {
            connection.allow();
        } else {
            connection.deny();
        }
    } else if (revocationStatus.certificates.leaf.status === "Error") {
        console.log(revocationStatus.certificates.leaf.errorType);
        connection.deny();
    } else {
        connection.allow();
    }
}

Comportamento de falha do OCSP

Quando o CloudFront não consegue determinar o status de revogação de um certificado — porque o respondente OCSP está inacessível, retorna um erro ou retorna “desconhecido” —, o CloudFront nega a conexão por padrão. Para implementar o comportamento de falha suave, use uma função de conexão. As funções de conexão não serão executadas se o OCSP estiver habilitado e a URL do OCSP estiver ausente nos certificados do cliente. O resultado do OCSP está disponível no objeto de conexão, e sua função pode permitir conexões quando o status do OCSP é indeterminado:

async function connectionHandler(connection) {
    var revocationStatus = connection.clientCertificate.revocationStatus;

    if (revocationStatus.certificates.leaf.status === "Error" ||
        revocationStatus.certificates.leaf.status === "Unknown") {
        // OCSP responder unreachable — allow connection (soft-fail)
        connection.logCustomData(`OCSP_SOFT_FAIL:${revocationStatus.certificates.leaf.errorType}`);
        return connection.allow();
    }

    if (revocationStatus.chainValidity === "Invalid") {
        return connection.deny();
    }

    return connection.allow();
}

Revogação de certificados com CloudFront Functions e KeyValueStore

Você pode usar as Funções de Conexão do CloudFront com o KeyValueStore para implementar a verificação de revogação de certificados sem qualquer dependência externa. Você mantém uma lista de números de série de certificados revogados em um KeyValueStore, e sua função de conexão verifica cada certificado do cliente em relação a essa lista durante o handshake TLS.

O processo de revogação de certificados funciona da seguinte maneira:

  1. O número de série dos certificados revogados é armazenado em um KeyValueStore do CloudFront.

  2. Quando um cliente apresenta um certificado, a função de conexão é invocada.

  3. A função compara o número de série do certificado com o número presente no KeyValueStore.

  4. Se o número de série for encontrado no armazenamento, o certificado será revogado.

  5. A função nega a conexão para certificados revogados.

Essa abordagem oferece uma verificação de revogação quase em tempo real na rede de borda global do CloudFront.

Para implementar essa abordagem, você precisa de:

  • Uma distribuição configurada com mTLS de visualizador.

  • Um KeyValueStore contendo números de série de certificados revogados.

  • Uma função de conexão que consulta o KeyValueStore para verificar o status do certificado.

Quando um cliente se conecta, o CloudFront valida o certificado em relação ao armazenamento confiável e, em seguida, executa a função de conexão. A função compara o número de série do certificado com o número de série no KeyValueStore e permite ou nega a conexão.

Etapa 1: criar um KeyValueStore para certificados revogados

Prepare os números de série de certificados revogados no formato JSON:

{
  "data": [
    { "key": "ABC123DEF456", "value": "" },
    { "key": "789XYZ012GHI", "value": "" }
  ]
}

Faça upload desse arquivo JSON em um bucket do S3 e, em seguida, crie o KeyValueStore:

aws s3 cp revoked-serials.json s3://your-bucket-name/revoked-serials.json

aws cloudfront create-key-value-store \
  --name revoked-serials-kvs \
  --import-source '{
    "SourceType": "S3",
    "SourceARN": "arn:aws:s3:::your-bucket-name/revoked-serials.json"
  }'

Aguarde até que o KeyValueStore conclua o provisionamento. Verifique o status com:

aws cloudfront get-key-value-store --name "revoked-serials-kvs"

Etapa 2: criar a função de conexão de revogação

Crie uma função de conexão que compare o número de série dos certificados com os números presentes no KeyValueStore:

aws cloudfront create-connection-function \
  --name "revocation-control" \
  --connection-function-config file://connection-function-config.json \
  --connection-function-code file://connection-function-code.txt

O arquivo de configuração especifica a associação do KeyValueStore:

{
  "Runtime": "cloudfront-js-2.0",
  "Comment": "A function that implements revocation control via KVS",
  "KeyValueStoreAssociations": {
    "Quantity": 1,
    "Items": [
      {
        "KeyValueStoreArn": "arn:aws:cloudfront::account-id:key-value-store/kvs-id"
      }
    ]
  }
}

Exemplo de código da função de conexão:

import cf from 'cloudfront';

async function connectionHandler(connection) {
    const kvsHandle = cf.kvs();

    // Get client serial number from client certificate
    const clientSerialNumber =
        connection.clientCertificate.certificates.leaf.serialNumber;

    // Check KVS to see if serial number exists as a key
    // Remove : from the clientSerialNumber if KVS entries dont have it
    const serialNumberExistsInKvs =
        await kvsHandle.exists(clientSerialNumber.replaceAll(":", ""));

    // Deny connection if serial number exists in KVS
    if (serialNumberExistsInKvs) {
        console.log("Connection denied — certificate revoked");
        connection.logCustomData("Connection denied — certificate revoked");
        return connection.deny();
    }

    // Allow connections that don't exist in KVS
    console.log("Connection allowed");
    return connection.allow();
}

Etapa 3: testar a função de revogação

Use o console do CloudFront para testar a função de conexão com certificados de exemplo. Acesse a função de conexão no console e use a guia “Testar”.

  • Cole um certificado de exemplo no formato PEM na interface de teste.

  • Opcionalmente, especifique um endereço IP de cliente para testar a lógica baseada em IP.

  • Selecione Testar função para visualizar os resultados da execução.

  • Analise os logs de execução para verificar a lógica de função.

Teste com certificados válidos e revogados para garantir que a função gerencie os dois cenários corretamente.

Etapa 4: associar a função à distribuição

Depois de publicar a função de conexão, associe-a à sua distribuição habilitada para mTLS para ativar a verificação de revogação de certificados. Acesse as configurações de distribuição, role até a seção "Autenticação mútua do visualizador (mTLS)", selecione sua função de conexão e salve as alterações.

Estratégias avançadas de revogação

Combine o OCSP com a lógica da função de conexão

Você pode habilitar o OCSP para verificação de revogação autorizada pela CA e adicionar uma função de conexão para políticas personalizadas. A função de conexão recebe o resultado OCSP e pode aplicar lógica adicional:

  • Períodos de carência — Permite certificados revogados de redes internas por um período definido durante a rotação de certificados.

  • Acesso de emergência — Permite conexões de IPs específicos mesmo quando o OCSP relata o status revogado.

  • Lógica de negação personalizada — Bloqueia certificados que o OCSP relata como “bons” com base em seus próprios dados de revogação no KeyValueStore.

exemplo Revogação combinada OCSP + KVS
import cf from 'cloudfront';

async function connectionHandler(connection) {
    var kvsHandle = cf.kvs();
    var revocationStatus = connection.clientCertificate.revocationStatus;
    var serialNumber = connection.clientCertificate.certificates.leaf.serialNumber;

    // Check your own revocation list first (immediate revocation, no cache delay)
    var inKvs = await kvsHandle.exists(serialNumber.replaceAll(":", ""));
    if (inKvs) {
        connection.logCustomData("KVS_REVOKED:" + serialNumber);
        return connection.deny();
    }

    // Then check OCSP result
    if (revocationStatus.chainValidity === 'Valid' && revocationStatus.certificates.leaf.status === "Revoked") {
        // OCSP says revoked — allow grace period from trusted IPs
        if (connection.clientIp.startsWith("10.0.")) {
            connection.logCustomData("GRACE_PERIOD:" + serialNumber + ":" + connection.clientIp);
            return connection.allow();
        }
        connection.logCustomData("OCSP_REVOKED:" + serialNumber);
        return connection.deny();
    }

    connection.allow();
}

Esse padrão fornece a revogação imediata via KVS (sem atraso no cache), além da revogação autorizada pela CA via OCSP, com tratamento de exceções personalizado no meio.