> ## Documentation Index
> Fetch the complete documentation index at: https://support.entegrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Encryption (CMK)

> Manage Customer-Managed Keys for enhanced data encryption and security compliance

## Overview

Customer-Managed Keys (CMK) provide enhanced security for your Entegrata instance by allowing you to control the encryption keys used to protect your data in Azure. With CMK, you maintain ownership and control over the cryptographic keys, meeting compliance requirements and providing additional security layers beyond Azure's default encryption.

<Info>
  CMK implementation requires uploading PEM-formatted encryption keys to your Entegrata instance. The system monitors key expiration and provides visual alerts to ensure continuous data protection.
</Info>

## Why Use Customer-Managed Keys?

### Enhanced Security Control

<Card>
  **Your Keys, Your Control:**

  * You generate and own the encryption keys
  * Keys never leave your control during generation
  * You decide when to rotate or revoke keys or let Entegrata rotate them yearly by default
  * Independent from cloud provider's key management
</Card>

### Flexibility in Key Management

<ResponseField name="Key Rotation" type="security">
  Rotate encryption keys on demandto meet security policies and compliance requirements or yearly by default.
</ResponseField>

<ResponseField name="Key Revocation" type="security">
  Immediately revoke access by removing keys, providing an additional security control in breach scenarios.
</ResponseField>

## Understanding CMK Status

### Status Badge Colors

The CMK card displays color-coded badges indicating key expiration status for quick assessment:

<Card>
  <div style={{ display:"flex",gap:"10px",flexDirection:"column" }}>
    <span>🔴 Red Badge - Key expires in less than 1 day (immediate action required</span>
    <span>🟡 Yellow Badge - Key expires in less than 7 days (plan key rotation soon</span>
    <span>🔵 Blue Badge - Key expires in less than 30 days (schedule key rotation</span>
    <span>🟢 Green Badge - Key valid for 30+ days (no immediate action needed)</span>
  </div>
</Card>

<Warning>
  If your CMK shows a **red badge** (expires in less than 1 day), upload a new key immediately. Expired keys may prevent access to encrypted data and cause service disruptions.
</Warning>

<Frame />

## Generating a PEM Key File

### Prerequisites

Before generating a CMK, ensure you have:

* **OpenSSL installed** on your system (or access to key generation tools)
* **Secure key storage** for backup copies
* **Documentation process** for tracking key generation

### Using OpenSSL to Generate Keys

<Steps>
  <Step title="Open Terminal or Command Prompt">
    Access a terminal with OpenSSL installed. Verify installation:

    ```bash theme={null}
    openssl version
    ```
  </Step>

  <Step title="Generate Private Key">
    Generate a 4096-bit RSA private key:

    ```bash theme={null}
    openssl genrsa -out cmk-private-key.pem 4096
    ```

    <Note>
      The 4096-bit key length provides strong encryption suitable for most compliance requirements. You can use 2048-bit for basic needs or 8192-bit for maximum security.
    </Note>
  </Step>

  <Step title="Secure the Key File">
    Set appropriate file permissions to protect the key:

    ```bash theme={null}
    chmod 600 cmk-private-key.pem
    ```

    <Warning>
      Never share your private key file. Store it securely with restricted access and maintain encrypted backups.
    </Warning>
  </Step>

  <Step title="Verify Key Format">
    Confirm the key is in proper PEM format:

    ```bash theme={null}
    openssl rsa -in cmk-private-key.pem -check -noout
    ```

    Expected output: `RSA key ok`
  </Step>
</Steps>

### Key Generation Best Practices

<Tip>
  **Security recommendations:**

  * ✅ Generate keys on secure, offline systems when possible
  * ✅ Use strong key lengths (4096-bit or higher)
  * ✅ Store backup copies in encrypted, secure locations
  * ✅ Document key generation date and purpose
  * ✅ Never transmit keys over unsecured channels
</Tip>

## Uploading a Customer-Managed Key

### File Format Requirements

<Card>
  **PEM File Requirements:**

  * File extension: `.pem`
  * Format: Privacy Enhanced Mail (PEM) encoded
  * Key type: RSA private key
  * Minimum key length: 2048 bits (4096 bits recommended)
  * Character encoding: ASCII/UTF-8
  * No password protection on the key file
</Card>

<Warning>
  The PEM file must be an unencrypted private key. Password-protected or encrypted PEM files will be rejected by the upload process.
</Warning>

### Upload Process

<Steps>
  <Step title="Access CMK Management">
    Navigate to Instance Settings and click **Manage Data Encryption** on the CMK card.
  </Step>

  <Step title="Select PEM File">
    Click **Choose File** or **Select PEM File** button to open the file browser.

    <Note>
      Only files with `.pem` extension are accepted. Other file types will be rejected.
    </Note>
  </Step>

  <Step title="Upload the Key">
    Click **Upload**

    <Info>
      The system validates the file format before accepting the upload. Invalid files will be rejected with an error message.
    </Info>
  </Step>
</Steps>

### During Upload Process

<Warning>
  While the infrastructure is in TRANSITIONING state:

  * All other instance configuration changes are disabled
  * The upload typically takes 5-15 minutes
  * You can monitor progress on the loading screen
</Warning>

### What Happens During Upload

The CMK upload process involves several backend operations:

1. **File Validation** - System verifies PEM format and key strength
2. **Secure Transfer** - Key is sent to Delegator Container App via Service Bus
3. **Customer Environment Processing** - Key is stored in your Azure subscription
4. **Key Vault Update** - Azure Key Vault is configured with the new CMK
5. **Infrastructure Update** - Pulumi applies configuration changes
6. **Encryption Migration** - Data encryption keys are re-encrypted with new CMK
7. **Status Update** - System records new expiration date and status

## CMK Expiration and Renewal

### Why Key Expiration Matters

Encryption keys should be rotated regularly to:

* **Minimize exposure** from potential key compromise
* **Meet compliance requirements** mandating periodic key rotation
* **Reduce cryptographic risk** from long-term key usage
* **Maintain security posture** with current best practices

<Note>
  Most compliance frameworks (SOC 2, ISO 27001, PCI-DSS) require key rotation at least annually. Many organizations implement yearly rotation schedules for sensitive data.
</Note>

### Key Rotation Before Expiry

<Tip>
  **Best practice: Rotate keys well before expiration**

  * Plan rotation when badge turns **blue** (30 days remaining)
  * Execute rotation when badge turns **yellow** (7 days remaining)
  * Avoid waiting until badge turns **red** (less than 1 day)
</Tip>

### Expired Key Recovery

<Warning>
  If a CMK expires before rotation:

  * Data access may be impacted
  * Some encrypted services may fail
  * Immediate key upload is required
  * Contact Entegrata support if data access issues occur
</Warning>

**Recovery steps for expired keys:**

1. **Immediate action** - Generate and upload a new key as quickly as possible
2. **Service verification** - Test critical services after new key is deployed
3. **Root cause analysis** - Document why expiration occurred
4. **Process improvement** - Adjust monitoring and rotation schedules to prevent recurrence

## Best Practices for Key Management

### Key Generation and Storage

<Card title="Secure Key Handling" icon="shield-halved">
  * **Generate offline** - Create keys on secure, non-networked systems when possible
  * **Encrypted backups** - Store backup copies in encrypted archives
  * **Access control** - Limit key access to authorized security personnel only
  * **Audit logging** - Document all key generation, access, and rotation activities
  * **Physical security** - Store backup keys in secure physical locations (safes, vaults)
</Card>

### Key Lifecycle Management

<Steps>
  <Step title="Generation">
    Create keys using approved methods and tools with documented procedures
  </Step>

  <Step title="Distribution">
    Securely transfer keys to authorized personnel using encrypted channels
  </Step>

  <Step title="Installation">
    Upload keys to Entegrata during planned maintenance windows
  </Step>

  <Step title="Active Use">
    Monitor expiration status and system health throughout key lifetime
  </Step>

  <Step title="Rotation">
    Replace keys before expiration following planned rotation schedule
  </Step>

  <Step title="Archival">
    Securely archive retired keys per data retention policies
  </Step>

  <Step title="Destruction">
    Permanently destroy keys after retention period using approved methods
  </Step>
</Steps>

### Multi-Person Approval

<Tip>
  For high-security environments, implement multi-person approval for CMK operations:

  * One person generates the key
  * Another person reviews and approves the key
  * A third person uploads the key to Entegrata
  * All actions are logged and auditable
</Tip>

## Troubleshooting

### Common Upload Errors

<AccordionGroup>
  <Accordion title="Invalid File Format">
    **Error:** "The uploaded file is not a valid PEM file"

    **Solutions:**

    * Verify the file has `.pem` extension
    * Ensure the file contains `-----BEGIN RSA PRIVATE KEY-----` header
    * Check that the key is not password-protected
    * Regenerate the key using OpenSSL if format is uncertain
    * Verify no corruption occurred during file transfer
  </Accordion>

  <Accordion title="Key Length Too Short">
    **Error:** "Key length does not meet minimum security requirements"

    **Solutions:**

    * Generate a new key with at least 2048-bit length
    * Recommended: Use 4096-bit keys for enhanced security
    * Verify key properties with: `openssl rsa -in key.pem -text -noout`
  </Accordion>

  <Accordion title="Upload Timeout">
    **Error:** "Upload operation timed out"

    **Solutions:**

    * Check your internet connection
    * Verify no firewall or proxy is blocking the upload
    * Try uploading again during off-peak hours
    * Contact Entegrata support if timeouts persist
  </Accordion>

  <Accordion title="Infrastructure Transitioning">
    **Error:** "Cannot upload CMK while infrastructure is transitioning"

    **Solutions:**

    * Wait for current infrastructure operations to complete
    * Check if other administrators are making instance changes
    * Monitor the infrastructure status on the loading screen
    * Try upload again after status returns to IDLE
  </Accordion>

  <Accordion title="File Size Too Large">
    **Error:** "File exceeds maximum allowed size"

    **Solutions:**

    * Ensure you're uploading only the private key, not a certificate chain
    * Verify the file contains only the key, no extra content
    * Standard PEM keys should be under 10KB
  </Accordion>
</AccordionGroup>

### Deployment Stuck in Transitioning

<Warning>
  If CMK upload remains in TRANSITIONING state for more than 30 minutes:
</Warning>

1. **Do not close browser** - Keep the page open to monitor progress
2. **Check infrastructure status** - Review any error messages on loading screen
3. **Wait for timeout** - System may still be processing
4. **Contact support** - If stuck beyond 60 minutes, contact Entegrata support
5. **Provide details** - Share upload timestamp, file details, and any error messages

### Data Access Issues After Upload

If you experience data access problems after CMK upload:

1. **Verify upload success** - Confirm green status badge appears
2. **Check expiration date** - Ensure new expiration date is displayed
3. **Test specific services** - Identify which services are affected
4. **Review error logs** - Check application logs for encryption errors
5. **Contact support immediately** - CMK issues may require backend intervention

## Security Considerations

### Key Security Warnings

<Warning>
  **Critical Security Reminders:**

  * Never share your CMK private key files
  * Never commit PEM files to version control systems
  * Never send keys via email or unencrypted channels
  * Never store keys on shared network drives without encryption
  * Never reuse keys across different environments or systems
</Warning>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Network Connections" icon="network-wired" href="/administration/instance/network-connections">
    Configure secure network connectivity
  </Card>

  <Card title="Firewall Rules" icon="shield-halved" href="/administration/instance/firewall-rules">
    Manage outbound access controls
  </Card>

  <Card title="System Versions" icon="code-branch" href="/administration/instance/system-versions">
    View and upgrade system versions
  </Card>

  <Card title="Instance Overview" icon="lightbulb" href="/administration/instance/overview">
    Learn about instance administration
  </Card>
</CardGroup>