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.
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).