Descriptografar confirmações de preço

Quando seu criativo ganha um leilão, o Google pode informar qual foi o preço vencedor se o criativo incluir a macro ${AUCTION_PRICE}.

Quando a macro é expandida, ela retorna o preço vencedor em um formato criptografado. Ele pode ser incluído em um criativo, por exemplo, com uma solicitação de pixel invisível renderizada como parte do anúncio:

<div>
  <script language='JavaScript1.1' src='https://example.com?creativeID=5837243'/>
  <img src='https://example.com/t.gif?price=${AUCTION_PRICE}' width='1' height='1'/>
</div>

A macro ${AUCTION_PRICE} também pode ser incluída no URL VAST de um criativo de vídeo, mas não no URL de impressão no VAST:

https://example.com/vast/v?price=${AUCTION_PRICE}

Cenário

1. Seu aplicativo de lances do OpenRTB inclui a macro ${AUCTION_PRICE} no snippet de HTML ou no URL VAST que ele retorna ao Google.
2. O Google substitui o preço vencedor da macro por uma codificação Base64 não preenchida segura para a Web (RFC 3548).
3. O snippet transmite a confirmação no formato escolhido. Por exemplo, a confirmação pode ser transmitida no URL de uma solicitação de pixel invisível renderizada como parte do anúncio.
4. No servidor, o base64 seguro para Web do seu aplicativo decodifica as informações do preço vencedor e descriptografa o resultado.

Dependências

Você vai precisar de uma biblioteca criptográfica compatível com o HMAC SHA-1, como o Openssl.

Código de amostra

O código de exemplo é fornecido em Java e C++ e pode ser feito o download no projeto privatedatacommunicationprotocol.

• O código de exemplo em Java usa o decodificador base64 do projeto Apache commons. Não será necessário fazer o download do código do Apache commons, porque a implementação de referência inclui a parte necessária e é independente.

• O código de exemplo em C++ usa o método base64 BIO do OpenSSL. Ele decodifica uma string codificada em base64 segura para a Web (RFC 3548). Normalmente, as strings base64 seguras para a Web substituem o preenchimento "=" por ".". As aspas são adicionadas para facilitar a leitura e não são incluídas no protocolo, mas a substituição de macro não preenche o preço criptografado. A implementação de referência adiciona preenchimento porque o OpenSSL tem problemas com strings sem preenchimento.

Codificação

A criptografia e a descriptografia do preço vencedor exigem duas chaves secretas, mas compartilhadas. Uma chave de integridade e uma chave de criptografia, chamadas de i_key e e_key, respectivamente. Ambas as chaves são fornecidas na configuração da conta como strings base64 seguras para a Web e podem ser encontradas na página do Authorized Buyers em Configurações do bidder > Configurações de RTB > Chaves de criptografia.

Exemplos de chaves de integridade e criptografia:

skU7Ax_NL5pPAFyKdkfZjZz2-VhIN8bjj1rVFOaJ_5o=  // Encryption key (e_key)
arO23ykdNqUQ5LEoQ0FVmPkBd7xB5CO89PDZlSjpFxo=  // Integrity key (i_key)

As chaves precisam ser decodificadas de forma segura para a Web e depois decodificadas em base64 pelo aplicativo:

e_key = WebSafeBase64Decode('skU7Ax_NL5pPAFyKdkfZjZz2-VhIN8bjj1rVFOaJ_5o=')
i_key = WebSafeBase64Decode('arO23ykdNqUQ5LEoQ0FVmPkBd7xB5CO89PDZlSjpFxo=')

Esquema de criptografia

O preço é criptografado usando um esquema de criptografia personalizado projetado para minimizar o tamanho da sobrecarga, garantindo a segurança adequada. O esquema de criptografia usa um algoritmo HMAC com chave para gerar um bloco secreto com base no ID exclusivo do evento de impressão.

O preço criptografado tem um comprimento fixo de 28 bytes. Ele é composto por um vetor de inicialização de 16 bytes, 8 bytes de texto criptografado e uma assinatura de integridade de 4 bytes. O preço criptografado é codificado em base64 seguro para a Web, de acordo com a RFC 3548, com caracteres de preenchimento omitidos. Assim, o preço criptografado de 28 bytes é codificado como uma string base-64 segura para Web de 38 caracteres, independentemente do preço vencedor pago.

Exemplos de preços criptografados:

YWJjMTIzZGVmNDU2Z2hpN7fhCuPemCce_6msaw  // 100 CPI micros
YWJjMTIzZGVmNDU2Z2hpN7fhCuPemCAWJRxOgA  // 1900 CPI micros
YWJjMTIzZGVmNDU2Z2hpN7fhCuPemC32prpWWw  // 2700 CPI micros

O formato criptografado é:

{initialization_vector (16 bytes)}{encrypted_price (8 bytes)}
{integrity (4 bytes)}

O preço é criptografado como <price xor HMAC(encryption_key, initialization_vector)>, para que a descriptografia calcule HMAC(encryption_key,initialization_vector) e xor's com o preço criptografado para reverter a criptografia. A etapa de integridade leva 4 bytes de <HMAC(integrity_key, price||initialization_vector)>, em que || é concatenação.

pad = hmac(e_key, iv)  // first 8 bytes
enc_price = pad <xor> price
signature = hmac(i_key, price || iv)  // first 4 bytes

final_message = WebSafeBase64Encode( iv || enc_price || signature )

Esquema de descriptografia

O código de descriptografia precisa descriptografar o preço usando a chave de criptografia e verificar os bits de integridade com a chave de integridade. As chaves serão fornecidas a você durante a configuração. Não há restrições sobre os detalhes de como você estrutura sua implementação. Na maioria das vezes, você pode usar o exemplo de código e adaptá-lo de acordo com suas necessidades.

// Base64 padding characters are omitted.
// Add any required base64 padding (= or ==).
final_message_valid_base64 = AddBase64Padding(final_message)

// Web-safe decode, then base64 decode.
enc_price = WebSafeBase64Decode(final_message_valid_base64)

// Message is decoded but remains encrypted.
(iv, p, sig) = enc_price // Split up according to fixed lengths.
price_pad = hmac(e_key, iv)
price = p <xor> price_pad

conf_sig = hmac(i_key, price || iv)
success = (conf_sig == sig)

Detectar ataques de resposta desatualizada

Para detectar ataques de resposta desatualizada ou de repetição, é recomendável filtrar respostas com um carimbo de data/hora que seja significativamente diferente do horário do sistema, após considerar as diferenças de fuso horário.

O vetor de inicialização contém uma marcação de tempo nos primeiros 8 bytes. Ela pode ser lida pela seguinte função em C++:

void GetTime(const char* iv, struct timeval* tv) {
    uint32 val;
    memcpy(&val, iv, sizeof(val));
    tv->tv_sec = htonl(val);
    memcpy(&val, iv+sizeof(val), sizeof(val));
    tv->tv_usec = htonl(val)
}

O carimbo de data/hora pode ser convertido em um formato legível por humanos usando o seguinte código C++:

struct tm tm;
localtime_r(&tv->tv_sec, &tm);

printf("%04d-%02d-%02d|%02d:%02d:%02d.%06ld",
       tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday,
       tm.tm_hour, tm.tm_min, tm.tm_sec,
       tv_.tv_usec);

Biblioteca Java

Em vez de implementar os algoritmos criptográficos para codificar e decodificar o preço vencedor, use DoubleClickCrypto.java. Para mais informações, consulte Criptografia.