How to Run Keyless Agent

This page talks through how to set-up and run IDV Bridge On-Premise (Keyless agent) and the required configurations.

Infrastructure Requirements

Keyless agent requires the following minimum versions and infrastructure in order to run:

• Kubernetes 1.32+

• Helm (if the chosen installation method is helm)

In terms of performance we typically find a single assistance of the Keyless Agent will perform as per the below (2000 mCPUs, 8000 Mi RAM):

• 5 req in parallel

• 3 sec for each image processed

• Horizontal-Scaling Ready (online mode only)

Pull the Docker image

The Docker image is available on Keyless Quay repository. First, execute a docker login:

docker login -u="keyless_technologies+<PROVIDED_TENANT_NAME>" -p="<PROVIDED_PASSWORD>" quay.io

Then, proceed with pulling the container:

dockerpullquay.io/keyless_technologies/keyless-agent:v2.0.1

Note - The Image can be also installed via the official helm chart which can be provided upon request - just ask your given contact from our technical services team.

Running Keyless Agent

Customers can run this on their own as docker image or utilize our helm chart.

Once the docker image is setup to run the service, the service is configured via the following environment variables. If there is no default then it is required.

• NUM_OF_CIRC - Number of circuits to create during enrollment (default: 25 )

To enable online enrollment, the following environment variables are required. If not set the online enrollment will be disabled:

• AUTH_SERVER_URL - URL of the keyless auth server (same as host passed to SDK)

• AUTH_SERVER_API_KEY - API key for the keyless auth server (same as api key passed to SDK)

To configure the HTTP server:

• PORT - port for HTTP server to listen on (default: 80)

• HTTP_KEEP_ALIVE - HTTP keep-alive timeout in seconds (default: 75)

• WEB_WORKERS - The number of worker processes for handling requests. (default: 1); more workers slows startup time but increases throughput

• MAX_REQUESTS - The maximum number of requests a worker will process before restarting. (default: 10); If this is set to zero then the automatic worker restarts are disabled.

• MAX_REQUESTS_JITTER - The maximum jitter to add to the max_requests setting. (default: 2); The jitter causes the restart per worker to be randomized.

Note that the defaults are set-up to run the service in a very conservative mode, designed for low resource usage and low throughput. For higher throughput following settings are recommended for a 2 core 8GB machine:

• WEB_WORKERS=2 (or 3) there should be at least 2 workers to handle requests concurrently.

• MAX_REQUESTS=100 to restart workers after processing 100 requests, processing images require a lot of memory and this will help to keep memory usage in check.

• MAX_REQUESTS_JITTER=10 this adds some jitter to the restarts to avoid all workers restarting at the same time.

Understanding circuits for Authentication

Circuits are a key concept in the Keyless platform to ensure we remain 100% Privacy-preserving. They ensure that our cryptographic transformation is a unique process for every user, on every device and for every authentication which prevents any reverse engineering attempts by bad actors.

These circuits are generated on the client side (e.g., the IDV bridge) and sent to the server. Each authentication request consumes one circuit, and a successful authentication replenishes the circuit supply. However, if a user repeatedly fails authentication, the circuits may become exhausted. When this occurs, the user must re-enroll. The maximum number of circuits therefore determines the maximum number of consecutive failed authentication attempts allowed before the account is locked and re-enrollment is required, with the trade-off that setting this maximum too high will start to effect performance. The default is set to 25 and we generally would advise against changing this without good reason.