associateKmsKey method

Future<void> associateKmsKey({ required String kmsKeyId, String? logGroupName, String? resourceIdentifier, })

Associates the specified KMS key with either one log group in the account, or with all stored CloudWatch Logs query insights results in the account.

When you use AssociateKmsKey, you specify either the logGroupName parameter or the resourceIdentifier parameter. You can't specify both of those parameters in the same operation.

• Specify the logGroupName parameter to cause log events ingested into that log group to be encrypted with that key. Only the log events ingested after the key is associated are encrypted with that key.

  Associating a KMS key with a log group overrides any existing associations between the log group and a KMS key. After a KMS key is associated with a log group, all newly ingested data for the log group is encrypted using the KMS key. This association is stored as long as the data encrypted with the KMS key is still within CloudWatch Logs. This enables CloudWatch Logs to decrypt this data whenever it is requested.

  Associating a key with a log group does not cause the results of queries of that log group to be encrypted with that key. To have query results encrypted with a KMS key, you must use an AssociateKmsKey operation with the resourceIdentifier parameter that specifies a query-result resource.

• Specify the resourceIdentifier parameter with a query-result resource, to use that key to encrypt the stored results of all future StartQuery operations in the account. The response from a GetQueryResults operation will still return the query results in plain text.

  Even if you have not associated a key with your query results, the query results are encrypted when stored, using the default CloudWatch Logs method.

  If you run a query from a monitoring account that queries logs in a source account, the query results key from the monitoring account, if any, is used.

It can take up to 5 minutes for this operation to take effect.

If you attempt to associate a KMS key with a log group but the KMS key does not exist or the KMS key is disabled, you receive an InvalidParameterException error.

May throw InvalidParameterException. May throw OperationAbortedException. May throw ResourceNotFoundException. May throw ServiceUnavailableException.

Parameter kmsKeyId : The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data. This must be a symmetric KMS key. For more information, see Amazon Resource Names and Using Symmetric and Asymmetric Keys.

Parameter logGroupName : The name of the log group.

In your AssociateKmsKey operation, you must specify either the resourceIdentifier parameter or the logGroup parameter, but you can't specify both.

Parameter resourceIdentifier : Specifies the target for this operation. You must specify one of the following:

• Specify the following ARN to have future GetQueryResults operations in this account encrypt the results with the specified KMS key. Replace REGION and ACCOUNT_ID with your Region and account ID.

  arn:aws:logs:REGION:ACCOUNT_ID:query-result:*

• Specify the ARN of a log group to have CloudWatch Logs use the KMS key to encrypt log events that are ingested and stored by that log group. The log group ARN must be in the following format. Replace REGION and ACCOUNT_ID with your Region and account ID.

  arn:aws:logs:REGION:ACCOUNT_ID:log-group:LOG_GROUP_NAME

In your AssociateKmsKey operation, you must specify either the resourceIdentifier parameter or the logGroup parameter, but you can't specify both.

Implementation

Future<void> associateKmsKey({
  required String kmsKeyId,
  String? logGroupName,
  String? resourceIdentifier,
}) async {
  final headers = <String, String>{
    'Content-Type': 'application/x-amz-json-1.1',
    'X-Amz-Target': 'Logs_20140328.AssociateKmsKey'
  };
  await _protocol.send(
    method: 'POST',
    requestUri: '/',
    exceptionFnMap: _exceptionFns,
    // TODO queryParams
    headers: headers,
    payload: {
      'kmsKeyId': kmsKeyId,
      if (logGroupName != null) 'logGroupName': logGroupName,
      if (resourceIdentifier != null)
        'resourceIdentifier': resourceIdentifier,
    },
  );
}