Skip to main content

Text Encryption

Learn how to encrypt and decrypt text payloads in CIFER Web2 mode.

Prerequisites​

This guide assumes you have already set up authentication (registered, verified email, created a session). Here is a quick setup recap:

import { createCiferSdk, web2 } from 'cifer-sdk';

const sdk = await createCiferSdk({
  blackboxUrl: 'https://cifer-blackbox.ternoa.dev:3010',
});

const client = web2.createClient({
  blackboxUrl: sdk.blackboxUrl,
  readClient: sdk.readClient,
});

// Session already created (see Authentication guide)
await client.createManagedSession({
  principalId: 'your-principal-uuid',
  ed25519Signer: myEd25519Signer,
});

Encrypt (Client)​

const encrypted = await client.payload.encryptPayload({
  secretId: 42,
  plaintext: 'My secret message',
});

console.log('Cifer:', encrypted.cifer);
console.log('Encrypted message:', encrypted.encryptedMessage);

Decrypt (Client)​

const decrypted = await client.payload.decryptPayload({
  secretId: 42,
  encryptedMessage: encrypted.encryptedMessage,
  cifer: encrypted.cifer,
});

console.log('Decrypted:', decrypted.decryptedMessage);

Stateless API​

You can also use the stateless web2.blackbox functions directly. This requires passing session, blackboxUrl, and readClient on every call:

Encrypt​

const encrypted = await web2.blackbox.payload.encryptPayload({
  session,
  secretId: 42,
  plaintext: 'My secret message',
  blackboxUrl: 'https://cifer-blackbox.ternoa.dev:3010',
  readClient: sdk.readClient,
});

console.log('Cifer:', encrypted.cifer);
console.log('Encrypted message:', encrypted.encryptedMessage);

Decrypt​

const decrypted = await web2.blackbox.payload.decryptPayload({
  session,
  secretId: 42,
  encryptedMessage: encrypted.encryptedMessage,
  cifer: encrypted.cifer,
  blackboxUrl: 'https://cifer-blackbox.ternoa.dev:3010',
  readClient: sdk.readClient,
});

console.log('Decrypted:', decrypted.decryptedMessage);

Error Handling​

import {
  Web2Error,
  Web2SessionError,
  BlackboxError,
  EncryptionError,
  DecryptionError,
  isWeb2SessionError,
  isCiferError,
} from 'cifer-sdk';

try {
  await client.payload.encryptPayload({ ... });
} catch (error) {
  if (isWeb2SessionError(error)) {
    // Session expired or cannot be renewed
    console.log('Session error:', error.message);
    // Re-create the session
  } else if (error instanceof EncryptionError) {
    console.log('Encryption failed:', error.message);
  } else if (error instanceof BlackboxError) {
    console.log('Blackbox error:', error.message, error.statusCode);
  } else if (isCiferError(error)) {
    console.log('CIFER error:', error.code, error.message);
  }
}

Best Practices​

  1. Use the client - Prefer client.payload.encryptPayload() over the stateless API. The client handles session, blackboxUrl, and readClient automatically.
  2. Check payload size - Text payloads must be < 16KB. For larger data, use File Encryption.
  3. Let sessions auto-renew - The client calls session.ensureValid() before each request automatically.

Next Steps​