Documentation
¶
Overview ¶
Package webpush speaks the Web Push protocol with the standard library only (design expansion phase 8, X22):
- RFC 8030, the generic event delivery: a POST to the subscription's push resource with TTL, Urgency and Topic, answered 201 Created;
- RFC 8292, VAPID: an ES256 JWT that identifies the workspace to the push services, carried in "Authorization: vapid t=…, k=…";
- RFC 8291 with RFC 8188's aes128gcm content coding: the payload is encrypted for the browser with a fresh ECDH key and a random salt.
It knows nothing about workspaces, sites or campaigns (internal/push does that). The encryption is checked against RFC 8291's Appendix A and RFC 8188's example; webpushtest is an in-process push service that verifies the JWT and decrypts what it receives, for tests and the demo.
Index ¶
- Constants
- Variables
- func Decode(s string) ([]byte, error)
- func Decrypt(ua *ecdh.PrivateKey, authSecret, body []byte) ([]byte, error)
- func Encode(b []byte) string
- func Encrypt(sub Subscription, plaintext []byte) ([]byte, error)
- func Origin(endpoint string) (string, error)
- func ParseAuthorization(h string) (token string, key []byte, err error)
- func TopicFor(tag string) string
- type Claims
- type Message
- type Outcome
- type Result
- type Sender
- type Subscription
- type Urgency
- type VAPIDKey
Constants ¶
const ( // RecordSize is the record size written in the header. Push services // accept 4096-byte bodies (RFC 8030 §7.2), so one record carries the // whole message. RecordSize = 4096 // MaxPayload is the most plaintext one message carries. MaxPayload = RecordSize - headerLen - tagLen - 1 )
const MaxTTL = 28 * 24 * time.Hour
MaxTTL is the longest time push services keep a message (FCM's limit, the shortest of the major services).
const MaxTokenLifetime = 24 * time.Hour
MaxTokenLifetime is RFC 8292's limit on "exp": at most 24 hours from the time of the request.
const TokenLifetime = 12 * time.Hour
TokenLifetime is what ReputeCast signs for. Tokens are reused for an hour per push service, so a token is always well inside the limit.
Variables ¶
var ( ErrTooLarge = fmt.Errorf("webpush: the payload is over %d bytes", MaxPayload) ErrBody = errors.New("webpush: the body isn't aes128gcm content") )
Errors from encrypting and decrypting.
var ( ErrAuthorization = errors.New("webpush: not a vapid authorization") ErrSignature = errors.New("webpush: the token's signature doesn't verify") ErrClaims = errors.New("webpush: the token's claims are invalid") )
Errors from verifying a token.
var ( ErrEndpoint = errors.New("webpush: the endpoint isn't an https URL") ErrKeys = errors.New("webpush: the subscription's keys are malformed") )
Errors from ParseSubscription.
Functions ¶
func Decrypt ¶
func Decrypt(ua *ecdh.PrivateKey, authSecret, body []byte) ([]byte, error)
Decrypt reads a Web Push message as the browser does, with the subscription's private key and authentication secret. The in-process push service uses it to check what it receives.
func Encrypt ¶
func Encrypt(sub Subscription, plaintext []byte) ([]byte, error)
Encrypt encrypts plaintext for a subscription with a fresh key pair and salt. The result is the request body, sent with Content-Encoding: aes128gcm.
func Origin ¶
Origin is the push service's origin, the JWT's audience: the scheme and host of the endpoint ("https://fcm.googleapis.com").
func ParseAuthorization ¶
ParseAuthorization splits "vapid t=…, k=…" into the token and the key.
Types ¶
type Claims ¶
type Claims struct {
Aud string `json:"aud"`
Exp int64 `json:"exp"`
Sub string `json:"sub,omitempty"`
}
Claims are a VAPID token's claims: the push service's origin, the expiry and the contact address ("mailto:support@acme.io").
type Message ¶
type Message struct {
// Payload is the plaintext; Send encrypts it.
Payload []byte
// TTL is how long the push service keeps the message while the
// browser is offline. After that it's dropped.
TTL time.Duration
// Urgency is normal when empty.
Urgency Urgency
// Topic replaces an undelivered message with the same topic (see
// TopicFor).
Topic string
}
Message is one push message to one subscription.
type Outcome ¶
type Outcome string
Outcome is what a push service did with a message.
const ( // Accepted: 201 Created, the push service will deliver it. Accepted Outcome = "accepted" // Gone: 404 or 410, the subscription ended (the browser unsubscribed // or the push service expired it). Remove it. Gone Outcome = "gone" // TooLarge: 413, the payload is over the push service's limit. TooLarge Outcome = "too_large" // RateLimited: 429, retry after RetryAfter. RateLimited Outcome = "rate_limited" // Rejected: 400, 401 or 403. The request or the key was refused; a // 403 usually means the subscription was made with other keys. Rejected Outcome = "rejected" Unavailable Outcome = "unavailable" )
Outcomes.
type Result ¶
type Result struct {
Outcome Outcome
// Status is the HTTP status, 0 when nothing answered.
Status int
// RetryAfter is the push service's Retry-After, for 429 and 503.
RetryAfter time.Duration
// Location is the message resource of an accepted message.
Location string
// Detail is the start of the push service's explanation, for the
// Events tab ("410 Gone · push subscription has unsubscribed or
// expired").
Detail string
}
Result is a push service's answer.
type Sender ¶
type Sender struct {
Key *VAPIDKey
// Contact is the "sub" claim: "mailto:support@acme.io".
Contact string
// HTTP is the client push services are called with (the SSRF-guarded
// client in production, the in-process push service in tests and the
// demo).
HTTP *http.Client
Now func() time.Time
// contains filtered or unexported fields
}
Sender sends messages signed with one workspace's VAPID key.
func (*Sender) Request ¶
Request builds the push request for a message: encrypted, signed, with its TTL, urgency and topic.
type Subscription ¶
type Subscription struct {
// Endpoint is the push resource URL (https://fcm.googleapis.com/…).
Endpoint string
// P256dh is the browser's ECDH public key, 65 bytes uncompressed.
P256dh []byte
// Auth is the 16-byte authentication secret.
Auth []byte
}
Subscription is what a browser's PushManager.subscribe() returns: the push resource and the keys the payload is encrypted for.
func ParseSubscription ¶
func ParseSubscription(endpoint, p256dh, auth string) (Subscription, error)
ParseSubscription checks a subscription as a browser sent it: an https endpoint, a P-256 public key and a 16-byte secret.
type Urgency ¶
type Urgency string
Urgency is a message's urgency (RFC 8030 §5.3): push services and browsers deliver low-urgency messages when it suits the battery.
type VAPIDKey ¶
type VAPIDKey struct {
// contains filtered or unexported fields
}
VAPIDKey is the key pair that identifies a workspace to the browsers' push services (RFC 8292): an ECDSA P-256 key. The public key is the applicationServerKey the browser subscribes with; the private key never leaves the server (internal/push seals it at rest).
func GenerateVAPIDKey ¶
GenerateVAPIDKey makes a new key pair.
func ParseVAPIDKey ¶
ParseVAPIDKey reads a private key stored as its 32-byte scalar.
func (*VAPIDKey) Authorization ¶
Authorization is the header value of a push request: "vapid t=<JWT>, k=<public key>".
func (*VAPIDKey) PrivateBytes ¶
PrivateBytes is the private scalar, 32 bytes, for sealing at rest.
func (*VAPIDKey) PublicKeyString ¶
PublicKeyString is the public key in base64url, as browsers take it for applicationServerKey and as the "k" parameter carries it.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package webpushtest is an in-process push service for tests and the demo: it answers the requests FCM, Mozilla's autopush, Apple and Windows would get, checks the VAPID token as they do, decrypts the payload when it made the subscription, and records every message.
|
Package webpushtest is an in-process push service for tests and the demo: it answers the requests FCM, Mozilla's autopush, Apple and Windows would get, checks the VAPID token as they do, decrypts the payload when it made the subscription, and records every message. |