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

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

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

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

  • O Edge Router apresenta o certificado ao cliente TLS para que ele faça a própria autenticação. Em seguida, o cliente verifica a identidade do servidor antes de enviar o certificado a 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 para um proxy de API por um host virtual que oferece suporte a TLS, o Edge pode capturar informações sobre a conexão TLS. O proxy de API pode acessar essas informações em variáveis de fluxo para realizar análise e validação adicionais.

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

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

Como capturar informações para TLS unidirecional e bidirecional

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

Variável de fluxo 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> como verdadeiro.

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

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

Variável de fluxo 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 verdadeiro.

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

Para configurar o host virtual para capturar informações TLS, defina as propriedades a seguir 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 informações adicionais para TLS bidirecional. O valor padrão é false.

Por exemplo, a definição de host virtual a seguir usa TLS bidirecional e ativa a captura dos dois 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 do 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, é necessário garantir que os limites de tamanho do cabeçalho sejam definidos de acordo com o uso do Edge para Cloud ou do Edge para nuvem privada:

  • Edge para Cloud: o Apigee define os tamanhos de cabeçalho de maneira adequada.
  • Edge para 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, use a política AssignMessage para acessá-las ou acesse-as em JavaScript com a política JavaScript.

Também é possível 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: