lacunasoftware/tsa repository overview

⁠Lacuna TSA

Time Stamping Server conforming to Time-Stamp Protocol (RFC 3161)

Recommended tag: lacunasoftware/tsa:1.2

⁠Prerequisites

• Lacuna PKI SDK license
• TSA certificate
• TSA key either in PKCS#12 or hosted on Amplia⁠

⁠Configuration

The following environment variables must be set:

• PkiSuite__SdkLicense: license for the PKI SDK in Base64

If the TSA key is on a PKCS#12 file, fill:

• KeyStore__Type: Pkcs12
• KeyStore__Pkcs12Content: PKCS#12 file in Base64
• KeyStore__Pkcs12Password: PKCS#12 file password

If the TSA key is hosted on Amplia, fill:

• KeyStore__Type: Amplia
• KeyStore__Certificate: TSA certificate in Base64 (or fill KeyStore__CertificateId)
• KeyStore__KeyId: ID of the key on Amplia
• KeyStore__CertificateId: ID of the certificate on Amplia. If the certificate was not issued on the same Amplia instance that hosts the key, leave blank and fill KeyStore__Certificate instead.
• Amplia__Endpoint: endpoint of the Amplia instance
• Amplia__ApiKey: API key for an application on the Amplia instance with Manager role

⁠Authentication

Authentication configuration is optional. By default, no authentication is enforced. To authenticate requests, fill the users configuration. For each user, fill:

• Authentication__Users__<Username>__Type: Basic or BearerToken
• Authentication__Users__<Username>__Password: password to be required for the user
• Authentication__Users__<Username>__BearerToken: bearer token to be required for the user
• Authentication__Users__<Username>__Disabled: set to True to disable user (defaults to False)

To disable authentication without clearing the users configuration, you may use:

• Authentication__Disabled: set to True to disable authentication (defaults to False)

⁠NTP synchronization

By default, the system clock is used to fetch the date/time that is included in each timestamp. You may optionally configure one or more NTP servers to be used as time sources. The application synchronizes periodically with the configured NTP servers and uses the first available server as time source.

• Ntp__SyncPeriodSeconds: delay between successful synchronizations in seconds (defaults to 3600 i.e. 1 hour)
• Ntp__RetryDelaySeconds: delay before retrying to sync with an NTP server (defaults to 60 i.e. 1 minute)
• Ntp__Servers__<ServerName>__Host: hostname or IP address of NTP server
• Ntp__Servers__<ServerName>__Port: port of NTP server (defaults to 123)
• Ntp__Servers__<ServerName>__Priority: if more than one NTP server is configure, specify the priority of each server. Smaller numbers mean higher priority (defaults to 0 i.e. highest priority)
• Ntp__Servers__<ServerName>__TimeoutMS: timeout in milliseconds when querying this NTP server (defaults to 1000 i.e. 1 second)

By default, if no servers can be contacted, the system clock is used. To require that at least one server be contacted at least once, set:

• Ntp__FallbackToSystemClock: set to False to disable using the system clock if no NTP servers can be reached (defaults to True)

Please note that if no NTP servers can be contacted and Ntp__FallbackToSystemClock=False, issuing of timestamps ceases until a NTP server can be contacted!

By default, if all servers are currently down or out-of-sync (see synchronization monitoring below), the offset from the latest server that was successfully synchronized is used. To cease issuing timestamps if no servers are in sync, set:

• Ntp__RequireSync: set to True to stop issuing timestamps if all NTP servers are currently down or out-of-sync (defaults to False). If set to True, then Ntp__FallbackToSystemClock is meaningless.

By default, the drift between the system clock and the NTP server is monitored on each synchronization. If the drift since the last synchronization is larger than the maximum acceptable drift, a warning is logged. To enforce the maximum drift, that is, to consider a NTP server as out-of-sync due to an unacceptable drift, set:

• Ntp__MaxDriftRateSecondsPerHour: maximum acceptable drift rate in seconds per hour (defaults to 5)
• Ntp__EnforceMaxDrift: set to True to consider a NTP server as out-of-sync due to an unacceptable drift (defaults to False)

Instead of monitoring the drift between the system clock and the NTP server after each synchronization, you may also monitor the absolute offset between the two clocks by configuring:

• Ntp__MaxOffsetSeconds: maximum acceptable offset between system clock and the NTP server (defaults to none, which means drift monitoring is used instead). If set, drift monitoring settings are ignored.
• Ntp__EnforceMaxOffset: set to True to consider a NTP server as out-of-sync due to an unacceptable offset (defaults to False)

To disable NTP without clearing the configuration, you may use:

• Ntp__Disabled: set to True to disable NTP synchronization (defaults to False)

To monitor NTP synchronization, set:

• Logging__LogLevel__Lacuna.Commons.NtpSync: Information

⁠Other settings

• Tsa__PolicyId: TSA policy ID (optional, defaults to 1.3.6.1.4.1.46332.4.1)
• Tsa__Tac: time attribute certificate in Base64 (optional, by default no TAC is included on timestamps)
• Tsa__CheckRequestType: whether to check the content type of incoming timestamp requests (optional, defaults to True)

⁠Changelog

⁠1.2.0 (2023-05-18)

• NTP synchronization improved with absolute drift monitoring, contingency options and improved logging

⁠1.1.0 (2023-05-15)

• Add NTP synchronization with offset drift monitoring

⁠1.0.0 (2023-05-10)

• Initial version