This guide will help you to setup the card vault on AWS manually by setting up the various components
Creating EC2 instance
Log into your AWS account and create a new EC2 instance preferably on a t3.medium machine with an AMI that supports docker like Amazon Linux 2.
Ensure to manage your instances' (EC2 and RDS) security group rules are selectively enabled for the application subnet and not exposed to the internet. (The locker application should not be accessible via internet)
Install docker on the EC2 instance
Connect to your EC2 instance using the SSH client via a terminal
Once you SSH into the EC2 instance, run the following commands on the terminal to install docker
amazon-linux-extrasinstalldocker-y
Run the following command to start docker
systemctlstartdocker
After starting the docker run the following command to pull the hyperswitch-card-vault docker image
Create an RDS with the latest postgres preferably with Aurora and select a storage of t4g medium. (Record the master username and password securely for further use in setup)
Ensure to add the EC2 instance to database's inbound/outbound rules and vice-versa (In the default set up the rules are set to allow all traffic)
To run the migrations install psql in the EC2 instance
sudoyuminstallpostgresql-serverpostgresql-contrib
sudoamazon-linux-extrasinstallpostgresql10
Run the migrations using the following commands
export DB_USER="<your-database-user>"export DB_PASS="<your-database-password>"# this is not the master passwordexport DB_NAME="locker"sudopsql-h<database-url>-U<master-username>-W-e-c \"CREATE USER $DB_USER WITH PASSWORD '$DB_PASS' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;"sudopsql-h<database-url>-U<master-username>-W-e-c \"CREATE DATABASE $DB_NAME WITH OWNER = $DB_USER;"
Now, open sql interactively with the following command
sudopsql-h<database-url>-U $DB_USER -Wlocker
and paste the contents from the below mentioned migration files
Before setting up KMS, create a new IAM role for your EC2 instance to allow connection to KMS. Use AWS service as the trusted entity type and add permissions for AWSKeyManagementServicePowerUser and create an inline policy allowing All KMS actions.
Now, create a KMS key pair on AWS with the key type as symmetric and the key usage as Encrypt and Decrypt. Ensure to add the IAM role above in the key administrative permissions and key usage permissions.
Generating the keys
To generate the master key and the custodian keys use the following command after cloning the repository.
We recommend generating the Master and JWE/JWS keys as mentioned below in the local setup guide outside of this EC2 machine for better security
KMS encrypting the keys
After generating your keys and setting up of KMS, run the following command to KMS encrypt the keys.
functionkms_encrypt() { xargs -I {} -0 echo -n "{}" | xargs -I {} -0 aws kms encrypt --key-id <your-kms-key-id> --region <your-kms-region> --plaintext "{}"
}# substitute this in the above mentioned envfile (LOCKER__DATABASE__PASSWORD)echo-n"<database password>"|kms_encrypt# substitute this in the above mentioned envfile (LOCKER__SECRETS__MASTER_KEY)echo-n"<generated master key>"|kms_encrypt# substitute this in the above mentioned envfile (LOCKER__SECRETS__LOCKER_PRIVATE_KEY)echo-n'<locker private key>'|kms_encrypt# substitute this in the above mentioned envfile (LOCKER__SECRETS__TENANT_PUBLIC_KEY)echo-n'<tenant public key>'|kms_encrypt
Update Config files
Create an env-file in the instance and paste the environment variables mentioned below
LOCKER__SERVER__HOST=0.0.0.0LOCKER__SERVER__PORT=8080LOCKER__LOG__CONSOLE__ENABLED=trueLOCKER__LOG__CONSOLE__LEVEL=DEBUGLOCKER__LOG__CONSOLE__LOG_FORMAT=defaultLOCKER__DATABASE__USERNAME=# add the database user created aboveLOCKER__DATABASE__PASSWORD=# add the kms encrypted password here (kms encryption process mentioned below)LOCKER__DATABASE__HOST=# add the host of the database (database url)LOCKER__DATABASE__PORT=5432# if used differently mention hereLOCKER__DATABASE__DBNAME=lockerLOCKER__LIMIT__REQUEST_COUNT=100LOCKER__LIMIT__DURATION=60LOCKER__SECRETS__TENANT=hyperswitchLOCKER__SECRETS__MASTER_KEY=# kms encrypted master keyLOCKER__SECRETS__LOCKER_PRIVATE_KEY=# kms encrypted locker private keyLOCKER__SECRETS__TENANT_PUBLIC_KEY=# kms encrypted locker private keyLOCKER__AWS_KMS__KEY_ID=# kms id used to encrypt it belowLOCKER__AWS_KMS__REGION=# kms region used
Running the Locker
After the above changes are done, run the following command to start the locker
Once the locker is up and running, use the 2 key custodian keys generated earlier securely to unlock the locker for use.
The following cURLs are to be used to provide keys
# temporary turn of saving to history to run the following commandsunsetHISTFILE# key 1curl-X'POST' \'localhost:8080/custodian/key1' \-H'accept: text/plain' \-H'Content-Type: application/json' \-d'{ "key": <key 1>}'# key 2curl-X'POST' \'localhost:8080/custodian/key2' \-H'accept: text/plain' \-H'Content-Type: application/json' \-d'{ "key": <key 2>}'# decryptcurl-X'POST''localhost:8080/custodian/decrypt'
If the last cURL replies with Decrypted Successfully, we are ready to use the locker.
Integrating it with Hyperswitch
To start using it with Hyperswitch application update the following environment variables while deploying the Hyperswitch Server. To use it with other applications use the Vault URL and JWE keys.
ROUTER__LOCKER__HOST=# add the ip address of the ec2 instance createdROUTER__JWEKEY__VAULT_ENCRYPTION_KEY=# add the JWE public key of locker generated aboveROUTER__JWEKEY__VAULT_PUBLIC_KEY=# add the JWE private key of tenant generated above
