Struct VapidSignatureBuilder

pub struct VapidSignatureBuilder<'a> { /* private fields */ }

A VAPID signature builder for generating an optional signature to the request. This encryption is required for payloads in all current and future browsers.

To communicate with the site, one needs to generate a private key to keep in the server and derive a public key from the generated private key for the client.

Private key generation:

openssl ecparam -name prime256v1 -genkey -noout -out private.pem

To derive a public key out of generated private key:

openssl ec -in private.pem -pubout -out vapid_public.pem

To get the byte form of the public key for the JavaScript client:

openssl ec -in private.pem -text -noout -conv_form uncompressed

… or a base64-encoded string, which the client should convert into byte form before using:

openssl ec -in private.pem -pubout -outform DER|tail -c 65|base64|tr '/+' '_-'|tr -d '\n'

The above commands can be done in code using PartialVapidSignatureBuilder::get_public_key, then base64 URL safe encoding as well.

To create a VAPID signature:

//You would get this as a `pushSubscription` object from the client. They need your public key to get that object.
let subscription_info = SubscriptionInfo {
    keys: SubscriptionKeys {
        p256dh: String::from("something"),
        auth: String::from("secret"),
    },
    endpoint: String::from("https://mozilla.rules/something"),
};

let file = File::open("private.pem").unwrap();

let mut sig_builder = VapidSignatureBuilder::from_pem(file, &subscription_info).unwrap();

//These fields are optional, and likely unneeded for most uses.
sig_builder.add_claim("sub", "mailto:test@example.com");
sig_builder.add_claim("foo", "bar");
sig_builder.add_claim("omg", 123);

let signature = sig_builder.build().unwrap();

Implementations

impl<'a> VapidSignatureBuilder<'a>

pub fn from_pem<R: Read>( pk_pem: R, subscription_info: &'a SubscriptionInfo, ) -> Result<VapidSignatureBuilder<'a>, WebPushError>

Creates a new builder from a PEM formatted private key.

Details

The input can be either a pkcs8 formatted PEM, denoted by a —–BEGIN PRIVATE KEY—— header, or a SEC1 formatted PEM, denoted by a —–BEGIN EC PRIVATE KEY—— header.

pub fn from_pem_no_sub<R: Read>( pk_pem: R, ) -> Result<PartialVapidSignatureBuilder, WebPushError>

Creates a new builder from a PEM formatted private key. This function doesn’t take a subscription, allowing the reuse of one builder for multiple messages by cloning the resulting builder.

Details

The input can be either a pkcs8 formatted PEM, denoted by a —–BEGIN PRIVATE KEY—— header, or a SEC1 formatted PEM, denoted by a —–BEGIN EC PRIVATE KEY—— header.

pub fn from_der<R: Read>( pk_der: R, subscription_info: &'a SubscriptionInfo, ) -> Result<VapidSignatureBuilder<'a>, WebPushError>

Creates a new builder from a DER formatted private key.

pub fn from_der_no_sub<R: Read>( pk_der: R, ) -> Result<PartialVapidSignatureBuilder, WebPushError>

Creates a new builder from a DER formatted private key. This function doesn’t take a subscription, allowing the reuse of one builder for multiple messages by cloning the resulting builder.

pub fn from_base64( encoded: &str, subscription_info: &'a SubscriptionInfo, ) -> Result<VapidSignatureBuilder<'a>, WebPushError>

Creates a new builder from a raw base64-encoded private key. This isn’t the base64 from a key generated by openssl, but rather the literal bytes of the private key itself. This is the kind of key given to you by most VAPID key generator sites, and also the kind used in the API of other large web push libraries, such as PHP and Node.

Base64 encoding must use URL-safe alphabet without padding.

Example

// Use `from_base64` here if you have a sub
let builder = VapidSignatureBuilder::from_base64_no_sub("IQ9Ur0ykXoHS9gzfYX0aBjy9lvdrjx_PFUXmie9YRcY").unwrap();

pub fn from_base64_no_sub( encoded: &str, ) -> Result<PartialVapidSignatureBuilder, WebPushError>

Creates a new builder from a raw base64-encoded private key. This function doesn’t take a subscription, allowing the reuse of one builder for multiple messages by cloning the resulting builder.

Base64 encoding must use URL-safe alphabet without padding.

pub fn add_claim<V>(&mut self, key: &'a str, val: V)

where V: Into<Value>,

Add a claim to the signature. Claims aud and exp are automatically added to the signature. Add them manually to override the default values.

The function accepts any value that can be converted into a type JSON supports.

pub fn build(self) -> Result<VapidSignature, WebPushError>

Builds a signature to be used in WebPushMessageBuilder.