API Safe Browsing Oblivious HTTP Gateway
Observação: esta documentação ainda está em desenvolvimento. Espere melhorias em breve.
A API Oblivious HTTP Gateway da Navegação segura é uma API que preserva a privacidade criada com base no protocolo RFC IETF chamado Oblivious HTTP, RFC 9458.
Visão geral
A API Oblivious HTTP Gateway da Navegação segura é um serviço do Google que permite que aplicativos clientes verifiquem URLs nas listas de recursos inseguros da Web do Google, constantemente atualizadas, com proteções de privacidade adicionais em vigor.
Isso é possível por meio de um protocolo leve chamado HTTP Oblivious ou OHTTP. Esse é um protocolo sem estado que pode ser usado por clientes da Navegação segura para acessar as APIs da Navegação segura do Google V5, com proteções robustas e maior cobertura sem comprometer a privacidade dos usuários.
OBSERVAÇÃO: as APIs da Navegação segura do Google V4 não podem ser acessadas por este serviço.
Protocolo HTTP Oblivious da Navegação segura
Protocolo RFC
O HTTP oblivious é um protocolo leve definido na RFC 9458 (link em inglês), usado para criptografar e enviar mensagens HTTP de um cliente para um servidor de destino. Ele usa um serviço de retransmissão confiável de maneira a atenuar o uso de metadados pelo servidor de destino, como endereço IP e informações de conexão para identificação do cliente, proporcionando privacidade e segurança além do protocolo HTTP/S simples. O protocolo usa HTTP binário, definido na RFC 9292, para codificar/decodificar solicitações/respostas HTTP.
Em um nível alto, um Relay fica entre o recurso de cliente e de gateway que faz proxy do tráfego do cliente, removendo todos os identificadores do cliente, incluindo atributos sensíveis à privacidade, como endereços IP, anonimizando de maneira eficaz as solicitações HTTP recebidas para o serviço de gateway. O benefício adicional do OHTTP é que todas as solicitações são criptografadas de ponta a ponta, o que significa que as consultas da Navegação segura dos clientes (ou seja, hashes truncados de expressões de URL) não são visíveis para o Relay. Consulte a postagem do blog (link em inglês) para ver um exemplo de implementação no Chrome.
Os clientes podem escolher qualquer provedor de redirecionamento (por exemplo, Rapidez) para fazer a integração com o serviço. O Relay precisa usar a autenticação Oauth 2.0 com o seguinte escopo de autorização para acessar o serviço.
// OAuth Authorization scope:
https://www.googleapis.com/auth/3p-relay-safe-browsing
Endpoints de API
Chave pública OHTTP
Esse endpoint vai fornecer a configuração de chave pública OHTTP conforme especificado na RFC 9458 (link em inglês), que será usada pelo cliente para criptografar a solicitação OHTTP.
GET https://safebrowsingohttpgateway.googleapis.com/v1/ohttp/hpkekeyconfig?key=<API key>
A chave de API acima não é estritamente necessária. O servidor não varia a chave pública OHTTP com base na chave de API fornecida. É permitido que os clientes investiguem esse fato usando diferentes chaves de API válidas para acessar esse ponto de extremidade ou não usando completamente nenhuma chave de API e verificando se a resposta realmente contém a mesma chave pública OHTTP. No entanto, para facilitar a depuração, é recomendável usar uma chave de API. Isso permite que os clientes acessem estatísticas como o número de solicitações no console do Google Cloud. Se o cliente pretende fornecer uma chave de API, consulte esta documentação sobre como configurá-las.
Conforme indicado na seção de recomendações de privacidade, para atender às metas de consistência principal, recomenda-se que os fornecedores de clientes configurem uma infraestrutura de distribuição de chaves centralizada para buscar a chave nesse endpoint e, em seguida, distribuí-la para os aplicativos clientes.
De acordo com as orientações sobre o gerenciamento de chaves, as chaves são alternadas regularmente no servidor. Os clientes precisam atualizar a chave, ou seja, buscar e atualizar a cópia local dela de vez em quando para evitar falhas de descriptografia.
Os clientes precisam atualizar (buscar e atualizar) a chave pública uma vez por dia. Se um mecanismo de distribuição centralizada estiver em uso, ele deve se certificar de obter e distribuir as chaves uma vez por dia.
Solicitação encapsulada OHTTP
Esse endpoint atenderá à solicitação OHTTP incluída no corpo HTTP da solicitação POST, realizando a descriptografia da solicitação e, em seguida, criptografar a resposta OHTTP para ser encaminhada de volta ao Relay na resposta HTTP. O cliente precisa incluir o cabeçalho de solicitação Content-Type como message/ohttp-req na solicitação POST HTTP.
POST https://safebrowsingohttpgateway.googleapis.com/v1/ohttp:handleOhttpEncapsulatedRequest?key=<API key>
OBSERVAÇÃO: de acordo com as orientações sobre RFC, codifique a solicitação interna (consulte a documentação da V5 sobre como criar uma solicitação de Navegação segura) usando o protocolo HTTP binário, RFC 9292.
Bibliotecas de cliente
O Google Quiche tem implementações do lado do cliente para os protocolos OHTTP e BHTTP. Recomendamos que os clientes usem essas bibliotecas. Consulte o pseudocódigo abaixo sobre como criar solicitações OHTTP para acessar a API.
Exemplo de implementação do lado do cliente
Os clientes buscam a chave pública HTTP Oblivious no endpoint da chave pública. Em seguida, inicialize a configuração da chave OHTTP quiche e inicialize o cliente OHTTP quiche.
auto ohttp_key_cfgs = quiche::ObliviousHttpKeyConfigs::ParseConcatenatedKeys(std::string public_key);
auto key_config = ohttp_key_cfgs->PreferredConfig();
auto public_key = ohttp_key_cfgs->GetPublicKeyForId(key_config.GetKeyId())
auto ohttp_client = quiche::ObliviousHttpClient::Create(public_key, key_config);
O cliente vai usar a codificação HTTP binária para criar uma solicitação BHTTP como primeira etapa antes da criptografia.
quiche::BinaryHttpRequest::ControlData bhttp_ctrl_data{
.method = "POST",
.scheme = "https",
.authority = "safebrowsing.googleapis.com",
.path = "/v5/hashes:search?key=<API key>&hashPrefixes=<HASH prefix 1>&hashPrefixes=<HASH prefix 2>",
};
quiche::BinaryHttpRequest bhttp_request(bhttp_ctrl_data);
Em seguida, o cliente vai criptografar a solicitação HTTP binária criada na etapa acima.
auto bhttp_serialized = bhttp_request.Serialize();
auto ohttp_request = ohttp_client.CreateObliviousHttpRequest(*bhttp_serialized);
// Client must include this in POST body, and add `Content-Type` header as "message/ohttp-req".
auto payload_include_in_post_body = ohttp_request.EncapsulateAndSerialize();
Depois que a resposta é recebida do Relay, o cliente a descriptografa. A resposta incluirá o cabeçalho de resposta Content-Type como ohttp-res.
auto ctx = std::move(ohttp_request).ReleaseContext();
auto ohttp_response = ohttp_client.DecryptObliviousHttpResponse("data included in body of http_response", ctx);
Depois de descriptografar a resposta OHTTP, decodifique a saída usando HTTP binário da seguinte maneira.
auto bhttp_response = BinaryHttpResponse::Create(ohttp_response.GetPlaintextData());
if (bhttp_response.status_code() == 200) {
auto http_response = bhttp_response.body();
auto response_headers = bhttp_response.GetHeaderFields();
}