v1alpha1

Documentation

Overview

Package v1alpha1 contains API definitions that can be used outside of this codebase in their alpha form. These APIs are not considered to be stable at HEAD.

Index

• Constants
• type ExposureKey
• type ExposureKeys
• type Publish
• type PublishResponse
• type TransmissionRiskOverride
• type TransmissionRiskVector
  • func (a TransmissionRiskVector) Len() int
  • func (a TransmissionRiskVector) Less(i, j int) bool
  • func (a TransmissionRiskVector) Swap(i, j int)
• type VerificationClaims
  • func NewVerificationClaims() *VerificationClaims

Constants

const (
	// only valid exposure key keyLength
	KeyLength = 16

	// Transmission risk constraints (inclusive..inclusive)
	MinTransmissionRisk = 0 // 0 indicates, no/unknown risk.
	MaxTransmissionRisk = 8

	// Intervals are defined as 10 minute periods, there are 144 of them in a day.
	// IntervalCount constraints (inclusive..inclusive)
	MinIntervalCount = 1
	MaxIntervalCount = 144

	// interval length
	IntervalLength = 10 * time.Minute
)

The following constants are generally useful in implementations of this API and for clients as well..

const (
	// ExposureKeyHMACClaim is the JWT claim key for the HMAC of the TEKs
	ExposureKeyHMACClaim = "tekmac"
	// TransmissionRiskOverrideClaim is the JWT Claim key for transmission risk overrides
	TransmissionRiskOverrideClaim = "trisk"
	// ReportTypeClaim is the JWT claim for the report type (confirmed|likely|negative)
	ReportTypeClaim = "reportType"
	// SymptomOnsetIntervalClaim is the JWT claim for the interval representing the symptom onset.
	SymptomOnsetIntervalClaim = "symptomOnsetInterval"
	// TestDateIntervalClaim is the JWT claim for the interval representing the test date
	TestDateIntervalClaim = "testDateInterval"
	// KeyIDHeader is the standard JWT key ID header name.
	KeyIDHeader = "kid"

	// ReportTypeConfirmed indicates to set ReportType.CONFIRMED_TEST
	ReportTypeConfirmed = "confirmed"
	// ReportTypeClinical indicates to set ReportType.CONFIRMED_CLINICAL_DIAGNOSIS
	ReportTypeClinical = "likely"
	// ReportTypeNegative is allowed by the verification flow. These keys are not saved in the system.
	ReportTypeNegative = "negative"

	TransmissionRiskUnknown           = 0
	TransmissionRiskConfirmedStandard = 2
	TransmissionRiskClinical          = 4
	TransmissionRiskNegative          = 6
)

Types

type ExposureKey

type ExposureKey struct {
	Key              string `json:"key"`
	IntervalNumber   int32  `json:"rollingStartNumber"`
	IntervalCount    int32  `json:"rollingPeriod"`
	TransmissionRisk int    `json:"transmissionRisk"` // DEPRECATED
}

ExposureKey is the 16 byte key, the start time of the key and the duration of the key. A duration of 0 means 24 hours. - ALL fields are REQUIRED and must meet the constraints below. Key must be the base64 (RFC 4648) encoded 16 byte exposure key from the device. - Base64 encoding should include padding, as per RFC 4648 - if the key is not exactly 16 bytes in length, the request will be failed - that is, the whole batch will fail. IntervalNumber must be "reasonable" as in the system won't accept keys that

are scheduled to start in the future or that are too far in the past, which
is configurable per installation.

IntervalCount must >= `minIntervalCount` and <= `maxIntervalCount`

1 - 144 inclusive.

transmissionRisk must be >= 0 and <= 8.

Transmission risk is depercated, but should still be populated for compatibility
with olrder clients. If it is omitted, and there is a valid report type,
then transmissionRisk will be set to 0.
IF there is a report type from the verification certificate AND tranismission risk
 is not set, then a report type of
  CONFIRMED will lead to TR 2
  LIKELY will lead to TR 4
  NEGATIVE will lead to TR 6

type ExposureKeys

type ExposureKeys struct {
	Keys []ExposureKey `json:"temporaryExposureKeys"`
}

ExposureKeys represents a set of ExposureKey objects as input to export file generation utility. Keys: Required and must have length >= 1.

type Publish

type Publish struct {
	Keys                 []ExposureKey `json:"temporaryExposureKeys"`
	Regions              []string      `json:"regions"`
	AppPackageName       string        `json:"appPackageName"`
	VerificationPayload  string        `json:"verificationPayload"`
	HMACKey              string        `json:"hmackey"`
	SymptomOnsetInterval int32         `json:"symptomOnsetInterval"`
	RevisionToken        string        `json:"revisionToken"`

	Padding string `json:"padding"`

	Platform                  string `json:"platform"`                  // DEPRECATED
	DeviceVerificationPayload string `json:"deviceVerificationPayload"` // DEPRECATED
}

Publish represents the body of the PublishInfectedIds API call. Keys: Required and must have length >= 1 and <= 21 (`maxKeysPerPublish`) Regions: Array of regions. System defined, must match configuration. AppPackageName: The identifier for the mobile application.

• Android: The App Package AppPackageName
• iOS: The BundleID

VerifcationPayload: The Verification Certificate from a verification server. HMACKey: the device generated secret that is used to recalculate the HMAC value

that is present in the verification payload.

SymptomOnsetInterval: An interval number that aligns with the symptom onset date.

• Uses the same interval system as TEK timing.
• Will be rounded down to the start of the UTC day provided.
• Will be used to calculate the days +/- symptom onset for provided keys.
• MUST be no more than 14 days ago.
• Does not have to be within range of any of the provided keys (i.e. future key uploads)

revisionToken: An opaque string that must be passed intact on additional

publish requests from the same device, where the same TEKs may be published
again.

Padding: random base64 encoded data to obscure the request size. The recommendation is that padding be at least 1kb in size with a random jitter of at least 1kb. Maximum overall request size is capped at 64kb for the serialized JSON.

The following fields are deprecated, but accepted for backwards-compatibility: DeviceVerificationPayload: (attestation) Platform: "ios" or "android"

type PublishResponse

type PublishResponse struct {
	RevisionToken     string   `json:"revisionToken"`
	InsertedExposures int      `json:"insertedExposures"`
	Error             string   `json:"error"`
	Padding           string   `json:"padding"`
	Warnings          []string `json:"warnings,omitempty"`
}

PublishResponse is sent back to the client on a publish request. If successful, the revisionToken indicates an opaque string that must be passed back if the same devices wishes to publish TEKs again.

On error, the error field will contain the error details.

The Padding field may be populated with random data on both success and error responses.

The Warnings field may be populated with a list of warnings. These are not errors, but may indicate the server mutated the response.

type TransmissionRiskOverride

type TransmissionRiskOverride struct {
	TransmissionRisk     int   `json:"tr"`
	SinceRollingInterval int32 `json:"sinceRollingInterval"`
}

TransmissionRiskOverride is an individual transmission risk override.

type TransmissionRiskVector

type TransmissionRiskVector []TransmissionRiskOverride

TransmissionRiskVector is an additional set of claims that can be included in the verification certificate for a diagnosis as received from a trusted public health authority. DEPRECATED - If received at a server, these values are ignored. Will be removed in v0.3

func (TransmissionRiskVector) Len

func (a TransmissionRiskVector) Len() int

func (TransmissionRiskVector) Less

func (a TransmissionRiskVector) Less(i, j int) bool

Less sorts the TransmissionRiskVector vector with the largest SinceRollingPeriod value first. Descending sort.

func (TransmissionRiskVector) Swap

func (a TransmissionRiskVector) Swap(i, j int)

type VerificationClaims

type VerificationClaims struct {
	// ReportType is one of 'confirmed', 'likely', or 'negative' as defined by the constants in this file.
	ReportType string `json:"reportType"`
	// SymptomOnsetInterval uses the same 10 minute interval timing as TEKs use. If an interval is provided that isn not the
	// start of a UTC day, then it will be rounded down to the beginning of that UTC day. And from there the days +/- symptom
	// onset will be calculated.
	SymptomOnsetInterval uint32 `json:"symptomOnsetInterval"`

	// Deprecated, but not scheduled for removal.
	// TransmissionRisks will continue to be supported. On newer versions of the device software,
	// the ReportType and days +/- symptom onset will be used.
	TransmissionRisks TransmissionRiskVector `json:"trisk,omitempty"`

	SignedMAC string `json:"tekmac"`
	jwt.StandardClaims
}

VerificationClaims represents the accepted Claims portion of the verification certificate JWT. This data is used to set data on the uploaded TEKs and will be reflected on export. See the export file format: https://github.com/google/exposure-notifications-server/blob/main/internal/pb/export/export.proto#L73

func NewVerificationClaims

func NewVerificationClaims() *VerificationClaims

NewVerificationClaims initializes a new VerificationClaims struct.