Overview

JxBrowser delegates the work with cookies to the Chromium engine. Chromium decides how to download cookies from a web server, extract them from the HTTP headers and store them in a local file system (persistent cookies) or in the memory (session cookies).

To work with cookies, JxBrowser provides CookieStorage and Cookie classes. Use CookieStorage to access the actual cookie storage to get, modify or remove cookies. The Cookie class allows you to get information about specified cookie.

Supported Protocols

JxBrowser supports cookies that are sent using the following protocols:

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

If a cookie is sent using a protocol that is not on the list, e.g. ftp://, it will not be stored in the cookie storage.

Working with Cookies

JxBrowser supports the following kinds of cookies:

• Persistent cookies — these are stored in the Chromium user data directory. If you delete the Chromium user data directory, all the persistent cookies will be removed.
• Session cookies — these are stored in the application memory. These cookies will be removed automatically when the application is terminated.
• Secure cookies — these can only be transmitted over an encrypted connection, i.e. HTTPS. This makes the cookie less likely to be exposed to cookie theft via eavesdropping.
• HttpOnly cookies — these cannot be accessed by the client-side APIs, such as JavaScript. This restriction eliminates the threat of cookie theft via cross-site scripting (XSS). However, the cookie remains vulnerable to cross-site tracing (XST) and cross-site request forgery (XSRF) attacks.

Cookie Storage

Each CookieStorage stores cookies on a local file system in Chromium’s user data directory. So, each CookieStorage depends on BrowserContext that defines where Chromium’s user data folder is located. If you need to use different cookie storages for different Browser instances, then you need to configure Browser instances with different BrowserContext instances and different Chromium’s user data directories.

The Browser instances with same BrowserContext instance will share the cookies.

The following code demonstrates how to create two Browser instances that don’t share cookies:

Browser browserOne = new Browser(new BrowserContext("C:\\MyUserData1"));
Browser browserTwo = new Browser(new BrowserContext("C:\\MyUserData2"));

To access CookieStorage of a Browser instance use the browser.getCookieStorage() method. Using CookieStorage you can get, modify, and delete cookies.

When you modify cookies you must save changes using the CookieStorage.save() method. For example:

CookieStorage cookieStorage = browser.getCookieStorage();
cookieStorage.setSessionCookie("http://www.a.com", "name1", "value1", ".a.com", "/", false, false);
cookieStorage.save();

Getting Cookies

To get all cookies, please use the following approach:

List<Cookie> cookies = cookieStorage.getAllCookies();
for (Cookie cookie : cookies) {
    System.out.println("cookie = " + cookie);
}

To get all cookies by a URL:

List<Cookie> cookies = cookieStorage.getAllCookies("http://www.google.com");
for (Cookie cookie : cookies) {
    System.out.println("cookie = " + cookie);
}

Creating Cookies

Persistent

To create a persistent cookie use the following code:

// Create and add new cookie
final int oneHourInMilliseconds = 36000000;
final int microsecondsOffset = 1000;
// Cookie will be alive during one hour starting from now
long expirationTimeInMicroseconds = (System.currentTimeMillis() + 
        oneHourInMilliseconds) * microsecondsOffset;
cookieStorage.setCookie("http://www.google.com", "mycookie", 
        "myvalue", ".google.com", "/", expirationTimeInMicroseconds, 
        false, false);
cookieStorage.save();

Session

To create a session cookie use the following code:

// Create and add new session cookie
cookieStorage.setSessionCookie("http://www.google.com", "mycookie", 
        "myvalue", ".google.com", "/", false, false);
cookieStorage.save();

Deleting Cookies

To delete all cookies use the following method:

int numberOfDeletedCookies = cookieStorage.deleteAll();
cookieStorage.save();

To delete one cookie, please use the CookieStorage.delete(Cookie). The following code deletes all cookies one by one obtaining the result of the operation:

List<Cookie> cookies = cookieStorage.getAllCookies();
for (Cookie cookie : cookies) {
    boolean success = cookieStorage.delete(cookie);    
}
cookieStorage.save();

Suppressing Cookies

Using Network API you can control all incoming and outgoing cookies. You can enable/disable saving/sending cookies. Using the NetworkDelegate.onCanSetCookies(String url, List<Cookie> cookies) method you can decide whether cookies should be saved or not. To disable sending some cookies to a web server you can use the NetworkDelegate.onCanGetCookies(String url, List<Cookie> cookies) method.

networkService.setNetworkDelegate(new DefaultNetworkDelegate() {
    @Override
    public boolean onCanSetCookies(String url, List<Cookie> cookies) {
        return false;
    }

    @Override
    public boolean onCanGetCookies(String url, List<Cookie> cookies) {
        return false;
    }
});

Encryption

JxBrowser does not encrypt cookies by default. To enable cookies encryption, use the --enable-cookie-encryption Chromium switcher (see the Chromium Switches article to find out how to use Chromium switches).

JxBrowser uses Chromium cookies encryption routines, so it uses the same way to store cookies as Chromium.

On Linux to encrypt cookies JxBrowser uses GNOME Keyring or KWallet. Although Chromium chooses which store to use automatically, the store to use can also be specified with a command line argument:

• --password-store=gnome (to use GNOME Keyring)
• --password-store=kwallet (to use KWallet)

On Windows to encrypt cookies JxBrowser uses only DPAPI. There are no alternatives at the moment.

On macOS, JxBrowser uses the private key stored with the Keychain Application to encrypt cookies with AES encryption.