- The client sends a registration request with (LDAP) account credentials to the SSU backend; the client forgets about the credentials directly after sending the request
- The SSU backend verifies the credentials, and on success, creates a client certificate which gets sent to the client
- The client stores the certificate, and uses it for future requests for authentication. This allows for user specific per-device registrations which can be individually revoked on the SSU backend without keeping parts of the regular account credentials on the device
The username may be sent together with a domain (like user\@example), with the SSU backend in charge of mapping that domain to a different LDAP organization, accounts database, or anything else useful for the given organization. The domain will be stored on both device and SSU backend, and allows for using different repository configurations for members of different organizations as well as limiting repository access for some domains.
The client-side implementation for this is in libssu, available through the SSU CLI and the ssud DBUS API.
Zypper only allows using user/password pairs for authentication. To avoid patching zypper this method of authentication is used, the device retrieves authentication tokens from the SSU server after successfully authenticating there with the client certificate.
Additional benefits of this method are easier deployment of repositories -- maintaining a huge list of individual credentials on the repository server can be tricky, especially on CDNs. Authenticating against a list of client certificates in such a scenario would be even more problematic.
The repository protection should change the passwords in regular intervals, and keep the passwords on the repository server and SSU backend in sync. Validity of old and new credentials should overlap slightly. As devices are sharing credentials for repository access this is the week point in this setup, so credentials should be changed often enough to make them useless before they are discovered/used on leaks.
Updating of on-device credentials happens within the URL resolver plugin for Zypper. On repository refresh,
- before returning the URL SSU checks if this repository requires authentication
- checks the time of last credentials update
- if the stored credentials are too old, authenticate to the SSU backend with the client certificate, and request a new set of credentials
- store the credentials on disk for Zypper to use
- return the resolved URL, and hand over to Zypper
The SSU backend checks if the user is still a valid (LDAP) user, and removes the registration for deleted/locked users. The device side removes on-device credentials if the SSU backend authentication fails.
/*! @page rndssu_clientprotocol Client protocol definition for RnD SSU
@section intro Introduction
This page contains the protocol definition used between a SSU client on a device and a SSU server. The client-side of this protocol is implemented in libssu and the SSU CLI. The server side heavily depends on the available infrastructure, and is not available in public. See \ref rndssu_implementation_notes "the implementation notes for RnD SSU" for additional details required to implement a SSU server.
$DEVICEID in the following examples is a variable filled by the SSU client before making the request, replaced by the devices IMEI (QSystemDeviceInfo::imei()), or a unique device ID (QSystemDeviceInfo::uniqueDeviceID()), if the IMEI is not available (netbooks, SDK, ...)
@section registration Device registration
- The client sends a POST request to https://ssu.example.com/ssu/device/$DEVICEID/register.xml
- The client MUST verify the servers certificate against the configured CA for this SSU server
- The client MUST send HTTP basic auth information with the request, containing (LDAP) account credentials queried from the user
- The client MUST NOT save (LDAP) account credentials obtained from the user on the device
- The client MAY send additional parameters in the requests body as content type application/x-www-form-urlencoded. Valid parameters are:
- deviceModel, optional, a string specifying the device to be registered (e.g. "N9")
- versionId, optional, a number specifying the protocol version. If set, the server MUST respond either with the requested version, or with an HTTP error code
- domain, optional, a string specifying domain for registration (e.g. "example", "example-investor", "example-developer")
- The server responds with HTTP status 200 on success, or an appropriate HTTP error code on error
- On success, the server MUST include and XML response, including
- certificate, mandatory, a string containing a PEM formatted SSL client certificate
- privateKey, mandatory, a string containing a PEM formatted SSL private key
- deviceId, mandatory, a string containing the devices IMEI or unique ID
- action, mandatory, a string containing the requested action
- protocolVersion, mandatory, a number specifying the protocol version used by the server. If the client requested a specific version the server MUST honour this request.
- On success, if the device ID has already been registered, the server MAY include a replaces element in the XML response, including
- user, mandatory, a string containing the username the device has been registered to before
- The client sends a GET request to https://ssu.example.com/ssu/device/$DEVICEID/credentials.xml
- The client MUST send a certificate with the request
- The client MUST NOT send any kind of (LDAP) account credentials (which it should not know about anyway, at this point)
- The client MAY send additional parameters as URL parameters. Valid parameters are:
- versionId, optional, a number specifying the protocol version. If set, the server MUST respond either with the requested version, or with an HTTP error code
- The server responds with HTTP status 200 on success, or an appropriate HTTP error code on error
- On success, the server MUST include and XML response, including
- credentials, mandatory, may be used several times, an element with attribute "scope", containing
- username, mandatory, a string specifying the new username
- password, mandatory, a string specifying the new password
- action, mandatory, a string containing the requested action
- protocolVersion, mandatory, a number specifying the protocol version used by the server. If the client requested a specific version the server MUST honour this request.
- deviceId, mandatory, a string containing the devices IMEI or unique ID
