📋

Description

This error indicates that a User-Defined Function (UDF) in MySQL, which relies on the AWS Keyring plugin to interact with AWS Key Management Service (KMS), has encountered an issue. It typically occurs during the execution of such a UDF when it attempts to perform cryptographic operations or access keys through AWS KMS.

💬

Error Message

Function %s failed due to: %s.

🔍

Known Causes

4 known causes

⚠️

Insufficient AWS KMS Permissions

The IAM role or user associated with the MySQL instance lacks the necessary permissions to access or perform operations with the specified AWS KMS keys.

⚠️

Incorrect Keyring Plugin Configuration

The MySQL AWS Keyring plugin (keyring_aws) is either not correctly installed, configured with invalid AWS credentials, or pointing to a non-existent KMS endpoint.

⚠️

AWS KMS Network Connectivity

The MySQL server is unable to establish a stable network connection to the AWS KMS endpoint, possibly due to firewall rules, routing issues, or VPC configuration.

⚠️

Invalid KMS Key Reference

The User-Defined Function (UDF) is attempting to use an AWS KMS Key ID or ARN that is incorrect, malformed, or refers to a key that does not exist or is in a different region.

🛠️

Solutions

4 solutions available

1. Verify KMS Key Permissions medium

Ensure the IAM role or user associated with your MySQL instance has the necessary permissions to use the specified AWS KMS key.

1

Navigate to the AWS IAM console and identify the role or user that your MySQL DB instance is using. This is often the service-linked role for RDS or a custom role you've attached.

2

Review the attached policies for this role/user. Ensure that the policies grant the `kms:Encrypt`, `kms:Decrypt`, `kms:ReEncrypt*`, `kms:GenerateDataKey*`, and `kms:DescribeKey` permissions for the specific KMS key ARN being used by your MySQL instance.

Example IAM Policy Snippet (replace placeholders):
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:DescribeKey"
            ],
            "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KMS_KEY_ID"
        }
    ]
}

3

If the permissions are missing or insufficient, update the IAM policy to include the required KMS actions for the correct KMS key ARN. Save the changes to the policy.

4

If you've recently modified IAM permissions, it might take a few minutes for the changes to propagate. Try performing the operation that triggered the error again.

2. Check KMS Key Status and Availability easy

Confirm that the AWS KMS key is enabled, not scheduled for deletion, and accessible from your MySQL instance's region.

1

Go to the AWS KMS console. Locate the KMS key that your MySQL instance is configured to use.

2

Verify that the KMS key's status is 'Enabled'. If it's 'Disabled', you'll need to enable it.

3

Check if the KMS key has a 'Deletion date' set. If it's scheduled for deletion, you will need to cancel the deletion process or create a new KMS key.

4

Ensure that the KMS key is in the same AWS region as your RDS instance. Cross-region KMS operations for encryption at rest are not directly supported by the UDF in this context.

5

Attempt the operation that failed. If the KMS key was disabled or scheduled for deletion, re-enabling it or cancelling deletion should resolve the issue.

3. Validate KMS Key ARN and Configuration easy

Double-check that the KMS key ARN configured for your MySQL instance is correct and that the instance itself is properly configured for encryption.

1

In the AWS RDS console, navigate to your DB instance. Select 'Modify' to view or change its configuration.

2

Under the 'Encryption' section, confirm that 'Encryption' is enabled and that the 'KMS key' selected or entered matches the exact ARN of your intended KMS key. Typos or incorrect ARNs are a common cause of this error.

Example KMS Key ARN format: arn:aws:kms:us-east-1:123456789012:key/abcdefgh-ijkl-mnop-qrst-uvwxyz123456

3

If the KMS key ARN is incorrect, update it to the correct ARN and save the changes. This might involve a brief instance reboot or modification window.

4

If you are using a custom KMS key, ensure it's not a Customer Managed Key that has been disabled or deleted. If it's an AWS Managed Key, ensure it's still valid and associated with the service.

4. Review MySQL UDF Logs for Specific Errors medium

Examine the MySQL error logs and AWS CloudTrail for more detailed information about the KMS UDF failure.

1

Access your MySQL server's error logs. For RDS, you can find these in the 'Log exports' section of your DB instance's monitoring tab or by downloading the log files.

2

Search the logs for entries related to 'AWS KMS UDF', 'kms', or the specific function name mentioned in the error message (e.g., 'mysql_kms_encrypt'). The second part of the error message '%s' often contains valuable details.

Example log entry pattern:
ERROR 3198 (HY000): Function mysql_kms_encrypt failed due to: AccessDeniedException: User is not authorized to perform kms:Encrypt on resource arn:aws:kms:...

3

Simultaneously, check AWS CloudTrail logs for API calls related to KMS made by your RDS instance or its associated IAM role around the time of the error. This can provide more granular permission-related insights.

In CloudTrail, filter by Event source: `kms.amazonaws.com` and Resource ARN of your KMS key.

4

Use the detailed error messages from the logs to refine your troubleshooting steps. For example, an `AccessDeniedException` points directly to IAM permission issues, while a `NotFoundException` might indicate an invalid KMS key ARN.

🔗

Related Errors

5 related errors

MySQL Error 3198: AWS KMS UDF Function Failure