Credentials

Station needs credentials for establishing a (secure) connection to both LNS and CUPS. A single credential definition consists of a set of up to four files which together form a credential set. The basename describes the purpose of the credential set and the file extension defines the type of contents.

Note

If no credential set for CUPS is provided, Station implicitly disables the CUPS functionality. In this case, at least one valid LNS credential set is required.

Files Types

The following four file types form a credential set and define the address of a server (either LNS or CUPS), how the server is authenticated by Station, and how Station authorizes its access to the server. Some of the files MAY be missing or empty in some modes (see Section Authentication Modes):

  • *.uri: The URI of the server to connect to. This SHALL be a simple ASCII file. The URI is either http, https, ws, or wss. If the URI indicates a non-TLS protocol scheme (i.e., http or ws), the subsequent files SHALL be missing or, if present, be empty. If a TLS-based scheme (i.e., https or wss) is specified, some or all of the other files MUST be present.
  • *.trust: The server’s CA certificate, which enables the Station to establish trust into the server. If the URI indicates a TLS-based scheme, this file MUST be present and contains a PEM-encoded X509 certificate.
  • *.crt: The Station’s own certificate if TLS client authentication is being used. If this is not empty, the corresponding key file MUST contain the private key matching this certificate.
  • *.key: The Station’s private key matching the corresponding cert file. If the cert file is missing or empty, this file, if present, SHALL contain an authorization token submitted in the HTTP header field Authorization when making requests to the server.

Categories and Sets

Station uses two different credential categories for connecting to LNS (prefix tc) and CUPS (prefix cups). For each category there are three different sets of credentials as listed below:

  • tc.\* / cups.\*: Regular credentials used to connect to LNS or CUPS, respectively. If these credentials are not available or do not work, the bak and boot variants will be tried alternatively. These files MAY be part of a system image or be updated by the Station process during an update session with a CUPS server.
  • tc-bak.\* / cups-bak.\*: Backup credentials are automatically created by Station. These are copies of the regular credentials made after a successful connection to the server and thereby are known to have worked at some point in time. These credentials are used as a fallback in case an update has wrecked the regular credentials.
  • tc-boot.\* / cups-boot.\*: Bootstrap credentials are optional and are used for an initial connection to a server. The server MAY limit its validity after a few uses. These credentials are again used as a fallback if the regular credentials fail to work, or if no regular credentials are available. The credentials MUST be provided as part of the system image and MAY be replaced or updated as part of firmware updates. Station never modifies these files.

Intermediate Files

All credential files are updated atomically. During this process some auxiliary files are used to mark certain stages in the transaction processing. The following files are used:

  • *-done.bak: Backup credentials are complete and valid. If this file is deleted, a new backup copy will be created.
  • *-temp.cpy: A backup copy is in progress and the bak files are possibly incomplete and inconsistent. This file is automatically removed once a backup copy is completed.
  • *-temp.{uri,trust,crt,key,upd}: Temporary files created during the credential update process with a CUPS server.