Como acessar informações de conexão TLS em um proxy de API

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

O Edge permite criar hosts virtuais com suporte a TLS unidirecional e bidirecional. Com o TLS de mão única, o cliente emite uma solicitação de sessão para um host virtual implantado em um roteador de borda, e o roteador responde com um certificado que contém a chave pública do host virtual. No caso de um certificado assinado, o cliente pode fazer uma solicitação à autoridade de certificação (CA, na sigla em inglês) para autenticar o certificado.

No TLS bidirecional, o cliente e o Edge transmitem certificados que são validados como parte de uma solicitação:

  • O roteador de borda apresenta o certificado ao cliente TLS para se autenticar. Em seguida, o cliente verifica a identidade do servidor antes de enviar o certificado para ele.
  • O cliente TLS apresenta o certificado ao Edge para se autenticar.

Consulte Sobre hosts virtuais para mais informações.

Como capturar informações de conexão TLS

Durante uma solicitação a um proxy de API por um host virtual compatível com TLS, o Edge pode capturar informações sobre a conexão TLS. O proxy de API pode acessar essas informações por meio de variáveis de fluxo para realizar análises e validação adicionais.

O tipo de informação TLS capturada pelo Edge depende da compatibilidade do host virtual com TLS unidirecional ou bidirecional. Por exemplo, para o TLS unidirecional, o Edge pode capturar informações sobre a criptografia TLS ou o protocolo TLS usado na conexão TLS.

Para TLS bidirecional, o Edge pode capturar todas as mesmas informações capturadas para TLS unidirecional e também capturar informações sobre o certificado do cliente. Por exemplo, o Edge pode capturar a impressão digital SHA1 do certificado do cliente e do certificado do cliente no formato PEM.

Capturar informações para TLS unidirecional e bidirecional

Na tabela a seguir, listamos as variáveis de fluxo que contêm informações de conexão TLS capturadas pelo Edge e disponíveis para acesso no proxy de API. Essas informações são capturadas para TLS unidirecional e bidirecional configurando <ConnectionProperties> como verdadeiro na definição do host virtual:

Variável Flow Descrição
tls.cipher A criptografia usada pela conexão TLS.
tls.protocol O protocolo usado pela conexão TLS.
tls.server.name O nome do servidor SNI solicitado.
tls.session.id

O identificador da sessão.

Essa variável de fluxo está disponível quando você define <ConnectionProperties> ou <ClientProperties> ou como "true".

Como capturar informações adicionais de TLS durante a TLS bidirecional

Na tabela a seguir, listamos as variáveis de fluxo que contêm detalhes do certificado do cliente capturados pelo Edge em TLS bidirecional. Essas informações são capturadas para TLS bidirecional configurando <ClientProperties> como verdadeiro na definição de host virtual:

Variável Flow Descrição
tls.client.s.dn O nome distinto (DN, na sigla em inglês) do assunto que identifica o certificado do cliente.
tls.client.i.dn O nome distinto (DN, na sigla em inglês) do emissor do certificado do cliente.
tls.client.raw.cert O certificado do cliente no formato PEM.
tls.client.cert.serial O número de série do certificado do cliente.
tls.client.cert.fingerprint Impressão digital SHA1 do certificado do cliente.
tls.session.id

O identificador da sessão.

Essa variável de fluxo está disponível quando você define <ConnectionProperties> ou <ClientProperties> como "true".

Como configurar um host virtual para capturar informações de TLS

Para configurar o host virtual para capturar informações de TLS, defina as seguintes propriedades em <PropagateTLSInformation> como true.

  • <ConnectionProperties>: ativa a captura de informações de conexão TLS para TLS unidirecional e bidirecional. O valor padrão é false.
  • <ClientProperties>: ativa a captura de mais informações para TLS bidirecional. O valor padrão é false.

Por exemplo, a definição de host virtual a seguir usa TLS bidirecional e permite a captura de ambos os tipos de informações TLS:

<VirtualHost name="secure">
    ....
    <SSLInfo>
        <Enabled>true</Enabled>
        # Enable two-way TLS.
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <KeyAlias>ks-alias</KeyAlias>
        <KeyStore>ref://ks-ref</KeyStore>
        <TrustStore>ref://ts-ref</TrustStore>
    </SSLInfo>
    <PropagateTLSInformation>
        <ConnectionProperties>true</ConnectionProperties>
        <ClientProperties>true</ClientProperties>
    </PropagateTLSInformation>
</VirtualHost>

Se você estiver transmitindo um corpo JSON, defina as propriedades como:

  "propagateTLSInformation" : {
    "connectionProperties" : true,
    "clientProperties" : true
  }

Definir limites de tamanho de cabeçalho

Quando você ativa a captura de informações TLS em um host virtual, o Edge transmite essas informações usando cabeçalhos HTTP. Portanto, verifique se os limites de tamanho do cabeçalho estão definidos corretamente com base no uso do Edge para a nuvem ou do Edge para a nuvem privada:

  • Edge para a nuvem: a Apigee define os tamanhos de cabeçalho corretamente.
  • Edge para a nuvem privada: recurso não disponível.

Como acessar as variáveis de fluxo em um proxy de API

No proxy de API, é possível acessar e inspecionar as variáveis de fluxo TLS. Por exemplo, é possível usar a política AssignMessage para acessá-los e em JavaScript com a política de JavaScript.

Você também pode referenciar as variáveis de fluxo em um elemento <Condition> de um proxy ou fluxo de destino, ou em um <Step> ou <RouteRule>. Por exemplo, é possível encaminhar uma solicitação para destinos diferentes com base no SN do cliente.

Para mais informações, consulte: