From 807f4027597bfe2a822bd71b6ea62d578de92852 Mon Sep 17 00:00:00 2001 From: Bernd Wachter Date: Wed, 17 Sep 2014 15:44:15 +0300 Subject: [PATCH] [doc] Add protocol documentation --- doc/src/mainpage.dox | 9 +++ doc/src/rndssu.dox | 54 ++++++++++++++++++ doc/src/rndssu_clientprotocol.dox | 95 +++++++++++++++++++++++++++++++ 3 files changed, 158 insertions(+) create mode 100644 doc/src/mainpage.dox create mode 100644 doc/src/rndssu.dox create mode 100644 doc/src/rndssu_clientprotocol.dox diff --git a/doc/src/mainpage.dox b/doc/src/mainpage.dox new file mode 100644 index 0000000..72899ec --- /dev/null +++ b/doc/src/mainpage.dox @@ -0,0 +1,9 @@ +/*! @mainpage SSU + + +@section intro Introduction + + +\ref rndssu "Using SSU in RnD setups" + +*/ \ No newline at end of file diff --git a/doc/src/rndssu.dox b/doc/src/rndssu.dox new file mode 100644 index 0000000..1824080 --- /dev/null +++ b/doc/src/rndssu.dox @@ -0,0 +1,54 @@ +/*! @page rndssu Overview of SSU RnD features + +@section intro Introduction + +SSU offers the ability to run in a special RnD mode for use during development. The main features are: + +- use a different set of repositories than for the published product +- allow using private (password-protected) repositories + +The objectives for the the implementation are: + +- Encourage people to update their devices instead of reflashing them + - Penalties for (i.e., additional steps required after flashing) are fine + - Penalties for updating a device must be avoided (for example, user interaction to keep device credentials for update access updated are not OK) +- Keep security impact on breach low without inconveniencing users + - If a device gets lost, allow excluding this device from receiving additional updates + - Do not store any part of the users credentials on the device, yet still keep track of individual devices and users they're associated with +- Stay as close to the way repository management works for the published product as possible +- Do the implementation without adding patches to upstream sources upstream would not accept + +@section rndssu_implementation_notes Implementation notes for repository protection + +See the \ref rndssu_clientprotocol client protocol definition for protocol details. + +@subsection rndssu_registration Device registration + +- 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. + +@subsection rndssu_repo_protection Protecting RnD repositories + +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. + +@subsection rndssu_credentialsupdate Updating on-device credentials + +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. +*/ \ No newline at end of file diff --git a/doc/src/rndssu_clientprotocol.dox b/doc/src/rndssu_clientprotocol.dox new file mode 100644 index 0000000..4724d1f --- /dev/null +++ b/doc/src/rndssu_clientprotocol.dox @@ -0,0 +1,95 @@ +/*! @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 + +Examples for valid responses from the server are: + +@code + + 1 + register + -----BEGIN CERTIFICATE----- +MIIDkjCCAnoCCQD/t7yBlPR2azANBgkqhkiG9w0BAQUFADCBijESMBAGA1UEAxMJ +bG[..] + -----BEGIN RSA PRIVATE KEY----- +Proc-Type: 4,ENCRYPTED +DEK-Info: DES-EDE3-CBC,306FB5F5BEC695CC + +02UJRwd8euWrs/ZKMoTjFHedvQLYjbC7MTtdiOytAmLV5eGiP27WWg07E67FgUv2 +GEiTCDb2pXDmiTR[...] + da39a3ee5e6b4b0d3255bfef95601890afd80709 + + + + 1 + register + -----BEGIN CERTIFICATE----- +MIIDkjCCAnoCCQD/t7yBlPR2azANBgkqhkiG9w0BAQUFADCBijESMBAGA1UEAxMJ +bG[..] + -----BEGIN RSA PRIVATE KEY----- +Proc-Type: 4,ENCRYPTED +DEK-Info: DES-EDE3-CBC,306FB5F5BEC695CC + +02UJRwd8euWrs/ZKMoTjFHedvQLYjbC7MTtdiOytAmLV5eGiP27WWg07E67FgUv2 +GEiTCDb2pXDmiTR[...] + da39a3ee5e6b4b0d3255bfef95601890afd80709 + + sampleuser + + +@endcode + +@section credentials_update Credentials update + +- 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 + +Examples for valid responses from the server are: + +@code + + 1 + credentials + + uNaepiu9 + Aeng5vah + + da39a3ee5e6b4b0d3255bfef95601890afd80709 + +@endcode +*/ \ No newline at end of file