Local Hashing Service Hosting

Clients using privacy-preserving (blinded) mode will have their own local hashing service instance. This service takes unblinded demographics information and returns a hashed payload for use with the blinded Identity API methods. See Privacy-Preserving (Blinded) Mode for details.

This article describes how to host and install your own copy of the local hashing service.

Contents

Docker
- Hash Key
- Configuration
Endpoints
Monitoring and Logging

Docker

The local hashing service is provided as a stand alone web service via a docker image in Docker Hub.

If you have Docker installed, you can pull the service for local testing using:

docker pull careevolution/bmpi-hashing-service

Hash Key

The local hashing service operates with a “Bring Your Own Key” (BYOK) model for increased security. This hash key should be a cryptographically secure, random key in base64 format, ideally generated by openSSL with 64 random bytes.

The openSSL command openssl rand -base64 64 can be used to generate a suitable key.

Warning
Data send with a given hash key will only match data sent with that same hash key. As such it is important to keep the key consistent for a given data set.

Configuration

The Docker service lets you configure which port(s) are available:

Port	Description
7001	HTTPS with a self-signed certificate
7002	HTTP

Additionally there are several environment variables you will need to configure:

Environment Variable	Description
`HASH__KEY`	See Hash Key.
`Logging__Console__FormatterName`	Set to `json` for machine-readable JSON logs, `simple` for human readable logs.

A sample docker-compose.yaml configuration is shown below.

services:
  bmpi-hashing-service:
    image: careevolution/bmpi-hashing-service:latest
    ports:
      # HTTPS port (using a self-signed certificate)
      - "7001:7001"
      
      # HTTP port
      - "7002:7002"

    environment:
      # set HASH__KEY to your secure key. Note the double underscore in the name
      HASH__KEY: "${HASH__KEY}"
      
      # this make the logs a nice human readable format, remove it or set the value to "json" for machine-readable logs
      Logging__Console__FormatterName: "simple"
      
    # prevent the user that runs the hashing service from having unneeded permissions
    cap_drop:
      - ALL

Endpoints

The following table shows all endpoints available on the hashing service. All endpoints are available on both the HTTP and HTTPS ports.

URL	Description
/hash	Get a hashed demographic object
/ready	HTTP health check
/swagger	HTML view of Swagger documentation
/swagger/v1/swagger.json	OpenAPI v3 documentation
/metrics	Prometheus metrics for monitoring

Monitoring and Logging

The local hashing service generates run-time metrics using Prometheus so that you can monitor your instance(s) for health, performance, load, etc. Point your metrics collector to /metrics.

The local hashing service writes JSON logs to STDOUT and should be available in whatever hosting solution you use. To generate logs in a human friendly format, set the Logging__Console__FormatterName environment variable to simple (as shown in the docker-compose.yaml above).