Tag: Field-Level Encryption (FLE)

Documentation tagged with Field-Level Encryption (FLE) in the Geode graph database. FLE provides application-level encryption for specific sensitive fields, ensuring that confidential data like credit cards, SSNs, and health records remain encrypted even from database administrators. <h3 id="introduction-to-field-level-encryption" class="position-relative d-flex align-items-center group"> Introduction to Field-Level Encryption <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="introduction-to-field-level-encryption" aria-haspopup="dialog" aria-label="Share link: Introduction to Field-Level Encryption"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script>Field-Level Encryption (FLE) is a selective encryption technique that protects specific sensitive properties while leaving other data unencrypted for querying and indexing. Unlike Transparent Data Encryption (TDE) which encrypts all data at rest, FLE provides granular control—you choose exactly which fields to encrypt based on sensitivity and compliance requirements. FLE addresses the zero-trust security model: even if an attacker gains database access (through compromised credentials, SQL injection, or insider threats), encrypted fields remain protected. Only applications with the correct encryption keys can decrypt the data. Key differences from TDE: <ul> <li>TDE: Encrypts all data on disk, transparent to queries, protects against physical theft</li> <li>FLE: Encrypts specific fields, requires application awareness, protects against database compromise</li> </ul> FLE is essential for: <ul> <li>PCI-DSS compliance: Credit card data must be encrypted</li> <li>HIPAA compliance: Protected Health Information (PHI) requires encryption</li> <li>GDPR compliance: Personal data should be encrypted when possible</li> <li>Zero-trust architecture: Minimize trust in database layer</li> <li>Multi-tenant isolation: Ensure tenants can’t access each other’s sensitive data</li> </ul> Geode’s FLE implementation provides: <ul> <li>Client-side encryption (data encrypted before reaching database)</li> <li>Deterministic and randomized encryption modes</li> <li>Queryable encryption for deterministic fields</li> <li>Automatic key rotation</li> <li>Integration with Key Management Systems (KMS)</li> </ul> <h3 id="core-fle-concepts" class="position-relative d-flex align-items-center group"> Core FLE Concepts <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="core-fle-concepts" aria-haspopup="dialog" aria-label="Share link: Core FLE Concepts"> Share link </button> </h3> <h4 id="encryption-modes" class="position-relative d-flex align-items-center group"> Encryption Modes <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="encryption-modes" aria-haspopup="dialog" aria-label="Share link: Encryption Modes"> Share link </button> </h4>FLE supports two encryption modes with different trade-offs: Deterministic Encryption: <ul> <li>Same plaintext always produces same ciphertext</li> <li>Enables equality queries (WHERE ssn = $encrypted_value)</li> <li>Reveals when two records have the same value</li> <li>Use for: Fields requiring exact-match queries (SSN, email, account numbers)</li> </ul> Randomized Encryption: <ul> <li>Same plaintext produces different ciphertext each time</li> <li>Prevents all queries on encrypted field</li> <li>Maximum security (no pattern leakage)</li> <li>Use for: Highly sensitive fields without query requirements (credit card CVV, passwords)</li> </ul> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Plaintext SSN: "123-45-6789" Deterministic encryption: - First record: "AES256(123-45-6789, key)" → "Xy7$mP2qR..." - Second record: "AES256(123-45-6789, key)" → "Xy7$mP2qR..." (same ciphertext) - Can query: WHERE ssn = "Xy7$mP2qR..." Randomized encryption: - First record: "AES256(123-45-6789, key, random_iv)" → "Xy7$mP2qR..." - Second record: "AES256(123-45-6789, key, random_iv)" → "9fK#nQ8tZ..." (different!) - Cannot query deterministically </code></pre></div> <h4 id="data-encryption-keys-dek" class="position-relative d-flex align-items-center group"> Data Encryption Keys (DEK) <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="data-encryption-keys-dek" aria-haspopup="dialog" aria-label="Share link: Data Encryption Keys (DEK)"> Share link </button> </h4>Each encrypted field uses a Data Encryption Key (DEK): <ul> <li>Field-specific DEKs: Different key for SSN vs. credit card</li> <li>Key rotation: Periodically rotate DEKs without re-encrypting all data</li> <li>Key derivation: Derive field keys from master key</li> </ul> Key hierarchy: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">Customer Master Key (CMK) [AWS KMS] | +-- Application Master Key (AMK) | +-- Field DEK (ssn) +-- Field DEK (credit_card) +-- Field DEK (health_records) </code></pre></div> <h4 id="encrypted-property-metadata" class="position-relative d-flex align-items-center group"> Encrypted Property Metadata <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="encrypted-property-metadata" aria-haspopup="dialog" aria-label="Share link: Encrypted Property Metadata"> Share link </button> </h4>Geode stores encrypted properties with metadata: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "ssn": { "value": "Xy7$mP2qR...", // Encrypted ciphertext "algorithm": "AES-256-GCM", // Encryption algorithm "key_id": "dek-ssn-v2", // Which DEK was used "mode": "deterministic", // Encryption mode "iv": "base64-iv", // Initialization vector (randomized mode) "tag": "base64-auth-tag" // Authentication tag } } </code></pre></div>This metadata enables: <ul> <li>Key rotation (identify which key encrypted each value)</li> <li>Algorithm agility (migrate to new algorithms)</li> <li>Authenticated encryption (detect tampering)</li> </ul> <h3 id="how-fle-works-in-geode" class="position-relative d-flex align-items-center group"> How FLE Works in Geode <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="how-fle-works-in-geode" aria-haspopup="dialog" aria-label="Share link: How FLE Works in Geode"> Share link </button> </h3> <h4 id="client-side-encryption" class="position-relative d-flex align-items-center group"> Client-Side Encryption <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="client-side-encryption" aria-haspopup="dialog" aria-label="Share link: Client-Side Encryption"> Share link </button> </h4>FLE encryption happens in the client library before data reaches the database: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import Client from geode_client.encryption import EncryptionConfig # Configure encryption encryption_config = EncryptionConfig( kms_provider='aws-kms', master_key_arn='arn:aws:kms:us-east-1:123:key/abc-123', field_configs={ 'Person.ssn': { 'algorithm': 'AES-256-GCM', 'mode': 'deterministic' }, 'Person.medical_notes': { 'algorithm': 'AES-256-GCM', 'mode': 'randomized' }, 'CreditCard.number': { 'algorithm': 'AES-256-GCM', 'mode': 'deterministic' } } ) # Initialize client with encryption client = Client('localhost:3141', encryption=encryption_config) # Insert with automatic encryption client.execute(""" INSERT (:Person { name: 'Alice', ssn: '123-45-6789', // Encrypted deterministically medical_notes: 'Patient has...' // Encrypted randomly }) """) # Query encrypted field (deterministic only) result = client.execute(""" MATCH (p:Person {ssn: '123-45-6789'}) // Client encrypts parameter RETURN p.name, p.ssn """) # p.ssn is automatically decrypted in result </code></pre></div>The database never sees plaintext sensitive data. <h4 id="queryable-encryption-deterministic" class="position-relative d-flex align-items-center group"> Queryable Encryption (Deterministic) <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="queryable-encryption-deterministic" aria-haspopup="dialog" aria-label="Share link: Queryable Encryption (Deterministic)"> Share link </button> </h4>Deterministic encryption enables equality queries: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Client automatically encrypts the SSN parameter MATCH (p:Person {ssn: $ssn}) RETURN p.name, p.email; -- Supported operations on deterministic fields MATCH (p:Person) WHERE p.ssn = $ssn // Equality OR p.ssn IN [$ssn1, $ssn2, $ssn3] // IN clause RETURN p; -- NOT supported (requires plaintext comparison) MATCH (p:Person) WHERE p.ssn > '000-00-0000' // Range query - NOT SUPPORTED OR p.ssn STARTS WITH '123' // Pattern matching - NOT SUPPORTED RETURN p; </code></pre></div> <h4 id="key-rotation" class="position-relative d-flex align-items-center group"> Key Rotation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="key-rotation" aria-haspopup="dialog" aria-label="Share link: Key Rotation"> Share link </button> </h4>Rotate encryption keys without re-encrypting all data: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Rotate DEK for SSN field client.rotate_field_key('Person.ssn') # Old data remains encrypted with old key (metadata stores key version) # New inserts use new key # Background job can re-encrypt old data gradually </code></pre></div>Geode tracks which key version encrypted each value, enabling: <ul> <li>Zero-downtime rotation</li> <li>Gradual re-encryption</li> <li>Key compromise recovery</li> </ul> <h4 id="schema-declaration" class="position-relative d-flex align-items-center group"> Schema Declaration <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="schema-declaration" aria-haspopup="dialog" aria-label="Share link: Schema Declaration"> Share link </button> </h4>Declare encrypted fields in schema: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Define encrypted properties CREATE CONSTRAINT person_ssn_encrypted FOR (p:Person) REQUIRE p.ssn IS ENCRYPTED DETERMINISTIC; CREATE CONSTRAINT person_medical_encrypted FOR (p:Person) REQUIRE p.medical_notes IS ENCRYPTED RANDOMIZED; -- Geode enforces encryption INSERT (:Person { name: 'Bob', ssn: 'plaintext-ssn' // ERROR: ssn must be encrypted }); </code></pre></div>This prevents accidental plaintext storage. <h3 id="use-cases" class="position-relative d-flex align-items-center group"> Use Cases <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="use-cases" aria-haspopup="dialog" aria-label="Share link: Use Cases"> Share link </button> </h3> <h4 id="pci-dss-compliance" class="position-relative d-flex align-items-center group"> PCI-DSS Compliance <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="pci-dss-compliance" aria-haspopup="dialog" aria-label="Share link: PCI-DSS Compliance"> Share link </button> </h4>Protect credit card data: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Configure FLE for payment data encryption_config = EncryptionConfig( field_configs={ 'Payment.card_number': { 'mode': 'deterministic', # Enable lookups by card number 'algorithm': 'AES-256-GCM' }, 'Payment.cvv': { 'mode': 'randomized', # Maximum security for CVV 'algorithm': 'AES-256-GCM' }, 'Payment.expiry': { 'mode': 'deterministic', 'algorithm': 'AES-256-GCM' } } ) # Store payment client.execute(""" INSERT (:Payment { card_number: '4532-1234-5678-9010', // Encrypted cvv: '123', // Encrypted expiry: '12/25', // Encrypted amount: 99.99, // Plaintext (not sensitive) merchant: 'Acme Corp' // Plaintext }) """) # Query by card number (deterministic encryption) payments = client.execute(""" MATCH (p:Payment {card_number: $card_number}) RETURN p.amount, p.merchant, p.expiry """, card_number='4532-1234-5678-9010') </code></pre></div> <h4 id="hipaa-compliance" class="position-relative d-flex align-items-center group"> HIPAA Compliance <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="hipaa-compliance" aria-haspopup="dialog" aria-label="Share link: HIPAA Compliance"> Share link </button> </h4>Protect Protected Health Information (PHI): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">encryption_config = EncryptionConfig( field_configs={ 'Patient.ssn': {'mode': 'deterministic'}, 'Patient.medical_record_number': {'mode': 'deterministic'}, 'Patient.diagnosis': {'mode': 'randomized'}, 'Patient.treatment_notes': {'mode': 'randomized'}, 'Patient.prescription': {'mode': 'randomized'} } ) # Insert patient data client.execute(""" INSERT (:Patient { name: 'John Doe', // Plaintext (public identifier) ssn: '987-65-4321', // Encrypted deterministically mrn: 'MRN-123456', // Encrypted deterministically diagnosis: 'Type 2 Diabetes', // Encrypted randomly treatment_notes: '...', // Encrypted randomly age: 45 // Plaintext (not PHI in this context) }) """) </code></pre></div> <h4 id="multi-tenant-saas" class="position-relative d-flex align-items-center group"> Multi-Tenant SaaS <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="multi-tenant-saas" aria-haspopup="dialog" aria-label="Share link: Multi-Tenant SaaS"> Share link </button> </h4>Isolate tenant data cryptographically: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Each tenant gets unique encryption keys class TenantEncryptionConfig: def __init__(self, tenant_id, master_key_arn): self.config = EncryptionConfig( kms_provider='aws-kms', master_key_arn=master_key_arn, key_namespace=f'tenant-{tenant_id}', // Tenant-specific keys field_configs={ 'Document.content': {'mode': 'randomized'}, 'Document.metadata': {'mode': 'deterministic'} } ) # Tenant A's client tenant_a_client = Client('localhost:3141', encryption=TenantEncryptionConfig('tenant-a', kms_key_a).config) # Tenant B's client (different keys) tenant_b_client = Client('localhost:3141', encryption=TenantEncryptionConfig('tenant-b', kms_key_b).config) # Even if Tenant A compromises database, can't decrypt Tenant B's data </code></pre></div> <h4 id="personally-identifiable-information-pii" class="position-relative d-flex align-items-center group"> Personally Identifiable Information (PII) <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="personally-identifiable-information-pii" aria-haspopup="dialog" aria-label="Share link: Personally Identifiable Information (PII)"> Share link </button> </h4>Protect PII for GDPR compliance: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">encryption_config = EncryptionConfig( field_configs={ 'User.email': {'mode': 'deterministic'}, # Queryable for login 'User.phone': {'mode': 'deterministic'}, # Queryable for contact 'User.address': {'mode': 'randomized'}, # No query needed 'User.date_of_birth': {'mode': 'randomized'}, # No query needed 'User.ip_address': {'mode': 'deterministic'}, # Queryable for audit } ) </code></pre></div> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3> <h4 id="choosing-encryption-mode" class="position-relative d-flex align-items-center group"> Choosing Encryption Mode <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="choosing-encryption-mode" aria-haspopup="dialog" aria-label="Share link: Choosing Encryption Mode"> Share link </button> </h4>Use Deterministic Encryption When: <ul> <li>Need to query by exact value (login, lookup)</li> <li>Field has high cardinality (many unique values)</li> <li>Pattern leakage is acceptable</li> </ul> Use Randomized Encryption When: <ul> <li>Maximum security required</li> <li>No query requirements</li> <li>Field has low cardinality (reveals patterns)</li> <li>Compliance demands strongest encryption</li> </ul> <h4 id="minimize-encrypted-fields" class="position-relative d-flex align-items-center group"> Minimize Encrypted Fields <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="minimize-encrypted-fields" aria-haspopup="dialog" aria-label="Share link: Minimize Encrypted Fields"> Share link </button> </h4>Only encrypt what’s truly sensitive: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Good: Selective encryption { 'name': 'Alice', // Plaintext (not sensitive) 'email': '...', // Deterministic (need to query) 'ssn': '...', // Deterministic (need to verify) 'medical_notes': '...' // Randomized (very sensitive) } # Bad: Over-encryption { 'name': '...', // Encrypted (why? need to display) 'created_at': '...', // Encrypted (why? need to sort/filter) 'public_bio': '...' // Encrypted (why? it's public!) } </code></pre></div>Over-encryption hurts performance and usability without security benefit. <h4 id="key-management" class="position-relative d-flex align-items-center group"> Key Management <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="key-management" aria-haspopup="dialog" aria-label="Share link: Key Management"> Share link </button> </h4><ol> <li> Use KMS: Never hardcode encryption keys <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Good config = EncryptionConfig( kms_provider='aws-kms', master_key_arn='arn:aws:kms:...' ) # Bad config = EncryptionConfig( master_key='hardcoded-key-here' // NEVER DO THIS ) </code></pre></div></li> <li> Rotate keys regularly: Quarterly or annually <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Schedule automated key rotation client.schedule_key_rotation( field='Person.ssn', interval_days=90 ) </code></pre></div></li> <li> Separate keys by sensitivity: SSN vs. email <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">config = EncryptionConfig( field_configs={ 'Person.ssn': {'key_id': 'high-security-dek'}, 'Person.email': {'key_id': 'medium-security-dek'} } ) </code></pre></div></li> </ol> <h4 id="application-design" class="position-relative d-flex align-items-center group"> Application Design <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="application-design" aria-haspopup="dialog" aria-label="Share link: Application Design"> Share link </button> </h4><ol> <li>Encrypt at client: Never send plaintext to database</li> <li>Validate before encrypt: Reject invalid SSNs before encrypting</li> <li>Cache decrypted values: Avoid repeated decryption</li> <li>Handle encryption errors: Key unavailable, KMS timeout, etc.</li> </ol> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">def create_user(name, ssn, email): # Validate BEFORE encrypting if not is_valid_ssn(ssn): raise ValueError("Invalid SSN format") try: client.execute(""" INSERT (:User {name: $name, ssn: $ssn, email: $email}) """, name=name, ssn=ssn, email=email) except EncryptionError as e: logger.error(f"Encryption failed: {e}") # Handle gracefully (retry, alert, etc.) raise </code></pre></div> <h3 id="performance-considerations" class="position-relative d-flex align-items-center group"> Performance Considerations <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-considerations" aria-haspopup="dialog" aria-label="Share link: Performance Considerations"> Share link </button> </h3> <h4 id="encryption-overhead" class="position-relative d-flex align-items-center group"> Encryption Overhead <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="encryption-overhead" aria-haspopup="dialog" aria-label="Share link: Encryption Overhead"> Share link </button> </h4>Typical performance impact: <ul> <li>Encryption latency: +0.5-2ms per encrypted field</li> <li>Decryption latency: +0.5-2ms per encrypted field</li> <li>Query performance: Deterministic fields support indexes, minimal impact</li> <li>Insert throughput: 10-20% reduction for heavily encrypted records</li> </ul> <h4 id="optimization-tips" class="position-relative d-flex align-items-center group"> Optimization Tips <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="optimization-tips" aria-haspopup="dialog" aria-label="Share link: Optimization Tips"> Share link </button> </h4><ol> <li> Batch operations: Amortize KMS overhead <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Encrypt batch before inserting encrypted_users = client.encrypt_batch(users) async with client.connection() as conn: await conn.begin() try: for query, params in insert_queries: await conn.execute(query, params) await conn.commit() except Exception: await conn.rollback() raise </code></pre></div></li> <li> Cache DEKs: Avoid repeated KMS calls <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">config = EncryptionConfig( kms_provider='aws-kms', dek_cache_size=1000, # Cache up to 1000 DEKs dek_cache_ttl=3600 # Cache for 1 hour ) </code></pre></div></li> <li> Use connection pooling: Reuse encrypted connections </li> <li> Minimize encrypted fields: Only encrypt what’s necessary </li> </ol> <h3 id="related-topics" class="position-relative d-flex align-items-center group"> Related Topics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-topics" aria-haspopup="dialog" aria-label="Share link: Related Topics"> Share link </button> </h3><ul> <li><a href="/tags/tde/" >Transparent Data Encryption (TDE)</a> - Full database encryption</li> <li><a href="/tags/security/" >Security</a> - Overall security features</li> <li><a href="/tags/encryption/" >Encryption</a> - Encryption capabilities</li> <li><a href="/tags/compliance/" >Compliance</a> - Regulatory compliance</li> <li><a href="/tags/authentication/" >Authentication</a> - Access control</li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li><a href="/docs/security/field-level-encryption/" >Field-Level Encryption Guide</a> - Complete FLE documentation</li> <li><a href="/docs/security/kms-integration/" >KMS Integration</a> - KMS integration guide</li> <li><a href="/docs/client-libraries/" >Client Libraries</a> - Language-specific FLE usage</li> </ul> Geode’s Field-Level Encryption provides granular protection for sensitive data with queryable encryption support, enabling compliance with PCI-DSS, HIPAA, and GDPR while maintaining application functionality.

Popular

Related Articles

Security and Compliance Guide