v1

Documentation

Overview

Package v1 contains API definitions that can be used outside of this codebase. The v1 API is considered stable. It will only add new optional fields and no fields will be removed.

Index

• Constants
• Variables
• type ExposureKey
• type ExposureKeys
• type Publish
• type PublishRequests
  • func (p *PublishRequests) Total() int64
• type PublishResponse
• type StatsDay
• type StatsRequest
• type StatsResponse
• type VerificationClaims
  • func NewVerificationClaims() *VerificationClaims
  • func (v *VerificationClaims) CustomClaimsValid() error

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

	// Error Code defintiions.
	// ErrorUnknownHealthAuthorityID indicates that the health authority was not found.
	ErrorUnknownHealthAuthorityID = "unknown_health_authority_id"
	// ErrorUnableToLoadHealthAuthority indicates a retryable error loading the configuration.
	ErrorUnableToLoadHealthAuthority = "unable_to_load_health_authority"
	// ErrorHealthAuthorityMissingRegionConfiguration indicautes the request can not accepted because
	// the specified health authority is not configured correctly.
	ErrorHealthAuthorityMissingRegionConfiguration = "health_authority_missing_region_config"
	// ErrorVerificationCertificateInvalid indicates a problem with the verification certificate.
	ErrorVerificationCertificateInvalid = "health_authority_verification_certificate_invalid"
	// ErrorBadRequest indicates that the client sent a request that couldn't be parsed correctly
	// or otherwise contains invalid data, see the extended ErrorMessage for details.
	ErrorBadRequest = "bad_request"
	// ErrorInternalError
	ErrorInternalError = "internal_error"
	// ErrorMissingRevisionToken indicates no reivison token passed when one is needed
	ErrorMissingRevisionToken = "missing_revision_token"
	// ErrorInvalidRevisionToken indicates a revision token was passed, but is missing a
	// key or has invalid metadata.
	ErrorInvalidRevisionToken = "invalid_revision_token"
	// ErrorKeyAlreadyRevised indicates one of the uploaded TEKs was marked for
	// revision, but it has already been revised.
	ErrorKeyAlreadyRevised = "key_already_revised"
	// ErrorInvalidReportTypeTransition indicates an uploaded TEK tried to
	// transition to an invalid state (like "positive" -> "likely").
	ErrorInvalidReportTypeTransition = "invalid_report_type_transition"
	// ErrorPartialFailure indicates that some exposure keys in the publish
	// request had invalid data (size, timing metadata) and were dropped. Other
	// keys were saved.
	ErrorPartialFailure = "partial_failure"
)

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
)

const (
	// ErrorUnauthorized is returned if the provided bearer token is invalid.
	ErrorUnauthorized = "unauthorized"
)

Variables

var (
	ValidReportTypes = map[string]bool{
		ReportTypeConfirmed: true,
		ReportTypeClinical:  true,
		ReportTypeNegative:  true,
	}
)

Types

type ExposureKey

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

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 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 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"`
	HealthAuthorityID    string        `json:"healthAuthorityID"`
	VerificationPayload  string        `json:"verificationPayload,omitempty"`
	HMACKey              string        `json:"hmacKey,omitempty"`
	SymptomOnsetInterval int32         `json:"symptomOnsetInterval,omitempty"`
	Traveler             bool          `json:"traveler,omitempty"`
	RevisionToken        string        `json:"revisionToken"`

	Padding string `json:"padding"`
}

Publish represents the body of the PublishInfectedIds API call. temporaryExposureKeys: Required and must have length >= 1 and <= 21 (`maxKeysPerPublish`) healthAuthorityID: The identifier for the mobile application.

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

verificationPayload: 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)

traveler - set to true if the TEKs in this publish set are consider to be the

keys of a "traveler" who has left the home region represented by this server
(or by the home health authority in case of a multi-tenant installation).

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 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.

Partial success: If at least one of the Keys passed in is valid, then the publish request will accept those keys, return a response code of 200 (OK) AND also return a 'Code' of ErrorPartialFailure allong with an error message of exactly which keys were not accepted and why. This does not indicate a failure that must be reported to the user, but does indicate an issue with the application making the upload (sending invalid data).

type PublishRequests

type PublishRequests struct {
	UnknownPlatform int64 `json:"unknown"`
	Android         int64 `json:"android"`
	IOS             int64 `json:"ios"`
}

func (*PublishRequests) Total

func (p *PublishRequests) Total() int64

type PublishResponse

type PublishResponse struct {
	RevisionToken     string   `json:"revisionToken,omitempty"`
	InsertedExposures int      `json:"insertedExposures,omitempty"`
	ErrorMessage      string   `json:"error,omitempty"`
	Code              string   `json:"code,omitempty"`
	Padding           string   `json:"padding,omitempty"`
	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 message will contain a message from the server and the 'code' field will contain one of the constants defined in this file. The intent is that code can be used to show a localized error message on the device.

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 StatsDay

type StatsDay struct {
	// Day will be set to midnight UTC of the day represented. An individual day
	// isn't released until there is a minimum threshold for updates has been met.
	Day                time.Time       `json:"day"`
	PublishRequests    PublishRequests `json:"publish_requests"`
	TotalTEKsPublished int64           `json:"total_teks_published"`
	// RevisionRequests is the number of publish requests that contained at least one TEK revision.
	RevisionRequests int64 `json:"requests_with_revisions"`
	// TEKAgeDistribution shows a distribution of the oldest tek in an upload.
	// The count at index 0-15 represent the number of uploads there the oldest TEK is that value.
	// Index 16 represents > 15 days.
	TEKAgeDistribution []int64 `json:"tek_age_distribution"`
	// OnsetToUploadDistribution shows a distribution of onset to upload, the index is in days.
	// The count at index 0-29 represents the number of uploads with that symptom onset age.
	// Index 30 represents > 29 days.
	OnsetToUploadDistribution []int64 `json:"onset_to_upload_distribution"`

	// RequestsMissingOnsetDate is the number of publish requests where no onset date
	// was provided. These request are not included in the onset to upload distribution.
	RequestsMissingOnsetDate int64 `json:"requests_missing_onset_date"`
}

StatsDay represents stats from an individual day. All stats represent only successful requests.

type StatsRequest

type StatsRequest struct {
	Padding string `json:"padding"`
}

StatsRequest represents the request to retrieve publish metrics for a specific health authority.

Calls to this API require an "Authorization: Bearer <JWT>" header with a JWT signed with the same private used to sign verification certificates for the health authority.

New stats are released every hour. And stats for a day (UTC) only start to be released once there have been a sufficient numbers of publish requests for that day.

This API is invoked via POST request to /v1/stats

type StatsResponse

type StatsResponse struct {
	// Individual days. There may be gaps if a day does not have enough data.
	Days []*StatsDay `json:"days,omitempty"`

	ErrorMessage string `json:"error,omitempty"`
	ErrorCode    string `json:"code,omitempty"`

	Padding string `json:"padding"`
}

StatsResponse returns all currently known metrics for the authenticated health authority.

There may be gaps in the Days if a day has insufficient data.

type VerificationClaims

type VerificationClaims struct {
	jwt.StandardClaims

	// ReportType is one of 'confirmed', 'likely', or 'negative' as defined by the constants in this file.
	// Required. Claims must contain a valid report type or the publish request won't have any effect.
	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.
	// Optional. If present, TEKs will be adjusted accordingly on publish.
	SymptomOnsetInterval uint32 `json:"symptomOnsetInterval,omitempty"`

	// SignedMac is the HMAC of the TEKs that may be uploaded with the certificate containing these claims.
	// Required, indicates what can be uploaded with this certificate.
	SignedMAC string `json:"tekmac"`
}

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.

func (*VerificationClaims) CustomClaimsValid

func (v *VerificationClaims) CustomClaimsValid() error

CustomClaimsValid returns nil if the custom claims are valid. .Valid() should still be called to validate the standard claims.