Opções para configurar o TLS

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

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

Versões do TLS sem suporte:a Apigee não oferece suporte ao uso do TLS 1.0 ou TLS 1.1. Se você usar esses protocolos na configuração do endpoint de destino, o endpoint de destino da Apigee vai gerar o erro messaging.adaptors.http.flow.SslHandshakeFailed.

Sobre a definição de opções de TLS em um endpoint ou servidor de destino

Um destino pode ser representado por um objeto XML como este:

<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 endpoint de destino que você modifica para configurar o TLS é definida pela tag <SSLInfo>. Use a mesma tag <SSLInfo> para configurar um endpoint ou servidor de destino.

Para saber mais sobre os elementos filhos de <SSLInfo>, consulte Configuração de TargetEndpoint de TLS/SSL.

A tabela a seguir descreve os elementos de configuração do TLS usados pela tag <SSLInfo>:

Elemento	Descrição
<Enabled>	O bloco <SSLInfo> pode ser usado para TLS/SSL unidirecional e bidirecional. Se definido como true, <Enabled> especificará que o bloco <SSLInfo> precisa ser usado. Quando definido como false, o bloco <SSLInfo> é ignorado. O valor padrão de <Enabled> é true se <URL> especificar o protocolo HTTPS e false se <URL> especificar HTTP.
<Enforce>	Aplica SSL rigoroso entre a Apigee e o back-end de destino. Se definidas como true, as conexões falharão para destinos com certificados inválidos, certificados expirados, certificados autoassinados, certificados com uma incompatibilidade de nome do host e certificados com uma raiz não confiável. Um código de falha 4xx ou 5xx é retornado. Se não for definido ou for definido como false, o resultado das conexões para back-ends de destino com certificados problemáticos dependerá da configuração de <IgnoreValidationErrors>. Confira abaixo. Uma resposta de sucesso (2xx) poderá 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 a Apigee e o cliente da API ou entre a Apigee e o back-end de destino. A ativação do TLS bidirecional exige que você configure um truststore na Apigee e um truststore.
<KeyStore>	Um keystore com chaves privadas usadas para autenticação do cliente de saída
<KeyAlias>	O alias especificado quando você fez upload de um certificado e uma chave privada para o armazenamento de chaves.
<TrustStore>	Um keystore com certificados de servidor confiáveis.
<IgnoreValidationErrors>	Indica se os erros de validação são ignorados. Se o sistema de back-end usar SNI e retornar um certificado com um nome distinto (DN, na sigla em inglês) de assunto que não corresponda ao nome do host, não será possível ignorar o erro, e a conexão falhará. Observação: se <Enforce> for definido como true, o valor de <IgnoreValidationErrors> será ignorado.
<Ciphers>	Criptografias compatíveis para TLS/SSL de saída. Se nenhuma criptografia for especificada, todas as criptografias disponíveis para o JVM serão permitidas. Para restringir as criptografias, adicione os elementos a seguir listando as criptografias compatíveis: <Ciphers> <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher> <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher> </Ciphers>
<Protocols>	Protocolos compatíveis com TLS/SSL de saída. Se nenhum protocolo for especificado, todos os protocolos disponíveis para JVM serão permitidos. Para restringir protocolos, especifique-os explicitamente. Por exemplo, para permitir apenas TLS v1.2 ou TLS v1.3: <Protocols> <Protocol>TLSv1.2</Protocol> <Protocol>TLSv1.3</Protocol> </Protocols>

Sobre a configuração dos elementos <KeyStore> e <TrustStore>

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

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

Aviso:a Apigee recomenda que você sempre use 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 o nome do keystore diretamente. Se você fizer upload de um novo certificado que não usa uma referência, mas especifica o nome do keystore diretamente, os processadores de mensagens de tempo de execução não vão detectar a mudança automaticamente. Para resolver isso, entre em contato com o suporte do Google Cloud para reiniciar os processadores de mensagens, o que pode causar uma degradação temporária do serviço.

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 truststore. Neste exemplo, o nome do truststore é myTruststore.

Quando um certificado expira, é necessário atualizar o endpoint/servidor de destino para especificar o keystore ou truststore que contém o novo certificado. No entanto, se você usar referências, poderá modificar o valor das referências para refletir os novos nomes de keystore ou truststore em vez de modificar o endpoint de destino/servidor de destino. Não é necessário entrar em contato com o Cloud Customer Care do Google Cloud para mudar o valor da referência.

Como alternativa, é possível especificar o nome do keystore e o nome do truststore diretamente:

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

Se você especificar diretamente o nome do keystore ou do truststore, entre em contato com o Suporte do Google Cloud.

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

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

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

Sobre a configuração do TLS

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

Como processar certificados expirados

Se um certificado TLS expirar ou se a configuração do sistema mudar para que o certificado não seja mais válido, será necessário atualizar o certificado. Ao configurar o TLS para um endpoint de destino/servidor de destino, decida como você executará essa atualização antes de realizar qualquer configuração.

Observação: não é possível atualizar um keystore ou truststore existente para adicionar um novo certificado. Você precisa criar um novo keystore/truststore ao atualizar um certificado. Normalmente, você cria o novo keystore/truststore e faz upload do novo certificado antes que o certificado do keystore antigo/truststore expire. Isso permite testar o novo keystore/truststore e reverter para o keystore/truststore antigo se houver algum problema.

Quando um certificado expira

Na Apigee, você armazena certificados em um destes dois locais:

• Keystore: contém o certificado TLS e a chave privada usados para identificar a entidade durante o handshake de TLS.
• Truststore: contém certificados confiáveis em um cliente TLS, usado para validar o certificado de um servidor TLS apresentado ao cliente. Em geral, esses certificados são autoassinados, assinados por uma AC confiável ou usados como parte do TLS bidirecional (também conhecido como TLS mútuo ou mTLS).

O método usado para especificar o keystore e o truststore no endpoint ou servidor de destino determina como você executa a atualização do certificado. Você pode usar referências, nomes diretos ou variáveis de fluxo. Cada método tem diferentes repercussões no processo de atualização, conforme descrito na tabela a seguir:

Tipo de configuração	Como atualizar/substituir certificado	Uso / Impacto
Referência (recomendado)	Keystore:crie um keystore com um novo nome e um alias com o mesmo nome do alias antigo. Truststore:crie uma truststore com um novo nome. O nome do alias não importa. Observação:se um certificado fizer parte de uma cadeia, você precisará criar um único arquivo contendo todos os certificados e fazer o upload desse arquivo para um único alias ou fazer o upload de todos os certificados da cadeia separadamente para o truststore usando um alias diferente para cada certificado.	Atualize a referência para apontar para o novo repositório. Não é necessário entrar em contato com o suporte da Apigee. Sem inatividade.
Variável de fluxo	Keystore:crie um keystore com um novo nome e um alias com o mesmo nome ou um novo. Truststore:crie uma truststore com um novo nome.	Transmita a variável de fluxo atualizada em cada solicitação com o nome da nova loja. Não é necessário entrar em contato com o suporte da Apigee. Sem inatividade.
Direto	Método 1: criar um novo repositório (recomendado para evitar inatividade) Crie um novo keystore ou truststore com um novo nome e faça upload do novo certificado (e da chave privada, se estiver criando um keystore).	Atualize a configuração do endpoint ou servidor de destino para especificar diretamente o novo nome da loja e implante novamente o proxy de API. Não é necessário entrar em contato com o suporte da Apigee.
Direto	Método 2a: atualização no local (excluir e recriar) Exclua o keystore ou o truststore e crie-o novamente com o mesmo nome.	As solicitações de API vão falhar durante o período de exclusão e recriação. Como os processadores de mensagens armazenam em cache as lojas especificadas diretamente, eles não detectam automaticamente o certificado atualizado. Você precisa entrar em contato com o Suporte do Google Cloud para reiniciar os processadores de mensagens.
Direto	Método 2b: atualização no local (upload do Truststore) Para truststores apenas, faça upload de um novo certificado diretamente para o truststore atual.	Como os processadores de mensagens armazenam em cache as lojas especificadas diretamente, eles não detectam o novo certificado automaticamente. Você precisa entrar em contato com o Suporte do Google Cloud para reiniciar os processadores de mensagens.