Skip to main content

Overview

The Polaris SDK is a TypeScript library that implements encryption and decryption utilities for secure communication with Polaris Secure Containers and for encrypting and decrypting data for storage.

Polaris Encryption Concept​

To use the Polaris SDK efficiently, it is important to understand the encryption mechanisms employed by Polaris. Polaris Containers are designed to enhance security for encrypted communication over HTTP, encrypted permanent data storage, and encryption of data in use. While data encryption in use is managed by the Confidential VM technology, the Polaris SDK addresses the other two aspects.

Integrated Encryption Scheme​

The Polaris encryption scheme is designed to meet the following requirements:

  1. Efficiently encrypt large amounts of data: For handling large HTTP requests or data in permanent storage.
  2. Use public-key cryptography: To encrypt data for use by the Polaris container using its public key.

Traditional asymmetric encryption fulfills the second requirement but is limited to encrypting small amounts of data. Symmetric encryption can efficiently encrypt large data volumes but does not satisfy the second requirement. To address this, Polaris implements an Integrated Encryption Scheme that combines both approaches.

  • RSA asymmetric encryption (4096-bit keys with OEAP padding) is used to exchange a symmetric AES-256-GCM key.
  • Symmetric encryption (AES-256-GCM) is used for encrypting the actual data.
  • For each request, a random symmetric key and IV are generated, encrypted with the container's public key, and packaged with the authentication tag.

The layout of the encrypted data is displayed below:

Encryption data format

info

In the future, we plan to support the HPKE standard.

Key Management​

Encrypting data with the Polaris SDK requires only the public key of the recipient, while decryption requires access to the corresponding private key. The Polaris SDK provides an abstracted interface for private key access, compatible with various key management solutions (e.g., Google Cloud Key Management, Azure Vault, or in-memory keys). See the Key Handlers module section for details.

Modules​

The Polaris SDK includes three modules for encryption utilities:

  1. Data Encryption Utilities: Functions implementing the Integrated Encryption Scheme.
  2. Key Handlers: The key handler abstraction and an ephemeral key handler implementation.
  3. HTTP Request Helpers: Utilities for encrypted HTTP communication with Polaris Containers.

Encryption and Decryption Utilities​

The Polaris SDK provides easy-to-use functions for encrypting and decrypting data. A KeyHandler instance must be provided when initializing the SDK to manage public and private keys. The SDK supports use in both Node.js (via the crypto module) and browsers (via the WebCrypto API).

Example usage:

import { EphemeralKeyHandler, PolarisSDK } from "@fr0ntier-x/polaris-sdk";

const polarisSDK = new PolarisSDK(new EphemeralKeyHandler());
const publicKey = await polarisSDK.getPublicKey();

const message = "Hello from Polaris!";

const encryptedMessage = await polarisSDK.encrypt(Buffer.from(message), publicKey);
const decryptedMessage = await polarisSDK.decrypt(encryptedMessage);

console.log(decryptedMessage.toString()); // Hello from Polaris!

Key Handlers​

The Polaris SDK provides a simple abstracted interface for accessing private keys via the KeyHandler interface. This interface requires the implementation of two functions:

  1. getPublicKey(): Returns the public key corresponding to the private key.
  2. unwrapKey(wrappedKey: Buffer): Unwraps a key previously wrapped with the corresponding public key.

This interface enables the Polaris SDK to integrate seamlessly with various key management solutions, such as Google Cloud Key Management or Azure Vault. The SDK includes an ephemeral key handler implementation that generates a new key pair on each initialization and stores the private key in memory. Implementations for external key management solutions are available through the Polaris Proxy.

HTTP Request Helpers​

To facilitate the integration of encrypted requests and responses in existing applications, the Polaris SDK provides request and response interceptors for the popular axios library. Attaching these interceptors to your axios client ensures that all requests and responses are automatically encrypted and decrypted.

Example usage:

import { createAxiosRequestInterceptor, createAxiosResponseInterceptor } from "@fr0ntier-x/polaris-sdk";

axios.interceptors.request.use(createAxiosRequestInterceptor({ polarisSDK }));
axios.interceptors.response.use(createAxiosResponseInterceptor({ polarisSDK }));
info

In the future, support for additional popular request libraries is planned.