TLS For Attestation Service

Because of an Android security policy around non-TLS traffic, all Valora requests to attestation services are currently being routed via a proxy operated by cLabs. To eliminate this unnecessary hop and single point of failure, Valora will move to only be able to use TLS-enabled Attestation Services.

Possible options including deploying Nginx or using a service like CloudFlare (but definitely with ‘full SSL’).

We have 2 guides, the one outlined here by Jeff Haferman and another one by Aaron Boyd of Pretoria Research found here.

Jeff Haferman of Qoor shared these steps that we converted into the TLS Guide.

Please begin the process of upgrading your Attestation Service with TLS. Don’t hesitate to reach out in #attestation-service for assistance.

Step 1

Create DNS A Record. You will need to link your Attestation Service IP Address with FQDN.

Step 2

Ensure Port 443 is Open on Your Attestation Service instance. If you’re using a firewall, make sure it allows port 443 as that is needed for TLS to be enabled.

Step 3

We need to install NGINX. Run the following to install it on Debian-based systems. Your installation command might be different if you’re using another Linux distro or OS:

$ sudo apt install nginx

Step 4

Now, we need to stop the attestation-service so we can generate our TLS certificate on the default Port 80.

Run the following command to do so:

$ stop attestation-service

Step 5

Now we will start and enable NGINX. We will run the following commands.

$ sudo systemctl start nginx
$ sudo systemctl enable nginx

Step 6

Now we will be installing Certbot in order to generate a certificate on our Linux box.

Certbot has more information about this on its page here:

We will run the following to install certbot on Debian-based Linux distributions. Instructions might differ if you’re using other Linux distributions or OSes.

$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot
$ sudo certbot --nginx

This last command will install and register your certificate on NGINX. Make sure to follow the prompt there to install it.

Step 7 (Optional)

This is an optional step to cause any calls to your IP Address to fail instead of redirect so that calls only happen from your TLS-enabled domain name.

If you look at an example configuration file for NGINX here, you’ll notice that we have moved root to /dev/null which was /var/www/html. This is how we fail the request to the IP Address.

Validator.Capital / Qoor has generously provided us with a sample of their NGINX template if you’d like to refer to it for guidance. Just ensure to modify <DOMAIN_NAME> to the one you’re registering with certbot.

# Default server configuration


server {

listen 80 default_server;

listen [::]:80 default_server;

root /dev/null; # was /var/www/html

# Add index.php to the list if you are using PHP

index index.html index.htm index.nginx-debian.html;

server_name _;

location / {

# First attempt to serve request as file, then

# as directory, then fall back to displaying a 404.

try_files $uri $uri/ =404;



server {

root /dev/null; # was /var/www/html

# Add index.php to the list if you are using PHP

index index.html index.htm index.nginx-debian.html;

server_name <DOMAIN_NAME>; # managed by Certbot

listen [::]:443 ssl ipv6only=on; # managed by Certbot

listen 443 ssl; # managed by Certbot

ssl_certificate /etc/letsencrypt/live/<DOMAIN_NAME>/fullchain.pem; # managed by Certbot

ssl_certificate_key /etc/letsencrypt/live/<DOMAIN_NAME>/privkey.pem; # managed by Certbot

include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot

ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

access_log /var/log/nginx/access.log;

# this is the reverse-proxy magic

location / {

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $scheme;

proxy_pass http://localhost:8080;

proxy_read_timeout 90;



server {

if ($host = <DOMAIN_NAME>) {

return 301 https://$host$request_uri;

} # managed by Certbot

listen 80;

listen [::]:80;

server_name <DOMAIN_NAME>;

return 404; # managed by Certbot

Step 8

Now we will need to point to Port 8080 from Port 3000 for both our config file and our attestation-service Docker image.

First, modify the .env file for PORT from 3000 to Port 8080 within this file config

Then, make sure your Docker command reflects the new port being Port 8080 as in the following example. NOTE: Don’t run this command yet.

docker run --name celo-attestation-service -it --restart always --entrypoint /bin/bash --network host --env-file $CONFIG -e PORT=8080 -p 8080:8080 $CELO_IMAGE_ATTESTATION -c "cd /celo-monorepo/packages/attestation-service && yarn run db:migrate && yarn start"

Step 9

Restart nginx with the new updates to the config:

$ sudo systemctl restart nginx

Step 10

Make sure to update your $CELO_ATTESTATION_SERVICE_URL environment variable with the new domain name.

Step 11

Start the Docker container for attestation-service from Step 8 with the new port updates.

Step 12

Here are the basic steps to update the metadata. More information about the metadata is found in the docs here

This command creates a metadata json file (on a node with celocli installed and the environment variables defined):

$ celocli account:create-metadata ./validator1_metadata.json --from $CELO_VALIDATOR_RG_ADDRESS

$ celocli account:claim-account ./validator1_metadata.json --address $CELO_VALIDATOR_GROUP_RG_ADDRESS --from $CELO_VALIDATOR_SIGNER_ADDRESS

$ celocli account:claim-attestation-service-url ./validator1_metadata.json --url $CELO_ATTESTATION_SERVICE_URL --from $CELO_ATTESTATION_SIGNER_ADDRESS

This json file then needs to be published as a gistfile. You will then get the URL for the raw gistfile, and then:

$ celocli releasegold:set-account --contract $CELO_VALIDATOR_RG_ADDRESS --property metaURL --value <RAW-GISTFILE-URL>

The above assumes a release gold contract — if we’re not using releasegold, it would be

$ celocli account:register-metadata --url <RAW-GISTFILE-URL>

Then check that the metadata has been registered properly:

$ celocli account:get-metadata $CELO_VALIDATOR_GROUP_RG_ADDRESS

Step 13

In Nexmo’s application, please update your callback URL to the new one you made for the attestation service (TLS-enabled Domain name).

Step 14 (Optional)

You can make a backup of the default file with the following command:

$ cp default default.bat