Configure data retention

To configure data retention for your AWS Wickr network, you must deploy the data retention bot Docker image to a container on a host, such as a local computer or an instance in Amazon Elastic Compute Cloud (Amazon EC2). After the bot is deployed, you can configure it to store data locally or in an Amazon Simple Storage Service (Amazon S3) bucket. You can also configure the data retention bot to use other AWS services like AWS Secrets Manager (Secrets Manager), Amazon CloudWatch (CloudWatch), Amazon Simple Notification Service (Amazon SNS), and AWS Key Management Service (AWS KMS). The following topics describe how to configure and run the data retention bot for your Wickr network.

Topics

• Prerequisites to configure data retention
• Password
• Storage options
• Environment variables
• Secrets Manager values
• IAM policy to use data retention with AWS services
• Start the data retention bot
• Stop the data retention bot

Prerequisites to configure data retention

Before you get started, you must get the data retention bot name (labeled as Username) and initial password from the AWS Management Console for Wickr. You must specify both of these values the first time you start the data retention bot. You must also enable data retention in the console. For more information, see View data retention details.

Password

The first time you start the data retention bot, you specify the initial password using one of the following options:

• The WICKRIO_BOT_PASSWORD environment variable. The data retention bot environment variables are outlined in the Environment variables section later in this guide.

• The password value in Secrets Manager identified by the AWS_SECRET_NAME environment variable. The Secrets Manager values for the data retention bot are outlined in the Secrets Manager values section later in this guide.

• Enter the password when prompted by the data retention bot. You will need to run the data retention bot with interactive TTY access using the -ti option.

A new password will be generated when you configure the data retention bot for the first time. If you need to re-install the data retention bot, you use the generated password. The initial password is not valid after the initial installation of the data retention bot.

The new generated password will be displayed as shown in the following example.

Important

Save the password in a safe place. If you lose the password you will not be able to re-install the data retention bot. Don't share this password. It provides the ability to start data retention for your Wickr network.

********************************************************************
**** GENERATED PASSWORD
**** DO NOT LOSE THIS PASSWORD, YOU WILL NEED TO ENTER IT EVERY TIME
**** TO START THE BOT
 "HuEXAMPLERAW4lGgEXAMPLEn"
 ********************************************************************

Storage options

After data retention is enabled and the data retention bot is configured for your Wickr network, it will capture all messages and files sent within your network. Messages are saved in files which are limited to a specific size or time limit that can be configured using an environment variable. For more information, see Environment variables.

You can configure one of the following options for storing this data:

• Store all captured messages and files locally. This is the default option. It's your responsibility to move local files to another system for long-term storage, and to make sure the host disk does not run out of memory or space.

• Store all captured messages and files in an Amazon S3 bucket. The data retention bot will save all decrypted messages and files to the Amazon S3 bucket you specify. The captured messages and files are removed from the host machine after they are successfully saved to the bucket.

• Store all captured messages and files encrypted in an Amazon S3 bucket. The data retention bot will re-encrypt all captured messages and files using a key that you supply and save them to the Amazon S3 bucket you specify. The captured messages and files are removed from the host machine after they are successfully re-encrypted and saved to the bucket. You will need software to decrypt the messages and files.

  For more information about creating an Amazon S3 bucket to use with your data retention bot, see Creating a bucket in the Amazon S3 User Guide

Environment variables

You can use the following environment variables to configure the data retention bot. You set these environment variables using the -e option when you run the data retention bot Docker image. For more information, see Start the data retention bot.

Note

These environment variables are optional unless otherwise specified.

Use the following environment variables to specify the data retention bot credentials:

• WICKRIO_BOT_NAME — The name of the data retention bot. This variable is required when you run the data retention bot Docker image.

• WICKRIO_BOT_PASSWORD — The initial password for the data retention bot. For more information, see Prerequisites to configure data retention. This variable is required if you don't plan to start the data retention bot with a password prompt or you don't plan to use Secrets Manager to store the data retention bot credentials.

Use the following environment variables to configure the default data retention streaming capabilities:

• WICKRIO_COMP_MESGDEST – The path name to the directory where messages will be streamed. The default value is /tmp/<botname>/compliance/messages.

• WICKRIO_COMP_FILEDEST – The path name to the directory where files will be streamed. The default value is /tmp/<botname>/compliance/attachments.

• WICKRIO_COMP_BASENAME – The base name for the received messages files. The default value is receivedMessages.

• WICKRIO_COMP_FILESIZE – The maximum file size for a received messages file in kibibyte (KiB). A new file is started when the max size is reached. The default value is 1000000000, as in 1024 GiB.

• WICKRIO_COMP_TIMEROTATE – The amount of time, in minutes, for which the data retention bot will put received messages into a received messages file. A new file is started when the time limit is reached. You can only use the file size or time to limit the size of the received messages file. The default value is 0, as in no limit.

Use the following environment variable to define the default AWS Region to use.

• AWS_DEFAULT_REGION – The default AWS Region to use for AWS services like Secrets Manager (not used for Amazon S3 or AWS KMS). The us-east-1 Region is used by default if this environment variable is not defined.

Use the following environment variables to specify the Secrets Manager secret to use when you opt to use Secrets Manager to store the data retention bot credentials and AWS service information. For more information about the values you can store in Secrets Manager see Secrets Manager values.

• AWS_SECRET_NAME – The name of the Secrets Manager secret that contains the credentials and AWS service information needed by the data retention bot.

• AWS_SECRET_REGION – The AWS Region that the AWS secret is located in. If you are using AWS secrets and this value is not defined the AWS_DEFAULT_REGION value will be used.

Note

You can store all of the following environment variables as values in Secrets Manager. If you opt to use Secrets Manager, and you store these values there, then you don't need to specify them as environment variables when you run the data retention bot Docker image. You only need to specify the AWS_SECRET_NAME environment variable described earlier in this guide. For more information, see Secrets Manager values.

Use the following environment variables to specify the Amazon S3 bucket when you opt to store messages and files to a bucket.

• WICKRIO_S3_BUCKET_NAME – The name of the Amazon S3 bucket where messages and files will be stored.

• WICKRIO_S3_REGION – The AWS Region of the Amazon S3 bucket where messages and files will be stored.

• WICKRIO_S3_FOLDER_NAME – The optional folder name in the Amazon S3 bucket where messages and files will be stored. This folder name will be preceded with the key for messages and files saved to the Amazon S3 bucket.

Use the following environment variables to specify the AWS KMS details when you opt to use client side encryption to re-encrypt files when saving them to an Amazon S3 bucket.

• WICKRIO_KMS_MSTRKEY_ARN – The Amazon Resource Name (ARN) of the AWS KMS master key used to re-encrypt the message files and files on the data retention bot before they are saved to the Amazon S3 bucket.

• WICKRIO_KMS_REGION – The AWS Region where the AWS KMS master key is located.

Use the following environment variable to specify the Amazon SNS details when you opt to send data retention events to an Amazon SNS topic. The events sent include startup, shutdown, as well as error conditions.

• WICKRIO_SNS_TOPIC_ARN – The ARN of the Amazon SNS topic that you want data retention events sent to.

Use the following environment variable to send data retention metrics to CloudWatch. If specified, the metrics will be generated every 60 seconds.

• WICKRIO_METRICS_TYPE – Set the value of this environment variable to cloudwatch to send metrics to CloudWatch.

Secrets Manager values

You can use Secrets Manager to store the data retention bot credentials and AWS service information. For more information about creating a Secrets Manager secret, see Create an AWS Secrets Manager secret in the Secrets Manager User Guide.

The Secrets Manager secret can have the following values:

• password – The data retention bot password.

• s3_bucket_name – The name of the Amazon S3 bucket where messages and files will be stored. If not set, the default file streaming will be used.

• s3_region – The AWS Region of the Amazon S3 bucket where messages and files will be stored.

• s3_folder_name – The optional folder name in the Amazon S3 bucket where messages and files will be stored. This folder name will be preceded with the key for messages and files saved to the Amazon S3 bucket.

• kms_master_key_arn – The ARN of the AWS KMS master key used to re-encrypt the message files and files on the data retention bot before they are saved to the Amazon S3 bucket.

• kms_region – The AWS Region where the AWS KMS master key is located.

• sns_topic_arn – The ARN of the Amazon SNS topic that you want data retention events sent to.

IAM policy to use data retention with AWS services

If you plan to use other AWS services with the Wickr data retention bot, you must ensure the host has the appropriate AWS Identity and Access Management (IAM) role and policy to access them. You can configure the data retention bot to use Secrets Manager, Amazon S3, CloudWatch, Amazon SNS, and AWS KMS. The following IAM policy allows access to specific actions for these services.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "secretsmanager:GetSecretValue",
                "sns:Publish",
                "cloudwatch:PutMetricData",
                "kms:GenerateDataKey"
            ],
            "Resource": "*"
        }
    ]
}

You can create an IAM policy that is more strict by identifying the specific objects for each service that you want to allow the containers on your host to access. Remove the actions for the AWS services that you do not intend to use. For example, if you intent to use only an Amazon S3 bucket, then use the following policy, which removes the secretsmanager:GetSecretValue, sns:Publish, kms:GenerateDataKey, and cloudwatch:PutMetricData actions.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "*"
        }
    ]
}

If you are using an Amazon Elastic Compute Cloud (Amazon EC2) instance to host your data retention bot, create an IAM role using the Amazon EC2 common case and assign a policy using the policy definition from above.