Configuration

The server is configured via a file named secrets.json. This file is included in the root of the distribution package that you have received and was automatically used when you started the server. You can, however, customize the values in this file. The default file (if you opted to generate the isssuer's private key looks like the following):

{
  "api_key": "wfMIgreFfMxDXySTU/MqNaFPJBIZcc40BQ62uQMwwd0=",
  "mobile_api_key": "S+ILGn9HOYKvgbt6MbqwJHknYajIeVn/bJJBjyLffFQ=",
  "jwt_secret": "ujfj1hiaiwaMsWnoiMDE1uKNHaD45Yu8hpscRggql5s=",
  "issuers_private_key": "v1ScMMYqPLUbFU5N6A4a+H9znA9+fi/WHWf61yivPts="
}

The following keys can be defined in the JSON:

1. api_key - this value defines a secret API key that you can use to make a server-to-server call to an end-point on the SenseCrypt server. The api-key is not meant for use with the mobile SDKs.
2. mobile_api_key - this value defines a secret API key that you can use to make a mobile to server call from the SenseCrypt Online Mobile SDK. The mobile_api_key must be used only with the mobile SDK. It cannot be used to make a server-to-server call to any of the end-points on the SenseCrypt server.
3. issuers_private_key (optional) - Secret key used to cryptographically sign all generated SensePrints. When set, every SensePrint issued by the server carries a signature that mobile clients can verify using set_issuers_public_key() in the offline SDK.

• Supports both Secp256k1 and ML-DSA key types. Note: ML-DSA keys cannot be used for QR SensePrints (signatures are too large); use Secp256k1 if QR support is needed.
• Can be set in secrets.json as "issuers_private_key" or as the environment variable ISSUERS_PRIVATE_KEY.
• This value was automatically set to a random key if you selected yes to generating issuer's public/private key pair while starting the server.
• You should not change this value manually unless you know how to generate a key-pair using the Secp256k1 elliptic curve.
• Furthermore, when it is set, generated SensePrints are signed using this key. Thus, for the SenseCrypt Offline Mobile SDK, correspondingly, the issuers_public_key must be set in the constants so that the offline mobile SDK can verify that SensePrints are issued by the correct issuer. To learn more about the effects of setting the issuers key pair checkout our overview.

4. pki_private_key (optional) - Secret key that enables the Face PKI subsystem. When set, the server acts as a Certificate Authority and can issue, sign, and verify X.509-style face certificates — certificates cryptographically bound to a user's face biometric.

• Supports both Secp256k1 and ML-DSA key types.
• Can be set in secrets.json as "pki_private_key" or as the environment variable PKI_PRIVATE_KEY.
• When this key is set, the following Face PKI endpoints become available:
  ▎ - POST /generate-face-certificate — issue a face-bound certificate signed by the server's PKI
  ▎ root
  ▎ - GET /root-certificate — retrieve the server's root certificate (derived from this key)
  ▎ - POST /verify-face-certificate — verify a face certificate against the root and a live face
  ▎ scan
  ▎ - POST /verify-face-signature — verify a face signature using the certificate chain
  ▎ - POST /encrypt-with-face-certificate — encrypt data using a face certificate
  ▎ - POST /face-decrypt — decrypt data that was encrypted with a face certificate
  ▎
  ▎ The following Face PKI endpoints work without this key (no certificate chain required):
  ▎ - POST /face-sign — sign data using a key derived from the user's face
  ▎ - POST /face-public-key — derive the face-bound public key for a given purpose ID
  ▎ - POST /verify-face-signature-with-public-key — verify a face signature using a raw public
  ▎ key

5. app_thumbprints_android (optional) - For the SenseCrypt Online Mobile SDK Online, a thumbprint is displayed in the app's settings and is also available as a mobile SDK API call. Your app may have different thumbprints while in development and in production (on the Play Store). If you set these thumbprints as comma separated values for this configuration, the server will not accept requests from any app that is not legitimate (has a different thumbprint).

6. jwt_secret (optional) - this value defines the secret used for JWT token generated on the /gen-jwt endpoint. See the Using a JWT Token for Mobile Authorization section for more information.
7. jwt_expire_seconds (optional) - this value defines the lifetime of JWT tokens generated by the /gen-jwt endpoint. The default value is 300 = 5 minutes.
8. REQUEST_TIMEOUT (optional) defines in seconds until a mobile request is considered as timeout. Default is 10 seconds. This variable can only be set as env variable on the container. Not in the secrets.json.

If you change the values in secrets.json, you will need to stop the container and restart it again.

First list the containers:

> docker ps

After observing the value for CONTAINER ID, you can stop it using:

> docker stop 336180357b1d

Once the docker is stopped, you can start it again using the process described in Starting the server.