Esta página foi traduzida pela API Cloud Translation.

Como configurar o acesso TLS a uma API para a nuvem privada

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Um host virtual no Edge define os domínios e as portas em que um proxy de API é exposto e, por extensão, o URL que os apps usam para acessar um proxy de API.

Um host virtual também define se o proxy de API é acessado usando o protocolo HTTP ou pelo protocolo HTTPS criptografado que usa TLS. Ao configurar um host virtual para usar HTTPS e TLS, crie um host virtual no Edge e configure-o para usar um keystore e um truststore.

Saiba mais:

Observações:

Este artigo de produto do Cloud lista criptografias SSL válidas para o TLS 1.2: Análise empírica de valores válidos para ssl_ciphers do VirtualHost para teste de TLS 1.2 (em inglês).
A partir do Edge para nuvem privada versão 4.16.01, você precisa especificar um alias de host ao criar um host virtual. Nas versões anteriores à 4.16.01, o alias do host era opcional.
A combinação de nome do alias do host e número da porta para o host virtual precisa ser exclusiva para todos os hosts virtuais na instalação do Edge.
Se você configurar um número de porta (diferente de 80 ou 443), ele precisa ser exclusivo e não pode ter uma configuração de porta sobreposta a um host atual.
Se a instalação usar um balanceador de carga e ele for responsável por lidar com o tráfego criptografado, ainda será necessário criar o host virtual. No entanto, sua configuração de rede determinará se o host virtual precisa ou não oferecer suporte a TLS entre o balanceador de carga e o roteador. Consulte Como usar o TLS em uma instalação de nuvem privada para saber mais.

Requisitos para criar um host virtual

Antes de criar um host virtual, você precisa ter as seguintes informações:

O nome de domínio público do host virtual. Por exemplo, saiba se o nome público é api.myCompany.com, myapi.myCompany.com etc. Essas informações são usadas quando você cria o host virtual e também quando cria o registro DNS para ele.
Para o TLS unidirecional, você precisa criar um keystore em que ele contenha o seguinte:
- Certificado TLS: um certificado assinado por uma autoridade de certificação (CA, na sigla em inglês) ou uma cadeia de certificados em que o último é assinado por uma CA.
- Chave privada: o Edge oferece suporte a tamanhos de chaves de até 2.048 bits. A senha longa é opcional.
Para TLS bidirecional, você precisa de um keystore e de um truststore para manter o certificado do cliente e, opcionalmente, a cadeia de CAs do certificado. Você precisa do truststore mesmo que o certificado seja assinado por uma CA.

Consulte Keystores e Truststores para mais informações sobre como criar keystores e truststores.

Configuração do host virtual para TLS

Para criar um host virtual, crie um objeto XML que defina o host virtual. O objeto XML a seguir usa o elemento <SSLInfo> para definir um host virtual para uma configuração de TLS unidirecional por HTTPS:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Observação:como o Edge era compatível com SSL, a tag que você usa para configurar o TLS é chamada de <SSLInfo>.

Nesse exemplo, o elemento <Enabled> é definido como verdadeiro para ativar o TLS unidirecional, e os elementos <KeyStore> e <KeyAlias> especificam o keystore e a chave usados pela conexão TLS.

Para ativar o TLS bidirecional, defina o elemento <ClientAuthEnabled> como true e especifique um truststore usando o elemento <TrustStore>. O truststore contém o certificado do cliente e, opcionalmente, a cadeia de CAs do certificado.

Como decidir como especificar o nome do keystore e do truststore no host virtual

No exemplo de host virtual acima, você especificou o keystore usando uma referência. Uma referência é uma variável que contém o nome do keystore, em vez de o especificar diretamente.

A vantagem de usar uma referência é que você pode alterar o valor da referência para alterar o keystore usado pelo host virtual, geralmente porque o certificado no keystore atual vai expirar em um futuro próximo. Alterar o valor da referência não exige que você reinicie o roteador de borda.

Como alternativa, é possível usar um nome de keystore literal no host virtual. No entanto, se você modificar o host virtual para alterar o nome do keystore, precisará reiniciar os roteadores de borda.

Restrições ao uso de referências a keystores e truststore

Considere a seguinte restrição ao usar referências a keystores e truststores:

Só é possível usar referências de keystore e truststore em hosts virtuais se você oferecer suporte à SNI e encerrar o SSL nos roteadores da Apigee.
Se você tiver um balanceador de carga na frente dos roteadores da Apigee e encerrar o TLS no balanceador de carga, não será possível usar as referências de keystore e truststore em hosts virtuais.

Como modificar um host virtual existente para usar referências ao keystore e ao truststore

A Apigee recomenda que os hosts virtuais usem referência a keystores e truststores. As referências permitem alterar o keystore e o truststore usados pelo host virtual sem precisar reiniciar os roteadores de borda.

Se os hosts virtuais estiverem configurados para usar o nome literal do keystore ou do truststore, você poderá convertê-los para usar referências. Para isso, atualize o host virtual para usar referências e reinicie os roteadores de borda.

Como definir as criptografias e os protocolos TLS para o Edge 4.15.07 e versões anteriores

Se você estiver usando o Edge versão 4.15.07 e anterior, defina o protocolo TLS e as criptografias usadas pelo host virtual com as tags filhas <Ciphers> e <Protocols> da tag <SSLInfo>. Essas tags são descritas na tabela abaixo.

Exemplo:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

A tag <Cipher> usa os nomes Java e JSSE da cifra. Por exemplo, para Java 8, consulte http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites.

Como especificar criptografias e protocolos TLS para o Edge 4.16.01 a 4.16.09

No Edge 4.16.01 a 4.16.09, você define as criptografias e protocolos padrão para hosts virtuais globalmente no roteador. Esses padrões serão aplicados a todos os hosts virtuais.

Use tokens para especificar os protocolos e as criptografias padrão:

Para especificar os protocolos padrão, use o token conf_load_balancing_load.balancing.driver.server.ssl.protocols
Para especificar as criptografias padrão para o roteador, use o token conf_load_balancing_load.balancing.driver.server.ssl.ciphers

O valor padrão do token conf_load_balancing_load.balancing.driver.server.ssl.protocols é:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

Esta configuração especifica que o roteador oferece suporte às versões 1.0, 1.1 e 1.2 do TLS. Especifique uma lista de valores delimitada por espaços para o token.

O valor padrão do token conf_load_balancing_load.balancing.driver.server.ssl.ciphers é:

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

Essa configuração especifica:

O comprimento da chave é de 128 bits ou mais (HIGH).
Excluir criptografias sem autenticação (!aNULL)
Excluir pacotes de criptografia usando MD5 (!MD5)
Excluir pacotes de criptografia usando DH (incluindo DH anônimo, DH temporário e DH fixo) E DES triplo (!DH+3DES)
Excluir pacotes de criptografia usando a troca de chaves RSA E DES triplo (!RSA+3DES)

Para saber mais sobre a sintaxe e os valores permitidos por esse token, consulte Criptografias de OpenSSL. Esse token usa os nomes de criptografia OpenSSL, como AES128-SHA256, e não os nomes de criptografia Java/JSSE, como TLS_RSA_WITH_AES_128_CBC_SHA256.

Para definir o token para o roteador:

Edite o arquivo /opt/apigee/customer/application/router.properties. Se esse arquivo não existir, crie-o.
Defina o token conf_load_balancing_load.balancing.driver.server.ssl.ciphers. Por exemplo, para especificar apenas o TLSv1.2 e excluir pacotes de criptografia que usam chaves pré-compartilhadas, adicione!PSK:
```
conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK
```
Verifique se o arquivo router.properties é de propriedade da Apigee:
```
chown apigee:apigee /opt/apigee/customer/application/router.properties
```

Reinicie o roteador de borda:

/opt/apigee/apigee-service/bin/apigee-service edge-router restart

Verifique o valor do token:

/opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Como configurar parâmetros de host virtual TLS para a versão 4.17.01 e mais recentes do Edge

Se você estiver usando o Edge versão 4.17.01 e mais recente, poderá definir algumas propriedades TLS para um host virtual individual, como criptografia e protocolo TLS, usando a tag filha <Properties> da tag <VirtualHost>. Essas tags são descritas em Referência de propriedades do host virtual.

Exemplo:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

Para saber mais sobre a sintaxe e os valores permitidos pelo token ssl_ciphers, consulte Criptografias de OpenSSL. Esse token usa os nomes de criptografia OpenSSL, como AES128-SHA256, e não os nomes de criptografia Java/JSSE, como TLS_RSA_WITH_AES_128_CBC_SHA256.

Como criar um host virtual que usa HTTPS

Neste exemplo, usamos uma referência para especificar o keystore para o host virtual. O uso de uma referência permite mudar o keystore sem precisar reiniciar os roteadores.

Siga o procedimento abaixo para criar o host virtual:

Crie e configure um keystore chamado myTestKeystore usando o procedimento descrito aqui: Keystores e Truststores. Verifique se o keystore usa um nome de alias myKeyAlias para o certificado e a chave privada.

Use a seguinte chamada de API POST para criar a referência chamada keystoreref para o keystore que você criou acima:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

A referência especifica o nome do keystore e o tipo de referência como KeyStore.

Use a chamada GET API a seguir para visualizar a referência:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Crie o host virtual usando a API Create a Virtual Host, em que <ms-IP> é o endereço IP ou o nome de domínio do nó do servidor de gerenciamento.

Certifique-se de especificar a referência correta do keystore e o alias da chave:
```
curl -X POST -H "Content-Type:application/xml" \
  http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
  -d '<VirtualHost  name="newTLSTrustStore2">
    <HostAliases>
      <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9005</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>false</ClientAuthEnabled>
      <KeyStore>ref://keystoreref</KeyStore>
      <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
  </VirtualHost>' \
  -u email:password
```
Observação : se você estiver executando o TLS bidirecional com o cliente, defina <ClientAuthEnabled> como true e especifique o truststore usando o elemento <TrustStore>. O cliente precisa ser configurado corretamente para o TLS bidirecional, o que significa que o Edge tem um truststore que contém o certificado e a cadeia de certificados do cliente. Crie o truststore usando o procedimento descrito aqui: Keystores e Truststores.
Crie um registro DNS para o host virtual que corresponda ao alias do host.
Se você tiver proxies de API, adicione o host virtual ao elemento <HTTPConnection> no ProxyEndpoint. O host virtual é adicionado automaticamente a todos os novos proxies de API.

Consulte Como atualizar um proxy de API depois de criar um host virtual em Sobre hosts virtuais.

Aviso:todos os hosts virtuais são adicionados automaticamente a todos os novos proxies de API. Portanto, se você criar um novo proxy de API que não possa ser acessado por um host virtual específico, edite-o para remover esse host virtual do ProxyEndpoint.

Depois de atualizar um proxy de API para usar o host virtual e criar o registro DNS para o alias do host, é possível acessar o proxy de API conforme mostrado abaixo:

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

Exemplo:

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

Como criar e modificar referências a um keystore ou um truststore

Opcionalmente, você pode configurar o host virtual para usar uma referência ao keystore ou truststore. A vantagem de usar uma referência é que você pode atualizá-la para apontar para um keystore ou truststore diferente para atualizar o certificado TLS sem precisar reiniciar um roteador.

Por exemplo, o host virtual abaixo usa uma referência ao keystore:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Use a seguinte chamada da API POST para criar a referência chamada keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

A referência especifica o nome e o tipo do keystore.

Use a chamada GET API a seguir para visualizar a referência:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Posteriormente, para alterar a referência e apontar para um keystore diferente, verifique se o alias tem o mesmo nome e use a seguinte chamada PUT:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password