node-red-contrib-aws-kms

A Node-RED node for AWS KMS (Key Management Service) operations. This module provides a simple way to perform encryption, decryption, and key generation operations using AWS KMS directly from your Node-RED flows.

Developed by Andrii Lototskyi

Installation

Run the following command in your Node-RED user directory (typically ~/.node-red):

npm install node-red-contrib-aws-kms

After installation, restart Node-RED to load the new nodes.

Features

This node provides the following AWS KMS operations:

• Encrypt: Encrypt data using a KMS key
• Decrypt: Decrypt data that was encrypted using KMS
• Generate Data Key: Generate a new data key for client-side encryption

Supported Operations

1. Encrypt

   • Encrypts data using the specified KMS key
   • Input: String or Buffer in msg.payload
   • Output: Base64-encoded encrypted data in msg.payload

2. Decrypt

   • Decrypts data encrypted using KMS
   • Input: Base64-encoded encrypted data in msg.payload
   • Output: Decrypted data in msg.payload

3. Generate Data Key

   • Generates a new data key for client-side encryption
   • No input required
   • Output: Object in msg.payload containing:
     • plaintext: Base64-encoded plaintext key
     • ciphertext: Base64-encoded encrypted key

Configuration

AWS Credentials

1. Add a new AWS KMS Config node
2. Choose an authentication method:
   • IAM Role (recommended for EC2 instances)
   • Access Key and Secret Key
   • Temporary credentials with Session Token

Node Configuration

1. Add an AWS KMS node to your flow
2. Configure the node with:
   • AWS credentials (select the config node)
   • Region (e.g., us-east-1)
   • Operation type
   • Key ID (ARN of the KMS key)
   • Key Spec (for Generate Data Key operation)

Examples

Basic Encryption Flow

[
    {
        "id": "aws-kms-encrypt",
        "type": "aws-kms",
        "name": "Encrypt Data",
        "aws": "aws-credentials",
        "region": "us-east-1",
        "operation": "encrypt",
        "keyId": "arn:aws:kms:us-east-1:123456789012:key/your-key-id"
    }
]

Decryption Flow

[
    {
        "id": "aws-kms-decrypt",
        "type": "aws-kms",
        "name": "Decrypt Data",
        "aws": "aws-credentials",
        "region": "us-east-1",
        "operation": "decrypt"
    }
]

Generate Data Key Flow

[
    {
        "id": "aws-kms-generate-key",
        "type": "aws-kms",
        "name": "Generate Data Key",
        "aws": "aws-credentials",
        "region": "us-east-1",
        "operation": "generateDataKey",
        "keyId": "arn:aws:kms:us-east-1:123456789012:key/your-key-id",
        "keySpec": "AES_256"
    }
]

Best Practices

1. Security

   • Use IAM roles when possible
   • Rotate access keys regularly
   • Use temporary credentials for enhanced security
   • Follow the principle of the least privilege

2. Performance

   • Use data keys for large data encryption
   • Cache data keys when possible
   • Consider regional placement of KMS keys

3. Error Handling

   • Always handle encryption/decryption errors
   • Implement retry logic for transient failures
   • Log security-related events

Troubleshooting

Common Issues

1. "Key ID required" Error

   • Ensure the Key ID is set in node config or msg.keyId
   • Verify the Key ID format (should be a valid KMS key ARN)

2. "Could not load credentials" Error

   • Check AWS credentials configuration
   • Verify IAM role permissions
   • Ensure environment variables are set correctly

3. "Invalid region" Error

   • Verify the region format (e.g., us-east-1)
   • Ensure the region is supported by AWS KMS

4. "Invalid ciphertext" Error

   • Verify the input data is properly base64 encoded
   • Check if the data was encrypted with the same key

Debugging

1. Enable Node-RED debug output
2. Check AWS CloudWatch logs
3. Verify IAM permissions
4. Test with AWS CLI first

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT

Support

For issues and feature requests, please use the GitHub issue tracker.