Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
140 lines (113 sloc) 3.85 KB

credentials.zip file format

The credentials.zip file provides the link between a user’s on-line account on HERE OTA Connect and the developer’s machine. It is used for:

  • Uploading the built OSTree image to treehub with garage-push

  • Offline-signing Uptane images targets metadata with garage-sign

  • Provisioning the device with Aktualizr or aktualizr-cert-provider

  • Providing the URL to the update server to Aktualizr (for implicit provisioning this is templated into sota.toml at build time, to allow software updates to modify that URL)

The following files are present in credentials.zip:

Filename in zip Purpose Used by

treehub.json

Location and authentications for treehub and Uptane repo

garage-sign, garage-push

client.crt

Certificate for TLS client authentication

garage-push

client.key

Private key for TLS client authentication

garage-push

root.crt

Root CA for TLS client authentication

garage-push

autoprov_credentials.p12

TLS client credentials for automatic device provisioning

aktualizr, aktualizr-cert-provider

autoprov.url

URL for automatic provisioning server

aktualizr, aktualizr-cert-provider

root.json

Initial Uptane root.json (for secure bootstrapping)

garage-sign

targets.pub

Public key for offline Uptane image signing

garage-sign

targets.sec

Private key for offline Uptane image signing

garage-sign

tufrepo.url

URL to Uptane repository

garage-sign

treehub.json

The treehub.json file points to the treehub installation, and also includes authentication information that is used for both treehub and Uptane metadata uploads.

The general format is like this:

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  },
  // Authentication information
}

Multiple types of authentication are supported, and more types may be added in the future. Clients should ignore unrecognised authentication types, and the server may add multiple authentication types to support both old and new clients.

No authentication (e.g. community edition)

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  },
  "no_auth" : true,
}

OAUTH2 authentication (HERE OTA Connect)

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  },
  "oauth": {
    "server": "https://example.com/",
    "client_id": "xas234fs4",
    "client_secret": "f5634fdxas234fs4dxas234fs4"
  }
}

HTTP Basic authentication

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  },
  "basic_auth": {
    "user": "bob",
    "password": "secret123"
  }
}

TLS Client Certificate authentication

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  },
  "certificate_auth": true,
}

Invalid examples

The following should be rejected. No authentication entry:

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  }
  // INVALID!
}

No recognised authentication entries:

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  },
  "xaxaxaxa": { ... }, // INVALID!
  "oauthv999": { ... }
}

In the case the TLS client key, client certificate and root CA are provided as separate files in credentials.zip

Compatibility case

If a future server supports a new authentication method, called 'oauthv3' for this example, then the server would construct a treehub.json with the following content:

{
  "ostree": {
    "server": "https://localhost:2443/api/v3"
  },
  "oauth": { ... } // Old clients read this
  "oauthv3": { ... } // New clients read this
}

Old clients will ignore the oauthv3 key because they don’t recognise it, but new clients will recognise both, and know that oauthv3 should take presidence over oauth.

Test Cases

There are a set of test cases for this in aktualizr/tests/sota_tools