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 (key) is the base64-encoded 16 byte exposure key from the device. The
	// base64 encoding should include padding, as per RFC 4648. If the key is not
	// exactly 16 bytes in length, the whole batch will fail.
	Key string `json:"key"`

	// IntervalNumber (rollingStartNumber) 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.
	IntervalNumber int32 `json:"rollingStartNumber"`

	// IntervalCount (rollingPeriod) must >= minIntervalCount and <=
	// maxIntervalCount, 1 - 144 inclusive.
	IntervalCount int32 `json:"rollingPeriod"`

	// TransmissionRisk (transmissionRisk) must be >= 0 and <= 8. This field is
	// optional, but should still be populated for compatibility with older
	// 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 transmission risk 2
	//   - LIKELY will lead to transmission risk 4
	//   - NEGATIVE will lead to transmission risk 6
	//
	TransmissionRisk int `json:"transmissionRisk,omitempty"` // 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.

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 (temporaryExposureKeys) is the list of TEKs and is required. The array
	// must have more than 1 element and less than 21 elements
	// (maxKeysPerPublish).
	Keys []ExposureKey `json:"temporaryExposureKeys"`

	// Regions (regions) is the list of regions for the upload. This must match
	// the system configuration.
	Regions []string `json:"regions"`

	// AppPackageName (appPackageName) is the identifier for the mobile
	// application:
	//
	//   - Android: The App Package AppPackageName
	//   - iOS: The BundleID
	//
	AppPackageName string `json:"appPackageName"`

	// VerificationPayload (verificationPayload) is the certificate from a
	// verification server.
	VerificationPayload string `json:"verificationPayload"`

	// HMACKey (hmacKey) is the device-generated secret that is used to
	// recalculate the HMAC value that is present in the verification payload.
	HMACKey string `json:"hmackey"`

	// SymptomOnsetInterval (symptomOnsetInterval) is 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)
	//
	SymptomOnsetInterval int32 `json:"symptomOnsetInterval"`

	// RevisionToken (revisionToken) is an opaque string that must be passed
	// intact on additional publish requests from the same device, where the same
	// TEKs may be published again.
	RevisionToken string `json:"revisionToken"`

	// Padding (padding) is random, base64-encoded data to obscure the request
	// size. The server will not process this data in any way. 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.
	Padding string `json:"padding"`

	// Platform (platform) must be one of "ios" or "android".
	//
	// DEPRECATED: This field has been deprecated.
	Platform string `json:"platform"`

	// DeviceVerificationPayload is the DeviceCheck or SafetyNet attestion.
	//
	// DEPRECATED: This field has been deprecated.
	DeviceVerificationPayload string `json:"deviceVerificationPayload"`
}

Publish represents the body of the PublishInfectedIds API call. Please see the individual fields below for details on their values.

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.

func NewVerificationClaims

func NewVerificationClaims() *VerificationClaims

NewVerificationClaims initializes a new VerificationClaims struct.