v1

package
v1.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2023 License: Apache-2.0 Imports: 7 Imported by: 7

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

View Source 
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 revision 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..

View Source 
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"
	// ReportTypeSelfReport indicates to set ReportType.SELF_REPORT.
	ReportTypeSelfReport = "user-report"

	TransmissionRiskUnknown           = 0
	TransmissionRiskConfirmedStandard = 2
	TransmissionRiskClinical          = 4
	TransmissionRiskSelfReport        = 5
	TransmissionRiskNegative          = 6
)
View Source 
const (
	// ErrorUnauthorized is returned if the provided bearer token is invalid.
	ErrorUnauthorized = "unauthorized"
)

Variables

View Source 
var ValidReportTypes = map[string]bool{
	ReportTypeConfirmed:  true,
	ReportTypeClinical:   true,
	ReportTypeNegative:   true,
	ReportTypeSelfReport: true,
}

Functions

This section is empty.

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"` // 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.

type ExposureKeys 

type ExposureKeys struct {
	// Keys (temporaryExposureKeys) is required and must have at least one TEK.
	Keys []ExposureKey `json:"temporaryExposureKeys"`
}

ExposureKeys represents a set of ExposureKey objects as input to export file generation utility.

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"`

	// HealthAuthorityID (healthAuthorityID) is the unique identifier assigned by
	// the server operator.
	HealthAuthorityID string `json:"healthAuthorityID"`

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

	// 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,omitempty"`

	// 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,omitempty"`

	// Traveler (traveler) indicates 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).
	Traveler bool `json:"traveler,omitempty"`

	// 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"`
}

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

Note on 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 added in v0.19.0 

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

PublishRequests is a summary of one day's publish requests by platform.

func (*PublishRequests) Total added in v0.19.0 

func (p *PublishRequests) Total() int64

Total returns the number of publish requests across all platforms.

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 added in v0.19.0 

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.

func (*StatsDay) IsEmpty added in v0.35.0 

func (s *StatsDay) IsEmpty() bool

func (*StatsDay) OnsetToUploadDistributionAsString added in v0.23.0 

func (s *StatsDay) OnsetToUploadDistributionAsString() []string

OnsetToUploadDistributionAsString returns an array of OnsetToUploadDistribution as strings instead of int64.

func (*StatsDay) TEKAgeDistributionAsString added in v0.23.0 

func (s *StatsDay) TEKAgeDistributionAsString() []string

TEKAgeDistributionAsString returns an array of TEKAgeDistribution as strings instead of int64.

type StatsDays added in v0.21.0 

type StatsDays []*StatsDay

StatsDays represents a logical collection of stats.

func (StatsDays) MarshalCSV added in v0.21.0 

func (s StatsDays) MarshalCSV() ([]byte, error)

MarshalCSV returns bytes in CSV format.

type StatsRequest added in v0.19.0 

type StatsRequest struct {
	// 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"`
}

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 added in v0.19.0 

type StatsResponse struct {
	// Individual days. There may be gaps if a day does not have enough data.
	Days StatsDays `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.

func NewVerificationClaims 

func NewVerificationClaims() *VerificationClaims

NewVerificationClaims initializes a new VerificationClaims struct.

func (*VerificationClaims) CustomClaimsValid added in v0.3.0 

func (v *VerificationClaims) CustomClaimsValid() error

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.