Intended use of keys

[christophhagen]

Hi there,

I'm trying to use this library to send notifications, and I'm unsure how the VAPID keys are supposed to be used.

From the Readme, I get the following understanding:

• Generate a VAPID key with the generator
• Load the configuration with the key in WebPushManager
• Provide a VAPID public key (VAPID.Key.ID) to the device
• The device registers a subscription containing the id
• When sending the notification, provide the Subscription to WebPushManager

However, this process fails with the following error when sending a notification:

ConfigurationError(kind: WebPush.VAPID.ConfigurationError.Kind.matchingKeyNotFound)

The log shows:

[WebPush] A key was not found for this subscriber.

If I look at the relevant code, this isn't surprising:

guard let signingKey = vapidKeyLookup[subscriber.vapidKeyID] else {
    logger.warning("A key was not found for this subscriber.")
    throw VAPID.ConfigurationError.matchingKeyNotFound
}

I'm only providing a primaryKey on init, like the Readme suggests.
Therefore, my vapidKeyLookup dict is empty, and the key is not found.

The readme suggests to use nextVAPIDKeyID for key ids sent to devices for subscription, which will return primaryKey if it exists.

So my questions are:

• What is the purpose of primaryKey? It is only used for nextVAPIDKeyID
• Should the code here also check the primaryKey and use this one?
• Or should I generate additional keys for use?
• If so, how should keys be generated/derived? From the primary key?
• Should I create a new WebPushManager when I want to add a key? It has immutable state.

Thank you for your help

[dimitribouniol]

So at first glance, this sounds like you may have either registered a Subscriber under a different key configuration with a different key, or you are using your own type that conforms to SubscriberProtocol and passed in a different key ID. This is an issue because the signatures attached to that subscriber are only valid for the key that was used at registration, so it would fail even if you bypassed this initial check.

I would make sure that:

• The VAPID key (and configuration, if you can) is generated exactly once and persisted for all server instances across reboots.
• Clearing out old subscribers you used during development whose keys don't match up. (You can do this by catching the ConfigurationError(kind: .matchingKeyNotFound) error and removing that subscriber)

To answer some of your more specific questions:

What is the purpose of primaryKey? It is only used for nextVAPIDKeyID

primaryKey is a compile-time-verified shortcut for specifying that only a single key should be used for all subscribers, which makes it the recommended way of configuring your manager. nextVAPIDKeyID is used to cycle between multiple keys if your configuration has multiple keys to cycle through (which is an advanced use case that has very limited benefits for increased complexity)

Should the code here also check the primaryKey and use this one?

I'm assuming "the code" refers to guard let signingKey = vapidKeyLookup[subscriber.vapidKeyID] else { ... }, but it really shouldn't, as we would end up flagging your server for sending notifications to subscribers that aren't registered to your VAPID key you are currently using. This occurs if you cycle out your VAPID keys, which unfortunately leaves old subscribers behind. You can apparently re-register subscribers with the new VAPID key and nothing else, but I haven't tried this process personally.

Or should I generate additional keys for use?

Again, I wouldn't recommend it as it comes with increased complexity. You might want to do this with deprecatedKeys if you preemptively cycle out a key for new subscribers, but don't want to lose old subscribers. Doing this semi-regularly (one every few months?) would minimize the damage of losing all your subscribers if a single key gets leaked, but again, minimal gain if all keys are defined in one place and would leak together…

If so, how should keys be generated/derived? From the primary key?

Ideally once using the generator on your system, and then shared with your server running in the cloud using secrets or other environment variables. You can also be creative here (I save mine in Application Support as I deploy to a Mac mini). If you save the entire configuration, you can use this one liner to get everything set up:

    let configurationData = // load from env
    let vapidConfiguration = try JSONDecoder().decode(VAPID.Configuration.self, from: configurationData)

You can generate keys in process if you have shared persistent storage, if you wanted to. This should be done prior to instantiating the manager though.

Should I create a new WebPushManager when I want to add a key? It has immutable state.

The keys should not be changing at runtime, as mentioned, so you should create a single WebPushManager after loading the configuration from env or disk, and just keep using it. If you absolutely need to generate keys at runtime (perhaps this is a managed service for others?), then I'd love to hear more about the use case so we can consider how to make this state mutable vs manage mutiple WebPushManagers.

[christophhagen]

Thank you, it was indeed an issue with the keys, but not quite in the way you described.
All keys were used correctly, but the client sent the key ids in base64, while the IDs in Swift are base64url encoded.
The subtle differences (e.g. - instead of _) meant that the key was not found.
It works now using a single primary key.

Might be worth a note somewhere, maybe others run into the same problems (I didn't even know that there were different base64 formats until now).
Otherwise my intuition would be to make the ID use the Data type, if it's always a base64 encoded string.

Thank you very much for your quick help, I was able to implement basic push notifications with very little effort!

[dimitribouniol]

That's an excellent catch, I've just filed #65 to make sure it's fool proof. Generally, the browser expects Base64 URL-Encoded tokens for this, which the library provides:

swift-webpush/Sources/WebPush/VAPID/VAPIDKey.swift

Line 107 in 456cd19

ID(privateKey.publicKey.x963Representation.base64URLEncodedString())

… so I'm curious how it ended up simply Base64 encoded on the way back. Can you share any JS-client-side code here? I must admit my own project uses SubscriberProtocol instead, since I was using WebPush since before I made it into a library, so I very likely missed something crucial in the examples 😅