User Guide on entici

API documentation

Mon, 01 Jan 0001 00:00:00 +0000

The following table gives an overview of all available REST interfaces.

Name	Since	Method	Path	Consumes
Pseudonymize	v1.0.0	POST	`/v1/process`	Bundle
Pseudonymize (batch)	v2.1.0	POST	`/v1/process/all`	Array of Bundles
Pseudonymize (Param)	v5.1.0	POST	`/entitylist/psn-service/$pseudonymize`	Parameters
Exists	v5.1.0	POST	`/entitylist/psn-service/pseudonym/exists`	Bundle
Depseudonymize	v4.0.0	POST	`/v1/resolve`	Bundle
Save Pseudonym	v2.1.0	POST	`/entitylist/psn-service/pseudonym/save`	Parameters
Get Bloomfilter	v2.1.0	POST	`/entitylist/psn-service/bloomfilter`	Parameters
Translate Pseudonym	v5.3.0	POST	`/entitylist/depsn-service/pseudonym/translate`	Bundle

Pseudonymize

This REST interface accepts a FHIR Bundle as input.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

For authorization and authentication purposes an entici instance requires a Keycloak server with a preconfigured trustcenter realm.

Figure 1. Overview of required Keycloak clients.

Figure 1 shows an overview of all relevant clients. The legend at the top visualizes the OAuth2 roles by using different background colors. It can be seen that in Keycloak a client can act both as resource server and as client at the same time (e.g. entitylist-webapp). The client trustcenter-test is available for testing an external interface of the trustcenter (e.g. /v1/process/). See Smoke Test for more details about how to run the test.

Pseudonym Generation

Mon, 01 Jan 0001 00:00:00 +0000

In entici, we distinguish between internal and external pseudonyms. The internal pseudonym is the default pseudonym which will be generated whenever a new resource is pseudonymized. Therefore, the relation between resource and internal pseudonym is 1:1.

In addition, an arbitrary number of external pseudonyms may be generated for one resource. This mechanism enables project-based pseudonymization. Therefore, the relation between resource and external pseudonym is 1:N.

All pseudonyms are generated via a cryptographically strong random number generator (RNG). In the unlikely case of a collision, a fall-back mechanism is in place to guarantee unique pseudonyms.

Performance Tuning

Mon, 01 Jan 0001 00:00:00 +0000

Parallel Processing

Pseudonymization requests can be processed in parallel. The degree of parallelism is controlled by the following configuration parameter:

Name	Description	Default Value
`PSN_PARALLELISM_LEVEL`	Number of parallel threads used for pseudonymization. Minimum: `1` Maximum: `0.5 × number of available processors`	`8`

PSN_PARALLELISM_LEVEL=8

Increasing this value allows more requests to be handled concurrently. However, it also increases contention on the database and CPU. The practical upper bound is capped at half the number of available processors to avoid starving other system processes.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Issues with Keycloak Communication

For internal Keycloak instances, or external Keycloak service running on the same Docker host, the trustcenter service containers might face difficulties when connecting to the Keycloak instance (defined in KEYCLOAK_SERVER_NAME).

Issue #1: Firewall settings

Make sure not to block the entici service containers from connecting to the Docker host by the firewall. For Ubuntu UFW, this can be prevented by:

# [Setup I] Assuming: KEYCLOAK_SERVER_TYPE=Internal, SERVER_PORT=443
# Open HTTPS port 443
sudo ufw allow 443
# [Setup II] Assuming: KEYCLOAK_SERVER_TYPE=External, Keycloak on Docker host on port: 8443 
# Open HTTPS port 8443
sudo ufw allow 8443

Note that Docker-based published ports are bypassing the firewall policies anyhow on Ubuntu systems by default for external requests [August 2021].

Backup

Mon, 01 Jan 0001 00:00:00 +0000

For the following commands, make sure to replace <postgres-user> with your database user.

Save

docker exec -u postgres db_entitylist pg_dump -U <postgres-user> -Fc -c entitylist > dump_entitylist_`date +%d-%m-%Y"_"%H_%M_%S`.sql

Restore

docker exec -u postgres -i db_entitylist pg_restore -U <postgres-user> -Fc -c -d entitylist < <dump-file>