Asset

Uniquely identifies an asset.

A digital asset is an identifiable and addressable online entity that typically provides some service or content. Examples of assets are websites, Android apps, Twitter feeds, and Plus Pages.

JSON representation 
{
  // Union field, only one of the following:
  "web": {
    object(WebAsset)
  },
  "androidApp": {
    object(AndroidAppAsset)
  },
}
Field name Type Description
Union field, only one of the following:
web object(WebAsset) Set if this is a web asset.
androidApp object(AndroidAppAsset) Set if this is an Android App asset.

WebAsset

Describes a web asset.

JSON representation 
{
  "site": string,
}
Field name Type Description
site string

Web assets are identified by a URL that contains only the scheme, hostname and port parts. The format is

http[s]://<hostname>[:<port>]

Hostnames must be fully qualified: they must end in a single period (".").

Only the schemes "http" and "https" are currently allowed.

Port numbers are given as a decimal number, and they must be omitted if the standard port numbers are used: 80 for http and 443 for https.

We call this limited URL the "site". All URLs that share the same scheme, hostname and port are considered to be a part of the site and thus belong to the web asset.

Example: the asset with the site https://www.google.com contains all these URLs:

  • https://www.google.com/
  • https://www.google.com:443/
  • https://www.google.com/foo
  • https://www.google.com/foo?bar
  • https://www.google.com/foo#bar
  • https://user@password:www.google.com/

But it does not contain these URLs:

  • http://www.google.com/ (wrong scheme)
  • https://google.com/ (hostname does not match)
  • https://www.google.com:444/ (port does not match) REQUIRED

AndroidAppAsset

Describes an android app asset.

JSON representation 
{
  "packageName": string,
  "certificate": {
    object(CertificateInfo)
  },
}
Field name Type Description
packageName string Android App assets are naturally identified by their Java package name. For example, the Google Maps app uses the package name com.google.android.apps.maps. REQUIRED
certificate object(CertificateInfo)

Because there is no global enforcement of package name uniqueness, we also require a signing certificate, which in combination with the package name uniquely identifies an app.

Some apps' signing keys are rotated, so they may be signed by different keys over time. We treat these as distinct assets, since we use (package name, cert) as the unique ID. This should not normally pose any problems as both versions of the app will make the same or similar statements. Other assets making statements about the app will have to be updated when a key is rotated, however.

(Note that the syntaxes for publishing and querying for statements contain syntactic sugar to easily let you specify apps that are known by multiple certificates.) REQUIRED

CertificateInfo

Describes an X509 certificate.

JSON representation 
{
  "sha256Fingerprint": string,
}
Field name Type Description
sha256Fingerprint string

The uppercase SHA-265 fingerprint of the certificate. From the PEM certificate, it can be acquired like this:

$ keytool -printcert -file $CERTFILE | grep SHA256:
SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
    42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

or like this:

$ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
    16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

In this example, the contents of this field would be 14:6D:E9:83:C5:73: 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF: 44:E5.

If these tools are not available to you, you can convert the PEM certificate into the DER format, compute the SHA-256 hash of that string and represent the result as a hexstring (that is, uppercase hexadecimal representations of each octet, separated by colons).