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

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Um host virtual no Edge define os domínios e 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 pode ser acessado usando o protocolo HTTP ou pelo protocolo HTTPS criptografado que usa TLS. Ao configurar um host virtual para usar HTTPS e TLS, você cria um host virtual no Edge e o configura para usar um keystore e truststore.

Saiba mais:

• Sobre TLS/SSL
• Como usar o TLS com o Edge
• Sobre hosts virtuais
• Como configurar hosts virtuais para a nuvem privada
• Referência de propriedade do host virtual
• Keystores e truststores

O que é necessário 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, você precisa saber se o nome público é api.myCompany.com, myapi.myCompany.com etc. Essas informações são usadas ao criar o host virtual e também ao criar o registro DNS para o host virtual.
• Para TLS unidirecional, é necessário criar um keystore que contenha o seguinte:
  • Certificado TLS: um certificado assinado por uma autoridade de certificação (CA) ou uma cadeia de certificados em que o último certificado é assinado por uma CA.
  • Chave privada: o Edge oferece suporte a tamanhos de chave de até 2048 bits. Uma senha longa é opcional.
• Para TLS bidirecional, você precisa de um keystore e um truststore para armazenar o certificado do cliente e, opcionalmente, a cadeia de CA 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 o defina. O objeto XML a seguir usa o <SSLInfo> elemento 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>

Neste exemplo, o elemento <Enabled> está definido como "true" 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 <ClientAuthEnabled> elemento como true, e especifique um truststore usando o <TrustStore> elemento. O truststore contém o certificado do cliente e, opcionalmente, a cadeia de CA do certificado.

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 especificar o nome do keystore diretamente.

A vantagem de usar uma referência é poder mudar o valor da referência para alterar o keystore usado pelo host virtual, geralmente porque o certificado no keystore atual expira em breve. Não é necessário reiniciar o roteador de borda para alterar o valor da referência.

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

Restrições ao usar referências a keystores e truststores

É necessário considerar a seguinte restrição ao usar referências a keystores e truststores:

• Só é possível usar referências a keystore e truststore em hosts virtuais se você oferecer suporte a 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, não será possível usar as referências do keystore e truststore em hosts virtuais.

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

A Apigee recomenda que os hosts virtuais usem referências a keystores e truststores. As referências permitem mudar 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 truststore, você poderá convertê-los para usar referências. Para fazer 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 versões anteriores, defina o protocolo TLS e as criptografias usadas pelo host virtual usando 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 o nome Java e JSSE da criptografia. Por exemplo, para Java 8, consulte http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites (link em inglês).

Como especificar as criptografias e os 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 os protocolos padrão para hosts virtuais globalmente no roteador. Esses padrões sã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 do 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

Essa 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 delimitados por espaço 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:

• Comprimento da chave de 128 bits ou mais necessário (HIGH).
• Excluir criptografias sem autenticação (!aNULL)
• Excluir conjuntos de criptografia usando MD5 (!MD5)
• Excluir conjuntos de criptografia usando DH (incluindo DH anônimo, DH efêmero e DH fixo) E DES triplo (!DH+3DES)
• Excluir conjuntos de criptografia usando troca de chaves RSA E DES triplo (!RSA+3DES)

Para informações sobre a sintaxe e os valores permitidos por esse token, consulte Criptografias 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 do roteador:

1. Edite o arquivo /opt/apigee/customer/application/router.properties. Se esse arquivo não existir, crie-o.
2. Defina o conf_load_balancing_load.balancing.driver.server.ssl.ciphers token. Por exemplo, para especificar apenas TLSv1.2 e excluir conjuntos de criptografia usando 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

3. Verifique se o arquivo router.properties pertence ao apigee:

   chown apigee:apigee /opt/apigee/customer/application/router.properties

4. Reinicie o roteador de borda:

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

5. 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 definir parâmetros de host virtual TLS para o Edge versão 4.17.01 e mais recentes

Se você estiver usando o Edge versão 4.17.01 e mais recentes, poderá definir algumas propriedades TLS para um host virtual individual, como protocolo TLS e criptografia, usando a tag filha <Properties> da <VirtualHost> tag. Essas tags são descritas em Referência de propriedade 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 informações sobre a sintaxe e os valores permitidos pelo token ssl_ciphers, consulte Criptografias OpenSSL (link em inglês). 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

Este exemplo especifica o keystore para o host virtual usando uma referência. O uso de uma referência permite mudar o keystore sem precisar reiniciar os roteadores.

Use o procedimento a seguir para criar o host virtual:

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

2. Use a seguinte chamada de API POST para criar a referência nomeada keystoreref ao keystore criado 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 de API GET 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
   

3. 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.

   Especifique a referência de keystore e o alias de chave corretos:

   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

4. Crie um registro DNS para o host virtual que corresponda ao alias de host.

5. 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 após criar um host virtual em Sobre hosts virtuais.

Depois de atualizar um proxy de API para usar o host virtual e criar o registro DNS para o alias de host , você poderá 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 truststore

Você tem a opção de configurar o host virtual para usar uma referência ao keystore ou truststore. A vantagem de usar uma referência é poder atualizá-la para apontar para um keystore ou truststore diferente para atualizar o certificado TLS sem precisar reiniciar um roteador.

Por exemplo, abaixo é mostrado um host virtual que 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 de 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 de API GET 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