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.