Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions gateway/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,12 @@ the real server's wake round; not yet against Apple or Google.
with `Retry-After`. Budgets are fixed hourly windows, so a server can
briefly send up to twice its budget across a window boundary. A wallet
with two servers gets two budgets; Apple may then throttle some wakes,
which wallets must tolerate anyway (spec §5.4).
which wallets must tolerate anyway (spec §5.4). The wallet API is also
limited per client address (an IPv4 address or an IPv6 /64): 60
subscriptions and 60 revocations an hour by default. The counters hold
salted hashes of addresses, in memory only, and are never logged.
Behind a proxy, list it in `trusted_proxies` so its `X-Forwarded-For`
names the client; from anyone else that header is ignored.
- **Blind.** Only `aes128gcm` bodies are accepted, and they are forwarded
unchanged, base64url in the `lz` field. Payment alerts show a fixed,
generic title (`alert_title`); the app's Notification Service Extension
Expand All @@ -52,7 +57,7 @@ gateway. The reference one takes:

```
POST /v0/subscriptions
{ "platform": "apns" | "fcm",
{ "platform": "apns" | "apns-sandbox" | "fcm",
"token": "<APNs device token, hex | FCM registration token>",
"server_key": "<vapid_public_key from the server's info, base64url>" }
→ 201 { "endpoint": "https://<public_origin>/wp/<opaque>",
Expand All @@ -66,6 +71,17 @@ Authorization: Bearer <revoke_secret>
503 revocation list full, try later
```

Both answer `429` with `Retry-After` past the per-address limits.

`apns-sandbox` is for development builds (Xcode), whose device tokens
work only in Apple's development environment. The gateway accepts it
when `[apns] allow_sandbox = true`, and sends those pushes there with the
same auth key; `apns` goes to the environment `sandbox` picks
(production by default). So one gateway serves development, TestFlight
and App Store builds. The app knows which it is from its
`aps-environment` entitlement. Turning `allow_sandbox` off later makes
existing `apns-sandbox` endpoints answer `410`.

The wallet registers the endpoint with the server (`POST /v0/devices`) and
keeps `revoke_secret` on the device; the server never sees it. A wallet
connected to two servers subscribes twice. Before `expires`, the wallet
Expand Down Expand Up @@ -145,8 +161,10 @@ revocations.

- **Abuse of the open wallet API.** Anyone can subscribe and then revoke,
so the revocation list could be filled; past 1,000,000 entries,
revocations get `503` until old ones expire. Put a per-address rate limit
in front of the gateway. App attestation would close this properly.
revocations get `503` until old ones expire. The per-address limits
make that slow (at 60 an hour, about 17,000 address-hours), not
impossible for someone with many addresses. App attestation (App
Attest, Play Integrity) would close it properly.
- **Several gateway instances.** Rate limits live in memory per instance,
and the revocation list is a local file. Run one instance, or share the
list.
Expand Down
11 changes: 11 additions & 0 deletions gateway/examples/config.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Example gateway configuration. TLS is terminated in front of the gateway.
listen = "127.0.0.1:8090"
# Proxies whose X-Forwarded-For names the client, for the per-address
# limits. Only these; from anyone else the header is ignored.
trusted_proxies = []
# Endpoints are built on this origin, and servers' VAPID tokens must name it.
public_origin = "https://push.example-wallet.app"
# Holds the endpoint-sealing keys and the revocation list. Losing it
Expand All @@ -17,7 +20,12 @@ key_id = "KEY1234567"
key_path = "/etc/lz-gateway/AuthKey_KEY1234567.p8"
# The wallet app's bundle id.
topic = "app.example.wallet"
# Where "apns" subscriptions go: false for production (TestFlight, App
# Store builds).
sandbox = false
# Also accept "apns-sandbox" subscriptions from development (Xcode) builds,
# sent to Apple's development environment with the same key.
allow_sandbox = false

[fcm]
project_id = "example-wallet"
Expand All @@ -29,3 +37,6 @@ credentials_path = "/etc/lz-gateway/fcm-service-account.json"
background_per_hour = 3
alerts_per_hour = 20
per_server_per_minute = 100000
# The open wallet API, per client address (IPv4 address or IPv6 /64).
subscriptions_per_address_per_hour = 60
revocations_per_address_per_hour = 60
48 changes: 46 additions & 2 deletions gateway/src/config.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! Gateway configuration, read from a TOML file.

use std::net::SocketAddr;
use std::net::{IpAddr, SocketAddr};
use std::path::PathBuf;

use serde::Deserialize;
Expand All @@ -10,6 +10,11 @@ use serde::Deserialize;
pub struct Config {
/// Address to listen on. TLS is terminated in front of the gateway.
pub listen: SocketAddr,
/// Proxies in front of the gateway whose `X-Forwarded-For` names the
/// client. Used for the per-address limits on the wallet API only, and
/// never logged.
#[serde(default)]
pub trusted_proxies: Vec<IpAddr>,
/// This gateway's public origin, for example `https://push.example.app`.
/// Endpoints are built on it, and VAPID tokens must name it as `aud`.
pub public_origin: String,
Expand Down Expand Up @@ -49,12 +54,21 @@ pub struct ApnsConfig {
pub key_path: PathBuf,
/// The app's bundle id (`apns-topic`).
pub topic: String,
/// Use the development APNs environment.
/// Send `apns` subscriptions to the development APNs environment.
#[serde(default)]
pub sandbox: bool,
/// Also accept `apns-sandbox` subscriptions, from development builds
/// (Xcode), and send them to the development environment, so one
/// gateway serves both kinds of build. The same auth key works in
/// both. Leave it off for a gateway that only release builds use.
#[serde(default)]
pub allow_sandbox: bool,
/// Overrides the APNs host, for tests.
#[serde(default)]
pub base_url: Option<String>,
/// Overrides the development APNs host for `apns-sandbox`, for tests.
#[serde(default)]
pub sandbox_base_url: Option<String>,
}

impl ApnsConfig {
Expand All @@ -65,6 +79,14 @@ impl ApnsConfig {
(None, false) => "https://api.push.apple.com".into(),
}
}

/// Where `apns-sandbox` subscriptions go, when allowed.
pub fn sandbox_url(&self) -> Option<String> {
self.allow_sandbox.then(|| match &self.sandbox_base_url {
Some(u) => u.trim_end_matches('/').to_owned(),
None => "https://api.sandbox.push.apple.com".into(),
})
}
}

#[derive(Debug, Clone, Deserialize)]
Expand Down Expand Up @@ -100,6 +122,16 @@ pub struct LimitsConfig {
/// All pushes signed by one server key, per minute.
#[serde(default = "default_per_server")]
pub per_server_per_minute: u32,
/// Subscriptions created per client address (an IPv4 address or an
/// IPv6 /64) per hour. A wallet subscribes once per server and renews
/// every few months, but carrier NAT puts many phones on one IPv4
/// address.
#[serde(default = "default_per_address")]
pub subscriptions_per_address_per_hour: u32,
/// Revocations per client address per hour. They fill the revocation
/// list, which holds at most 1,000,000.
#[serde(default = "default_per_address")]
pub revocations_per_address_per_hour: u32,
}

fn default_background() -> u32 {
Expand All @@ -111,13 +143,18 @@ fn default_alert() -> u32 {
fn default_per_server() -> u32 {
100_000
}
fn default_per_address() -> u32 {
60
}

impl Default for LimitsConfig {
fn default() -> Self {
Self {
background_per_hour: default_background(),
alerts_per_hour: default_alert(),
per_server_per_minute: default_per_server(),
subscriptions_per_address_per_hour: default_per_address(),
revocations_per_address_per_hour: default_per_address(),
}
}
}
Expand All @@ -134,6 +171,8 @@ pub enum ConfigError {
NoPlatform,
#[error("endpoint_lifetime_days must be 1 to 365")]
Lifetime,
#[error("[limits] per-address limits must be at least 1")]
Limits,
}

impl Config {
Expand Down Expand Up @@ -163,6 +202,11 @@ impl Config {
if !(1..=crate::keys::MAX_LIFETIME_DAYS).contains(&self.endpoint_lifetime_days) {
return Err(ConfigError::Lifetime);
}
if self.limits.subscriptions_per_address_per_hour == 0
|| self.limits.revocations_per_address_per_hour == 0
{
return Err(ConfigError::Limits);
}
Ok(())
}
}
76 changes: 68 additions & 8 deletions gateway/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@
//! - **Bound.** Each subscription accepts pushes signed by one server key
//! ([`vapid`]); there is no admission list.
//! - **Rate-limited** per device, with background and alert budgets apart,
//! and per server key ([`limits`]).
//! and per server key; the wallet API per client address ([`limits`]).
//! - **Blind.** Payloads are forwarded as received: encrypted to the
//! device. Nothing logs device tokens, endpoints, or payloads.
//!
//! Wallet API (vendor-internal, not part of the Lantern Zero spec):
//! - `POST /v0/subscriptions` with
//! `{"platform": "apns" | "fcm", "token": "...", "server_key": "<base64url>"}`
//! `{"platform": "apns" | "apns-sandbox" | "fcm", "token": "...", "server_key": "<base64url>"}`
//! returns `201 {"endpoint": "https://<origin>/wp/<opaque>",
//! "expires": <unix seconds>, "revoke_secret": "<base64url>"}`.
//! - `DELETE /v0/subscriptions/<opaque>` with
Expand All @@ -31,12 +31,14 @@ pub mod revoke;
pub mod seal;
pub mod vapid;

use std::net::{IpAddr, SocketAddr};
use std::sync::Arc;
use std::time::{SystemTime, UNIX_EPOCH};

use axum::Router;
use axum::body::Bytes;
use axum::extract::{DefaultBodyLimit, Path as UrlPath, State};
use axum::extract::connect_info::IntoMakeServiceWithConnectInfo;
use axum::extract::{ConnectInfo, DefaultBodyLimit, Path as UrlPath, State};
use axum::http::{HeaderMap, StatusCode, header};
use axum::response::{IntoResponse, Response};
use axum::routing::{delete, post};
Expand All @@ -48,7 +50,7 @@ use subtle::ConstantTimeEq as _;
use zeroize::Zeroizing;

use crate::keys::KeyRing;
use crate::limits::{Limits, Window};
use crate::limits::{ClientKey, Limits, Window};
use crate::platform::{Apns, Delivery, Fcm, Kind, Push};
use crate::revoke::{RevokeError, Revoked};
use crate::seal::{MAX_TOKEN_LEN, Platform, Sealer, Subscription};
Expand All @@ -66,6 +68,7 @@ pub struct AppState {
pub sealer: Sealer,
pub revoked: Arc<Revoked>,
pub limits: Limits,
pub client_key: ClientKey,
pub apns: Option<Apns>,
pub fcm: Option<Fcm>,
}
Expand Down Expand Up @@ -111,16 +114,49 @@ impl AppState {
background: Window::new(l.background_per_hour, 3600),
alert: Window::new(l.alerts_per_hour, 3600),
per_server: Window::new(l.per_server_per_minute, 60),
subscribe: Window::new(l.subscriptions_per_address_per_hour, 3600),
revoke: Window::new(l.revocations_per_address_per_hour, 3600),
};
Ok(Arc::new(Self {
sealer: Sealer::new(&ring),
revoked,
limits,
client_key: ClientKey::default(),
apns,
fcm,
config,
}))
}

/// The client's address, for the per-address limits only: the peer,
/// or the last `X-Forwarded-For` entry when the peer is a trusted
/// proxy (as the relay does).
fn client_ip(&self, peer: IpAddr, headers: &HeaderMap) -> IpAddr {
if !self.config.trusted_proxies.contains(&peer) {
return peer;
}
headers
.get_all("x-forwarded-for")
.iter()
.filter_map(|v| v.to_str().ok())
.flat_map(|v| v.split(','))
.next_back()
.and_then(|v| v.trim().parse().ok())
.unwrap_or(peer)
}

/// Counts a wallet API call against its client's hourly budget.
fn limit_client(&self, w: &Window, peer: SocketAddr, headers: &HeaderMap) -> Option<Response> {
let key = self.client_key.of(self.client_ip(peer.ip(), headers));
w.hit(key, now_unix()).err().map(|retry| {
(
StatusCode::TOO_MANY_REQUESTS,
[(header::RETRY_AFTER, retry.to_string())],
"rate limited",
)
.into_response()
})
}
}

pub fn router(state: Arc<AppState>) -> Router {
Expand All @@ -132,6 +168,12 @@ pub fn router(state: Arc<AppState>) -> Router {
.with_state(state)
}

/// [`router`] as a service that knows each peer's address, which the
/// per-address limits need. Serve this, not the bare router.
pub fn app(state: Arc<AppState>) -> IntoMakeServiceWithConnectInfo<Router, SocketAddr> {
router(state).into_make_service_with_connect_info::<SocketAddr>()
}

/// Lowercase hex.
pub(crate) fn hex(bytes: &[u8]) -> String {
bytes.iter().map(|b| format!("{b:02x}")).collect()
Expand Down Expand Up @@ -159,19 +201,32 @@ struct SubscribeRequest {
}

/// Creates a subscription bound to `server_key` (spec §4.1).
async fn subscribe(State(state): State<Arc<AppState>>, body: Bytes) -> Response {
async fn subscribe(
State(state): State<Arc<AppState>>,
ConnectInfo(peer): ConnectInfo<SocketAddr>,
headers: HeaderMap,
body: Bytes,
) -> Response {
if let Some(r) = state.limit_client(&state.limits.subscribe, peer, &headers) {
return r;
}
let Ok(req) = serde_json::from_slice::<SubscribeRequest>(&body) else {
return error(StatusCode::BAD_REQUEST, "malformed request");
};
let platform = match req.platform.as_str() {
"apns" if state.apns.is_some() => Platform::Apns,
"apns-sandbox" if state.apns.as_ref().is_some_and(Apns::allows_sandbox) => {
Platform::ApnsSandbox
}
"fcm" if state.fcm.is_some() => Platform::Fcm,
"apns" | "fcm" => return error(StatusCode::BAD_REQUEST, "platform not configured"),
"apns" | "apns-sandbox" | "fcm" => {
return error(StatusCode::BAD_REQUEST, "platform not configured");
}
_ => return error(StatusCode::BAD_REQUEST, "unknown platform"),
};
let token = match platform {
// APNs device tokens are hex.
Platform::Apns => {
Platform::Apns | Platform::ApnsSandbox => {
let t = req.token.trim();
if t.len() % 2 != 0 || t.len() < 32 || t.len() > 2 * MAX_TOKEN_LEN {
return error(StatusCode::BAD_REQUEST, "invalid token");
Expand Down Expand Up @@ -228,9 +283,13 @@ async fn subscribe(State(state): State<Arc<AppState>>, body: Bytes) -> Response
/// Revokes a subscription (spec §4.1): later pushes to it get `410`.
async fn revoke(
State(state): State<Arc<AppState>>,
ConnectInfo(peer): ConnectInfo<SocketAddr>,
UrlPath(opaque): UrlPath<String>,
headers: HeaderMap,
) -> Response {
if let Some(r) = state.limit_client(&state.limits.revoke, peer, &headers) {
return r;
}
let now = now_unix();
let Some(sub) = state.sealer.open(&opaque) else {
return error(StatusCode::NOT_FOUND, "no such subscription");
Expand Down Expand Up @@ -375,7 +434,8 @@ async fn push(
topic,
};
let delivery = match (sub.platform, &state.apns, &state.fcm) {
(Platform::Apns, Some(apns), _) => apns.send(&sub.token, &p, now).await,
(Platform::Apns, Some(apns), _) => apns.send(&sub.token, &p, now, false).await,
(Platform::ApnsSandbox, Some(apns), _) => apns.send(&sub.token, &p, now, true).await,
(Platform::Fcm, _, Some(fcm)) => fcm.send(&sub.token, &p).await,
// The platform was configured when this endpoint was made, but
// isn't any more: the endpoint can never work again.
Expand Down
Loading
Loading