node-red-contrib-aws-kms

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

• Encrypt

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

• Decrypt

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

• 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

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

Node Configuration

• Add an AWS KMS node to your flow
• 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

• Security

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

• Performance

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

• Error Handling

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

Troubleshooting

Common Issues

• "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)

• "Could not load credentials" Error

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

• "Invalid region" Error

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

• "Invalid ciphertext" Error

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

Debugging

• Enable Node-RED debug output
• Check AWS CloudWatch logs
• Verify IAM permissions
• Test with AWS CLI first

Contributing

• Fork the repository
• Create a feature branch
• Commit your changes
• Push to the branch
• Create a Pull Request

License

MIT

Support

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