Launching Sessions

• 1: Creating an Isolated link
• 2: Session configuration options

1 - Creating an Isolated link

Overview

Browsolate is a secure, isolated browser environment designed to safely render and interact with websites. To facilitate secure communication and configuration, Browsolate uses encrypted URLs containing JSON blobs that define browser session settings. These URLs are constructed with sensitive data that needs to be encrypted for safe transfer.

This documentation outlines how developers can construct such URLs, using encryption keys sourced from an API or AWS Secrets Manager.

Table of Contents

1. How the System Works
2. Encryption Key Sources
   • API-Sourced Encryption Key
   • AWS Secrets Manager
3. Constructing URLs for Browsolate
4. Example Implementations
   • Python Example
   • Node.js Example
   • Java Example
   • Bash Example
5. Deployment Considerations
6. JSON Object Metadata

How the System Works

At the core of Browsolate’s system, URLs are used to initiate browser sessions with encrypted JSON data. This data is required to configure each session and contains sensitive information such as session parameters, permissions, and other settings.

Encryption Process:

1. JSON Construction: Developers define session-related JSON.
2. AES-256-CBC Encryption: The JSON blob is encrypted using the AES-256-CBC algorithm.
3. Base64 Encoding: The encrypted data is base64-encoded and appended to the URL as a query parameter (b8data).
4. URL Construction: The encrypted blob is added to the URL, making it secure for transmission.

Example URL Format

https://<aws_region>.<your_subdomain>.isolated.browsolate.com/viewer.html?keyId=default&b8data=ENCRYPTED_BASE64_DATA

Where:

• <aws_region> is the AWS region where the instance is hosted.
• <your_subdomain> is the unique subdomain assigned to you as a customer using Browsolate.

Encrypting the JSON

API-Sourced Encryption

If the API has been enabled at deployment time, the data may be encrypted via a POST to the /encrypt HTTP endpoint

API Endpoint:

• HTTP Basic Auth required.
  • User: b8admin
  • Password: (Specified during marketplace deployment)
• JSON Payload
  • keyName: The name of key to use for encryption. default is created upon deployment
  • data: The data to be encrypted. This may be in the form of an Object, or an escaped JSON string.
• JSON Response
  • {"encryptedData":"ENCRYPTED_BASE64_DATA"}

API Example:

POST /encrypt HTTP/1.1
Host: us-east-1.abc123_custid.isolated.browsolate.com
Authorization: Basic b8admin:password
Content-Type: application/json

{
  "keyName": "default",
  "data": {
    "url": "https://example.com",
    "linkExpiry": -1
  }
}

The response contains the encrypted base64 data:

{
  "encryptedData": "ENCRYPTED_BASE64_DATA"
}

AWS Secrets Manager

AWS Secrets Manager is used to secure the encryption keys. When deployed from AWS Marketplace, the secret b8_urlencryption_secrets-v1.json is created (if not already present).

• Secret Name: b8_urlencryption_secrets-v1.json

Secrets Manager Fetch Example:

aws secretsmanager get-secret-value --secret-id b8_urlencryption_secrets-v1.json

This returns the encryption keys stored as a JSON blob.

Constructing URLs for Browsolate

1. Construct the JSON Payload: Create a JSON object that holds the session-related data.
2. Encrypt the JSON Blob: Use AES-256-CBC encryption to encrypt the JSON payload with the chosen key. The initialization vector (IV) should be securely generated.
3. Base64 Encode the Encrypted Data: After encryption, base64-encode the encrypted blob for URL-safe transmission.
4. Construct the URL: Append the b8data query parameter to the base URL along with the keyId, which identifies the source of the encryption key.

Example URL Format:

https://<aws_region>.<your_subdomain>.isolated.browsolate.com/viewer.html?keyId=default&b8data=ENCRYPTED_BASE64_DATA

Example Implementations

cURL Example - Calling the Browsolate API

For generating a URL, the API can be called via cURL as follows:

curl -X POST "https://us-west-1.your_subdomain.isolated.browsolate.com:5443/encrypt" \
     -H "Authorization: Basic B64(b8admin:password)" \
     -H "Content-Type: application/json" \
     -d '{
    "keyName": "default",
    "data": {
        "url": "https://example.com",
        "linkExpiry": -1
    },
    "returnBase64": true
}'

Node.js Example - Encrypting the URL yourself

const crypto = require('crypto');
const base64url = require('base64url');

function encrypt(key, data) {
    const iv = crypto.randomBytes(16);
    const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
    const encrypted = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
    return base64url(Buffer.concat([iv, encrypted]));
}

const key = Buffer.from('your-256-bit-secret-key', 'utf8');
const jsonData = JSON.stringify({
    "url": "https://example.com",
    "linkExpiry": -1
});

const encryptedData = encrypt(key, jsonData);
const url = `https://us-east-1.your_subdomain.isolated.browsolate.com/viewer.html?keyId=default&b8data=${encryptedData}`;
console.log(url);

Further examples

Sample code for Java, Python, JavaScript and shell-scripting.

• Java_CreateBrowsolateUrl.zip
• create_browsolate_url.js
• create_browsolate_url.py
• create_browsolate_url.sh

Deployment Considerations

Depending on the environment, the encryption key may be sourced differently:

1. API Encryption: Ensure the API is enabled and credentials for accessing it are securely stored.
2. AWS Secrets Manager: The marketplace application stores its keys in b8_urlencryption_secrets-v1.json

JSON Object Metadata

The following table describes all the fields that may appear in the JSON object.

Note: Fields marked with * are required.

2 - Session configuration options

When creating URLs to launch sessions in Browsolate, you can pass various runtime arguments to customize session behavior dynamically. These options allow for flexible control over user interactions, security, and session parameters during runtime.

Below is a detailed explanation of the available runtime arguments and their effects.

Runtime Arguments

Mandatory arguments

URL to Browse

The URL that will be opened in the isolated browser session. This must be a valid web address.

• URL
  • Type: String
  • Default: ""

Link Expiry

Specifies the absolute time when the session link will expire, or -1 for no expiry.

• linkExpiry
  • Type: Abstime
  • Default: -1

Clipboard Access

Allow Clipboard Read

Specifies whether the session is allowed to read content from the user’s clipboard. If set to true, the session can access clipboard data.

• clipboardRead
  • Type: Boolean
  • Default: false

Allow Clipboard Write

Specifies whether the session can write content to the user’s clipboard. If set to true, the session can modify clipboard content.

• clipboardWrite
  • Type: Boolean
  • Default: false

User Interface and Experience

Theme Name

Specifies the theme to use for the session’s user interface.

• themeName
  • Type: String
  • Default: "default"

Read-Only Mode

Enables or disables read-only mode for the session. When enabled, the session restricts user actions such as input or interaction with web forms.

• readOnly
  • Type: Boolean
  • Default: false

Allow Navigation

Determines if the user is allowed to navigate to different URLs during the session.

• navigation
  • Type: Boolean
  • Default: true

URL Editable

Specifies whether the URL bar is editable by the user during the session.

• urlEditable
  • Type: Boolean
  • Default: false

Session Management

Session Lifetime

Defines the total duration (in seconds) of the session before it is automatically terminated.

• sessionLifetime
  • Type: Integer
  • Default: 300

Allow Session Extension

Specifies whether the session can be extended beyond its original lifetime.

• sessionExtensionAllowed
  • Type: Boolean
  • Default: false

Session Extension Time

Defines the amount of time (in seconds) to extend the session when allowed.

• sessionExtensionTime
  • Type: Integer
  • Default: 30

Screen Settings

Screen Width

Specifies the width of the browser window. Use -1 for automatic sizing.

• screenWidth
  • Type: Integer
  • Default: -1

Screen Height

Specifies the height of the browser window. Use -1 for automatic sizing.

• screenHeight
  • Type: Integer
  • Default: -1

Mobile Device Automatic Sizing

Automatically size the screen on mobile devices, ignore any fixed width and height.

• mobileAutoSize
  • Type: Boolean
  • Default: true

Customization Options

User Agent String

Defines the User-Agent string for the session. This is an advanced option and can be used to modify how the browser identifies itself to websites.

• userAgent
  • Type: String
  • Default: ""

Custom Request Headers

Allows custom request headers to be sent with each HTTP request. This is an advanced option for customizing how requests are made.

• customRequestHeaders
  • Type: KeyValue
  • Default: ""

Debugging and Logging

Link ID

An identifier for the session link, which will be logged with all events generated by the session.

• linkId
  • Type: String
  • Default: ""

Log Direct URL Navigation

Logs whenever the user navigates directly to a new URL within the session.

• logDirectUrlNavigation
  • Type: Boolean
  • Default: false

Log Indirect URL Navigation

Logs when URLs are fetched indirectly from within the session, such as through JavaScript.

• logIndirectUrlNavigation
  • Type: Boolean
  • Default: false

Enable Debug Mode

Turns on debug mode for the session, which may provide additional diagnostic information.

• debugModeEnabled
  • Type: Boolean
  • Default: false