> For the complete documentation index, see [llms.txt](https://docs.friggframework.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.friggframework.org/2.0/reference/encryption-and-security.md).

# Encryption and Security

## Overview

Frigg provides built-in support for data encryption to help you secure sensitive information in your integrations. The framework automatically configures AWS KMS (Key Management Service) for field-level encryption when enabled in your application definition.

## Default Encryption: AES Keys

### Out-of-the-Box Encryption

By default, Frigg uses a simple AES key-based encryption system that works without any additional configuration. This system uses environment variables to manage encryption keys:

```javascript
// Current encryption key
process.env.AES_KEY_ID       // Key identifier
process.env.AES_KEY          // Actual encryption key

// For key rotation support
process.env.DEPRECATED_AES_KEY_ID    // Previous key identifier  
process.env.DEPRECATED_AES_KEY       // Previous encryption key
```

## Automatic KMS Configuration

### Enable KMS in Your App Definition

To enable automatic KMS configuration, add the `encryption` property to your App Definition:

```javascript
const appDefinition = {
    name: 'my-frigg-app',
    integrations: [
        // your integrations...
    ],
    encryption: {
        fieldLevelEncryptionMethod: 'kms'
    }
}

module.exports = appDefinition;
```

### What Happens Automatically

When `fieldLevelEncryptionMethod` is set to `'kms'`, Frigg automatically:

1. **Discovers KMS Key**: Uses AWS Discovery to find your account's default KMS key
2. **Grants KMS Permissions**: Adds `kms:GenerateDataKey` and `kms:Decrypt` permissions to all Lambda function IAM roles
3. **Sets Environment Variable**: Configures `KMS_KEY_ARN` environment variable with discovered key for runtime access
4. **Includes KMS Plugin**: Adds the `serverless-kms-grants` plugin to your serverless configuration
5. **VPC Integration**: Creates KMS VPC Endpoint when VPC is enabled for secure, cost-effective access

### Generated Infrastructure

The framework generates the following serverless configuration:

```yaml
# IAM Permissions
provider:
  iamRoleStatements:
    - Effect: Allow
      Action:
        - kms:GenerateDataKey
        - kms:Decrypt
      Resource: 
        - '${self:custom.kmsGrants.kmsKeyId}'

# Environment Variables
provider:
  environment:
    KMS_KEY_ARN: '${self:custom.kmsGrants.kmsKeyId}'

# Plugins
plugins:
  - serverless-kms-grants

# Custom Configuration  
custom:
  kmsGrants:
    kmsKeyId: '${env:AWS_DISCOVERY_KMS_KEY_ID}'  # Discovered via AWS Discovery
```

## Using KMS in Your Code

### Accessing the KMS Key ARN

The KMS key ARN is available in your Lambda functions via environment variables:

```javascript
const kmsKeyArn = process.env.KMS_KEY_ARN;

// Use with AWS SDK for encryption operations
const { KMSClient, GenerateDataKeyCommand, DecryptCommand } = require('@aws-sdk/client-kms');

const kmsClient = new KMSClient({ region: 'us-east-1' });
```

### Integration with Frigg Encrypt Module

If you're using the `@friggframework/encrypt` module, it will automatically use the configured KMS key:

```javascript
const { encrypt, decrypt } = require('@friggframework/encrypt');

// Encrypt sensitive data
const encryptedData = await encrypt(sensitiveString);

// Decrypt when needed
const decryptedData = await decrypt(encryptedData);
```

## VPC Integration

### KMS with VPC Enabled

When both KMS and VPC are enabled, Frigg automatically optimizes for security and cost:

```javascript
const appDefinition = {
    encryption: { fieldLevelEncryptionMethod: 'kms' },
    vpc: { enable: true },
    integrations: [/* your integrations */]
};
```

This configuration automatically:

* **Creates KMS VPC Endpoint** (\~$22/month) for secure, direct KMS access
* **Avoids NAT Gateway costs** for KMS operations
* **Reduces latency** by keeping KMS traffic within your VPC
* **Improves security** by avoiding internet routing for encryption operations

### Cost Considerations

| Configuration            | Monthly Cost | Security  | Performance |
| ------------------------ | ------------ | --------- | ----------- |
| KMS only (no VPC)        | $0           | Medium    | Good        |
| KMS + VPC (no endpoints) | \~$45        | High      | Good        |
| KMS + VPC + Endpoints    | \~$67        | Very High | Excellent   |

The VPC endpoint cost is often offset by reduced NAT Gateway data charges for encryption operations.

## Security Best Practices

### When to Use KMS

Enable KMS encryption when your integrations handle:

* Personal Identifiable Information (PII)
* Financial data
* Authentication tokens (beyond basic OAuth)
* Sensitive business data
* Healthcare information (PHI)

### Key Management

* **Default Keys**: Frigg uses AWS default KMS keys (`*`) for simplicity
* **Custom Keys**: For enhanced security, consider creating dedicated KMS keys per environment
* **Key Rotation**: AWS automatically rotates default keys annually

## Deployment Considerations

### Prerequisites

Ensure your deployment environment has:

1. **IAM Permissions**: Deployment role needs KMS permissions to create grants
2. **KMS Access**: Lambda execution role will have KMS permissions after deployment

### Environment Isolation

KMS configurations are environment-specific:

* **Development**: Uses same default keys for testing
* **Staging**: Can use environment-specific keys
* **Production**: Should use dedicated production keys for maximum security

### Version Requirements

* **Framework Version**: Requires `@friggframework/devtools` v2.1.0+
* **AWS Provider**: Compatible with all AWS regions
* **Node.js**: Works with all supported Node.js versions (16.x, 18.x, 20.x)

## Examples

### Basic Setup

```javascript
// app-definition.js
const appDefinition = {
    name: 'secure-integration-app',
    integrations: [
        SalesforceIntegration,
        HubspotIntegration
    ],
    encryption: {
        fieldLevelEncryptionMethod: 'kms'
    }
};

module.exports = appDefinition;
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.friggframework.org/2.0/reference/encryption-and-security.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.