Cookies

Este documento descreve como trabalhar com cookies.

Visão geral

O JxBrowser delega o trabalho com os cookies no motor Chromium. O Chromium decide como realizar o download de cookies de um servidor Web, extraí-los dos cabeçalhos HTTP e armazená-los no diretório de dados do usuário (cookies persistentes) ou na memória (cookies de sessão).

A classe CookieStore lhe permite obter, modificar e remover cookies. A classe Cookie fornece informações sobre um cookie específico.

Para obter o CookieStore para um Profile específico, por favor use o método Profile.cookieStore(). O método Engine.cookieStore() retorna o CookieStore associado ao perfil padrão.

Para acessar o armazenamento de cookies, utilize o seguinte procedimento:

CookieStore cookieStore = profile.cookieStore();

val cookieStore = profile.cookieStore()

Protocolos suportados

O JxBrowser suporta cookies que são enviados utilizando os seguintes protocolos:

• HTTP
• HTTPS
• WS (WebSocket)
• WSS (WebSocket seguro)

Se um cookie for enviado utilizando um protocolo que não conste na lista, por exemplo, ftp://, não será guardado no armazenamento de cookies.

Trabalhando com cookies

O JxBrowser suporta os seguintes tipos de cookies:

• Cookies persistentes — são armazenados no diretório de dados do usuário do Chromium. Se você excluir o diretório de dados do usuário do Chromium, todos os cookies persistentes serão removidos.
• Cookies de sessão — são armazenados na memória da aplicação. Estes cookies serão removidos automaticamente quando a aplicação for terminada.
• Cookies seguros — só podem ser transmitidos através de uma ligação encriptada, ou seja HTTPS. Isto torna o cookie menos suscetível de ser exposto ao roubo de cookies através de escutas.
• HttpOnly cookies — não podem ser acessados pelas APIs do lado do cliente, como o JavaScript. Esta restrição elimina a ameaça de roubo de cookies através de cross-site scripting (XSS). No entanto, o cookie continua vulnerável a ataques cross-site tracing (XST) e cross-site request forgery (XSRF).

Quando você modificar os cookies, utilize o método CookieStore.persist() para salvar as alterações.

Obtendo cookies

Para obter todos os cookies, utilize o método cookies():

cookieStore.cookies().forEach(cookie -> 
        System.out.println("cookie = " + cookie));

cookieStore.cookies().forEach { println("cookie = $it") }

Para obter todos os cookies de um URL, utilize o método cookies() que aceita uma string:

cookieStore.cookies("https://www.google.com").forEach(cookie -> 
        System.out.println("cookie = " + cookie));

cookieStore.cookies("https://www.google.com").forEach { println("cookie = $it") }

Criando cookies

Persistente

Para criar um cookie persistente com um tempo de expiração, utilize o seguinte código:

cookieStore.set(Cookie.newBuilder(".google.com")
        .creationTime(creationTime)
        .expirationTime(expirationTime)
        .name("name")
        .value("value")
        .path("/")
        .build());
cookieStore.persist();

cookieStore.set(Cookie.newBuilder(".google.com")
        .creationTime(creationTime)
        .expirationTime(expirationTime)
        .name("name")
        .value("value")
        .path("/")
        .build())
cookieStore.persist()

Sessão

Para criar um cookie de sessão, utilize o seguinte código:

cookieStore.set(Cookie.newBuilder(".google.com")
        .name("name")
        .value("value")
        .path("/")
        .build());
cookieStore.persist();

cookieStore.set(Cookie.newBuilder(".google.com")
        .name("name")
        .value("value")
        .path("/")
        .build())
cookieStore.persist()

Excluindo cookies

Para excluir todos os cookies, utilize o método deleteAll():

int numberOfDeletedCookies = cookieStore.deleteAll();
cookieStore.persist();

val numberOfDeletedCookies = cookieStore.deleteAll()
cookieStore.persist()

Para excluir um cookie, utilize o comando delete(Cookie). O código seguinte elimina todos os cookies um a um:

cookieStore.cookies().forEach(cookieStore::delete);
cookieStore.persist();

cookieStore.cookies().forEach(cookieStore::delete)
cookieStore.persist()

Supressão de cookies

Você pode controlar todos os cookies de entrada e de saída utilizando as chamadas de retorno CanSetCookieCallback e CanGetCookiesCallback da Network.

Para suprimir os cookies de entrada, utilize o seguinte código:

network.set(CanSetCookieCallback.class, params -> Response.cannot());

network.set(CanSetCookieCallback::class.java, CanSetCookieCallback { Response.cannot() })

Para suprimir os cookies de saída, utilize o seguinte código:

network.set(CanGetCookiesCallback.class, params -> Response.cannot());

network.set(CanGetCookiesCallback::class.java, CanGetCookiesCallback { Response.cannot() })

Encriptação

O JxBrowser suporta a encriptação de cookies por padrão. Ele utiliza as rotinas de encriptação de cookies do Chromium, portanto, os cookies são armazenados exatamente como no Chromium.

Linux

No Linux, o JxBrowser utiliza o GNOME Keyring ou KWallet para encriptar os cookies. A biblioteca escolhe automaticamente qual local utilizar. Você pode especificar manualmente qual o local a utilizar através de uma opção apropriada quando o constrói Engine. Por exemplo:

Engine engine = Engine.newInstance(EngineOptions.newBuilder(...)
        .passwordStore(PasswordStore.GNOME_KEYRING)
        .build());

val engine = Engine.newInstance(EngineOptions.newBuilder(...)
        .passwordStore(PasswordStore.GNOME_KEYRING)
        .build())

Windows

No Windows, o JxBrowser utiliza apenas a DPAPI para encriptar os cookies. Atualmente, não existem alternativas.

macOS

No macOS, o JxBrowser utiliza a chave privada armazenada na aplicação Keychain para encriptar cookies com encriptação AES.