webpush

Documentation

Overview

Package webpush provides helper functions for sending encrpyted payloads using the Web Push protocol.

Sending a message:

import (
  "github.com/googlechrome/push-encryption-go/webpush"
)

func main() {
  // The values that make up the Subscription struct come from the browser
  sub := &webpush.Subscription{endpoint, key, auth}
  webpush.Send(nil, sub, "Yay! Web Push!", "")
}

You can turn a JSON string representation of a PushSubscription object you collected from the browser into a Subscription struct with a helper function.

var exampleJSON = []byte(`{"endpoint": "...", "keys": {"p256dh": "...", "auth": "..."}}`)
sub, err := SubscriptionFromJSON(exampleJSON)

If the push service requires an authentication header (notably Google Cloud Messaging, used by Chrome) then you can add that as a fourth parameter:

if strings.Contains(sub.Endpoint, "https://android.googleapis.com/gcm/send/") {
  webpush.Send(nil, sub, "A message for Chrome", myGCMKey)
}

Index

• func NewPushRequest(sub *Subscription, message string, token string) (*http.Request, error)
• func Send(client *http.Client, sub *Subscription, message, token string) (*http.Response, error)
• type ContentEncoding
  • func (v ContentEncoding) String() string
• type EncryptionResult
  • func Encrypt(sub *Subscription, message string, encoding ContentEncoding) (*EncryptionResult, error)
• type Subscription
  • func SubscriptionFromJSON(b []byte) (*Subscription, error)

Functions

func NewPushRequest

func NewPushRequest(sub *Subscription, message string, token string) (*http.Request, error)

NewPushRequest creates a valid Web Push HTTP request for sending a message to a subscriber. If the push service requires an authentication header (notably Google Cloud Messaging, used by Chrome) then you can add that as the token parameter.

func Send

func Send(client *http.Client, sub *Subscription, message, token string) (*http.Response, error)

Send a message using the Web Push protocol to the recipient identified by the given subscription object. If the client is nil then the default HTTP client will be used. If the push service requires an authentication header (notably Google Cloud Messaging, used by Chrome) then you can add that as the token parameter.

Types

type ContentEncoding

type ContentEncoding int

ContentEncoding indicates the version of encoding.

const (
	// The encoding that is widely deployed with WebPush (as of 2016-11).
	AESGCM ContentEncoding = iota
	// The most recent encoding, the salt, record size and key identifier
	// are included in a header that is part of the encrypted content coding.
	AES128GCM
)

func (ContentEncoding) String

func (v ContentEncoding) String() string

type EncryptionResult

type EncryptionResult struct {
	Ciphertext      []byte
	Salt            []byte
	ServerPublicKey []byte
}

EncryptionResult stores the result of encrypting a message. The ciphertext is the actual encrypted message, while the salt and server public key are required to be sent to the client so that the message can be decrypted.

func Encrypt

func Encrypt(sub *Subscription, message string, encoding ContentEncoding) (*EncryptionResult, error)

Encrypt a message such that it can be sent using the Web Push protocol. You can find out more about the various pieces:

• https://tools.ietf.org/html/draft-ietf-httpbis-encryption-encoding
• https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman
• https://tools.ietf.org/html/draft-ietf-webpush-encryption

type Subscription

type Subscription struct {
	// Endpoint is the URL to send the Web Push message to. Comes from the
	// endpoint field of the PushSubscription.
	Endpoint string
	// Key is the client's public key. From the keys.p256dh field.
	Key []byte
	// Auth is a value used by the client to validate the encryption. From the
	// keys.auth field.
	Auth []byte
}

Subscription holds the useful values from a PushSubscription object acquired from the browser

func SubscriptionFromJSON

func SubscriptionFromJSON(b []byte) (*Subscription, error)

SubscriptionFromJSON is a convenience function that takes a JSON encoded PushSubscription object acquired from the browser and returns a pointer to a Subscription