Asymmetric Encryption

Hashing & Password Storage

2.2 Prohibited Algorithms (NEVER USE)

3. Encryption at RestEncryption-in-Transit

3.1Standards

Encryption
• Minimum: TLS 1.2 (legacy client support only)
• Preferred: TLS 1.3 — enforced via Cloudflare SSL Full (Strict) mode
• Cipher suites (TLS 1.3): TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256
• Certificate: Let's Encrypt via Cloudflare (auto-renew) for *.bilko.io
• HSTS: Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

Scope

What is NOT acceptable

• HTTP (unencrypted) for any Bilko endpoint — Cloudflare redirects HTTP → HTTPS
• Self-signed certificates in production
• TLS 1.0 or TLS 1.1 connections
• Disabling certificate verification in API clients

4. Encryption-at-Rest

Database (PostgreSQL on Railway)

• Algorithm: AES-256 (Railway managed disk encryption)
• Level: Full disk encryption — Railway EU West
• Backups: Encrypted using same key before upload to Railway backup storage
• Connection: ssl=require — plaintext connection not allowed even from same host

Backup Files

• Bilko does not manage its own database backups — Railway handles this
• If manual exports are taken for disaster recovery: encrypt with GPG (AES-256) before storing
• GPG key stored in Vaultwarden, not in same location as backup files

5. Field-Level Encryption (L4-A: JMBG and OIB Only)

Tiered L4 approach per ADR-014: Field-level encryption applies ONLY to L4-A personal identifiers (JMBG, OIB). L4-B fields (PIB, JIB, IBAN) rely on disk-level encryption and application controls — see Section 5b. Field-level encryption for L4publicly Restrictedavailable data:business tax IDs (PIB, JIB) is disproportionate per GDPR Article 32.

Field-level encryption is applied to JMBG and OIB BEFORE writing to the database. The database column stores only ciphertext. The application decrypts on read.

Algorithm

• Algorithm:
   AES-256-GCM (authenticated encryption — provides confidentiality + integrity)
• IV: 12 bytes, randomly generated per encryption operation
• Key: 32 bytes (256 bits), stored in FIELD_ENCRYPTION_KEY environment variable (Railway secret)
• Output format: base64(iv):base64(authTag):base64(ciphertext) stored as TEXT column

Implementation

// Tax IDs and bank account numbers encrypted at application layer
// In addition to Railway disk encryption
import crypto{ createCipheriv, createDecipheriv, randomBytes } from 'crypto';

asyncconst ALGORITHM = 'aes-256-gcm'

function encryptRestrictedField(getKey(): Buffer {
  const hex = process.env.FIELD_ENCRYPTION_KEY
  if (!hex || hex.length !== 64) {
    throw new Error('FIELD_ENCRYPTION_KEY must be a 64-character hex string (32 bytes)')
  }
  return Buffer.from(hex, 'hex')
}

export function encryptField(plaintext: string): Promise<string> {
  const key = Buffer.from(process.env.FIELD_ENCRYPTION_KEY!, 'hex'getKey(); // 32 bytes
  const iv = crypto.randomBytes(12); // 96-bit IV for GCM
  const cipher = crypto.createCipheriv('aes-256-gcm',ALGORITHM, key, iv);
  const ciphertextencrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
  const tagauthTag = cipher.getAuthTag();
  // Store: base64(iv || tag || ciphertext)
  return Buffer.concat([iv, tag,authTag, ciphertext])encrypted].map((b) => b.toString('base64');).join(':')
}

asyncexport function decryptRestrictedField(stored:decryptField(ciphertext: string): Promise<string> {
  const key = Buffer.from(process.env.FIELD_ENCRYPTION_KEY!, 'hex'getKey();
  const buf[ivB64, tagB64, encB64] = Buffer.from(stored, ciphertext.split('base64':');
  const iv = buf.subarray(0,Buffer.from(ivB64, 12);'base64')
  const tagauthTag = buf.subarray(12,Buffer.from(tagB64, 28);'base64')
  const ciphertextencrypted = buf.subarray(28);Buffer.from(encB64, 'base64')
  const decipher = crypto.createDecipheriv('aes-256-gcm',ALGORITHM, key, iv);
  decipher.setAuthTag(tag);authTag)
  return Buffer.concat([decipher.update(ciphertext) +encrypted), decipher.final()]).toString('utf8');
}

3.2Fields FileSubject Storageto Field-Level Encryption (L4-A)

3.3Fields BackupNOT Encryption

Railway provides automatic daily PostgreSQL backups, encrypted with AES-256. Backup retention: 30 days (Railway default). Custom backup strategySubject to be implemented in Phase 2 with separate backup encryption key stored in Railway environment secrets.

4. Encryption in Transit

4.1 TLS Configuration

Minimum TLS version:

• External-facing (api.bilko.io, bilko.io): TLS 1.3 (enforced via Cloudflare)
• Railway internal: TLS 1.3

Approved cipher suites (TLS 1.3):

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256 (minimum)

HSTS configuration:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

HTTP redirect: All HTTP traffic redirected to HTTPS (301). No HTTP allowed in production.

Prohibited:

• TLS 1.0 and TLS 1.1 — prohibited
• SSL 2.0 / SSL 3.0 — prohibited
• RC4 cipher suites — prohibited

4.2 Cookie Security

All session cookies set with:

res.cookie('refreshToken', token, {
  httpOnly: true,    // Not accessible to JavaScript
  secure: true,      // HTTPS only
  sameSite: 'strict', // CSRF protection
  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
});

4.3 API Security Headers (Helmet.js)

app.use(helmet({
  hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", "data:", "https:"],
    },
  },
}));

5. Application-Level Encryption

5.1 Field-Level Encryption Requirements(L4-B — Disk-Level + Controls)