Opções para configurar o protocolo TLS

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Esta secção mostra como configurar o TLS para o tráfego de um proxy para um destino.

Acerca da definição das opções de TLS num ponto final de destino ou num servidor de destino

Um alvo pode ser representado por um objeto XML como o abaixo:

<HTTPTargetConnection>
    <Properties/>
    <URL>https:myTargetAddress</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <Enforce>true</Enforce>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTruststoreRef</TrustStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <Protocols>myProtocols</Protocols>
        <Ciphers>myCipher</Ciphers>
    </SSLInfo>
</HTTPTargetConnection>

A área da configuração do ponto final de destino que modifica para configurar o TLS é definida pela etiqueta <SSLInfo>. Usa a mesma etiqueta <SSLInfo> para configurar um ponto final de destino ou um servidor de destino.

Para obter informações sobre os elementos subordinados de <SSLInfo>, consulte Configuração do TargetEndpoint TLS/SSL.

A tabela seguinte descreve os elementos de configuração do TLS usados pela etiqueta <SSLInfo>:

Elemento Descrição
<Enabled> O bloco <SSLInfo> pode ser usado para TLS/SSL unidirecional e bidirecional.

Se estiver definido como true, <Enabled> especifica que deve ser usado o bloco <SSLInfo>. Quando definida como false, o bloco <SSLInfo> é ignorado.

O valor predefinido de <Enabled> é true se <URL> especificar o protocolo HTTPS, e false se <URL> especificar HTTP.
<Enforce>

Aplica SSL rigoroso entre o Apigee e o back-end de destino.

Se estiver definido como true, as ligações falham para alvos com certificados inválidos, certificados expirados, certificados autoassinados, certificados com uma incompatibilidade de nome de anfitrião e certificados com uma raiz não fidedigna. É devolvido um código de falha de 4xx ou 5xx.

Se não estiver definido ou estiver definido como false, o resultado das ligações aos back-ends de destino com certificados problemáticos depende da definição de <IgnoreValidationErrors> (veja abaixo). Uma resposta de sucesso (2xx) pode ocorrer em determinadas condições, se <IgnoreValidationErrors> estiver definido como true.
<ClientAuthEnabled>

Ativa o TLS bidirecional (também conhecido como TLS mútuo ou mTLS) entre o Apigee e o cliente da API ou entre o Apigee e o back-end de destino.

A ativação do TLS bidirecional requer normalmente que configure um truststore no Apigee e um truststore.
<KeyStore> Um repositório de chaves que contém chaves privadas usadas para a autenticação de clientes de saída
<KeyAlias> O alias especificado quando carregou um certificado e uma chave privada para o repositório de chaves.
<TrustStore> Um keystore que contém certificados de servidor fidedignos.
<IgnoreValidationErrors>

Indica se os erros de validação são ignorados. Se o sistema de back-end usar SNI e devolver um certificado com um nome distinto (DN) do assunto que não corresponda ao nome do anfitrião, não há forma de ignorar o erro e a ligação falha.

Nota: se <Enforce> estiver definido como true, o valor de <IgnoreValidationErrors> é ignorado.
<Ciphers>

Cifras compatíveis para TLS/SSL de saída. Se não forem especificados cifrões, todos os cifrões disponíveis para a JVM são permitidos.

Para restringir cifras, adicione os seguintes elementos que indicam as cifras suportadas:

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
<Protocols>

Protocolos suportados para TLS/SSL de saída. Se não forem especificados protocolos, todos os protocolos disponíveis para a JVM são permitidos.

Para restringir protocolos, especifique-os explicitamente. Por exemplo, para permitir apenas o TLS v1.2 ou o TLS v1.3:

<Protocols>
 <Protocol>TLSv1.2</Protocol>
 <Protocol>TLSv1.3</Protocol>
</Protocols>

Acerca da definição dos elementos <KeyStore> e <TrustStore>

No exemplo acima, o keystore e o truststore são especificados através de referências, no formato:

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

A Apigee recomenda vivamente que use sempre referências ao keystore e ao truststore. Uma referência é uma variável que contém o nome do keystore ou do truststore, em vez de especificar diretamente o nome do keystore. Neste exemplo:

  • myKeystoreRef é uma referência que contém o nome do keystore. Neste exemplo, o nome do keystore é myKeystore.
  • myTruststoreRef é uma referência que contém o nome do repositório de confiança. Neste exemplo, o nome do repositório de confiança é myTruststore.

Quando um certificado expira, tem de atualizar o ponto final de destino/servidor de destino para especificar o keystore ou o truststore que contém o novo certificado. A vantagem de uma referência é que pode modificar o valor da referência para alterar o keystore ou o truststore sem ter de modificar o próprio ponto final/servidor de destino:

A alteração do valor da referência não requer que contacte o apoio ao cliente do Google Cloud.

Em alternativa, pode especificar diretamente o nome do keystore e o nome do truststore:

<KeyStore>myKeystore</KeyStore>
<TrustStore>myTruststore</TrustStore>

Se especificar diretamente o nome do keystore ou do truststore, tem de contactar o apoio técnico do Google Cloud.

Uma terceira opção é usar variáveis de fluxo:

<KeyStore>{ssl.keystore}</KeyStore>
<TrustStore>{ssl.truststore}</TrustStore>

Pode usar variáveis de fluxo para especificar dinamicamente um keystore ou um truststore, com um efeito semelhante ao uso de uma referência. Para mais informações, consulte Usar variáveis de fluxo para definir dinamicamente os valores de TLS/SSL.

Acerca da configuração do TLS

Todos os clientes do Apigee, pagos e de avaliação, têm controlo total sobre a configuração dos pontos finais/servidores de destino. Além disso, os clientes do Apigee pagos têm controlo total sobre as propriedades TLS.

Processamento de certificados expirados

Se um certificado TLS expirar ou se a configuração do sistema for alterada de modo que o certificado deixe de ser válido, tem de atualizar o certificado. Quando configurar o TLS para um ponto final/servidor de destino, deve decidir como vai fazer essa atualização antes de fazer qualquer configuração.

Quando um certificado expira

No Apigee, armazena certificados num de dois locais:

  • Keystore: contém o certificado TLS e a chave privada usados para identificar a entidade durante o handshake TLS.
  • Truststore: contém certificados fidedignos num cliente TLS usados para validar o certificado de um servidor TLS apresentado ao cliente. Normalmente, estes certificados são certificados autoassinados, certificados assinados por uma CA fidedigna ou certificados usados como parte do TLS bidirecional (também conhecido como TLS mútuo ou mTLS).

Quando um certificado num repositório de chaves expira e está a usar uma referência ao repositório de chaves, não pode carregar um novo certificado para o repositório de chaves. Em alternativa:

  1. Crie um novo keystore.
  2. Carregue o novo certificado para o novo keystore com o mesmo nome de alias que no keystore antigo.
  3. Atualize a referência no servidor de destino/ponto final de destino para usar o novo keystore.

Quando um certificado num arquivo de confiança expira e está a usar uma referência ao arquivo de confiança:

  1. Crie um novo repositório de confiança.
  2. Carregue o novo certificado para o novo repositório de confiança. O nome do alias não é importante para os repositórios de confiança. Nota: se um certificado fizer parte de uma cadeia, tem de criar um único ficheiro com todos os certificados e carregar esse ficheiro para um único alias ou carregar todos os certificados na cadeia separadamente para o truststore com um alias diferente para cada certificado.
  3. Atualize a referência no servidor de destino/ponto final de destino para usar o novo truststore.

Resumo dos métodos para atualizar um certificado expirado

O método que usa para especificar o nome do keystore e do truststore no endpoint de destino/servidor de destino determina como faz a atualização do certificado. Pode usar:

  • Referências
  • Nomes diretos
  • Variáveis de fluxo

Cada um destes métodos tem repercussões diferentes no processo de atualização, conforme descrito na tabela seguinte:

Tipo de configuração Como atualizar/substituir o certificado Utilização
Referência (recomendado) Para um repositório de chaves, crie um novo repositório de chaves com um novo nome e um alias com o mesmo nome que o alias antigo.

Para um repositório de confiança, crie um repositório de confiança com um novo nome.

 Atualize a referência ao keystore ou truststore.

Não é necessário contactar o apoio técnico do Apigee.
Variável de fluxo Para um repositório de chaves, crie um novo repositório de chaves com um novo nome e um alias com o mesmo nome ou com um novo nome.

Para um repositório de confiança, crie um repositório de confiança com um novo nome.

 Transmita a variável de fluxo atualizada em cada pedido com o nome do novo keystore, alias ou truststore.

Não é necessário contactar o apoio técnico do Apigee.
Direto Crie um novo keystore, alias e truststore. Volte a implementar o proxy.
Direto Elimine o keystore ou o truststore e recrie-o com o mesmo nome. Os pedidos da API vão falhar até que o novo keystore e alias sejam definidos.

Se o keystore for usado para o TLS bidirecional (também conhecido como TLS mútuo ou mTLS) entre o Apigee e o serviço de back-end, contacte o apoio técnico do Google Cloud para reiniciar os processadores de mensagens.
Direto Para o repositório de confiança, carregue um novo certificado para o repositório de confiança. Contacte o apoio técnico do Google Cloud para reiniciar os processadores de mensagens.