Device Authentication

Starting in Cobalt 20, initial URL requests will now have query parameters appended to them signed by the platform's secret key. The key is provided during the certification process. The key must be stored in secure storage on the device.

Message

When constructing the URL for the initial browse request, according to the logic in cobalt/browser/device_authentication.cc, it will fetch from the platform a "certification scope" string provided to the device during certification. The certification scope will be queried by a call to SbSystemGetProperty(kSbSystemPropertyCertificationScope, ...), which the platform is expected to implement. Along with the current system time, this forms the message that must be signed by the device's secret key.

Signing

The message defined above must be signed with the HMAC-SHA256 algorithm. The resulting digest (encoded as base64), alongside the unencrypted message contents, will be appended to the initial URL.

Two choices exists for how platforms can expose the secret key to Cobalt. Cobalt will first attempt to have the platform sign the message, and if that functionality is not implemented Cobalt will query the platform for the secret key and sign the message itself. If neither choice is implemented, then Cobalt will log a warning and not append anything to the URL.

Platform signing

Cobalt will first attempt to use the SbSystemSignWithCertificationSecretKey() function to sign the message using the secret key. This method is preferred since it enables implementations where the key exists only in secure hardware and never enters the system's main memory. A reference implementation, which depends on BoringSSL, is as follows:

bool SbSystemSignWithCertificationSecretKey(
    const uint8_t* message, size_t message_size_in_bytes,
    uint8_t* digest, size_t digest_size_in_bytes) {
  return starboard::shared::deviceauth::SignWithCertificationSecretKey(
      kBase64EncodedCertificationSecret,
      message, message_size_in_bytes, digest, digest_size_in_bytes);
}

Cobalt signing

If the function SbSystemSignWithCertificationSecretKey() is unimplemented (e.g. it returns false, as is done in starboard/shared/stub/system_sign_with_certification_secret_key.cc), then Cobalt will instead attempt to retrieve the secret key from the system by a call to SbSystemGetProperty(kSbSystemPropertyBase64EncodedCertificationSecret, ...), and use it to produce the HMAC-SHA256 digest of the message itself.