Pass formats & distribution

Manifest and signature

The two files in every PKPass that prove it is genuine; manifest.json lists a hash of every other file and signature is a detached signature over the manifest, made with the pass type ID certificate.

A PKPass is a zip archive, and two files in it exist only to prove the rest has not been touched. manifest.json is a list of every other file in the bundle, pass.json, the images, the localization files, each paired with a hash of its contents. The signature file is a detached cryptographic signature over the manifest, made with the private key of the program's pass type ID certificate and including the certificate chain up to Apple's WWDR certificate.

Verification runs the chain backwards. When a pass is added, the wallet checks that the signature is valid and was made by a certificate Apple issued for the pass type identifier the pass claims, then checks that every file's hash matches the manifest. Change a single byte of pass.json, add an image, or sign with a certificate for a different identifier, and the pass is refused. That is what lets Apple Wallet accept passes from any issuer without a central registry: the certificate is the proof of ownership.

It is also why every update is a reissue. Since the whole bundle is sealed, a changed points balance means a new manifest and a new signature, which the wallet fetches through the pass web service. Signing is fast and platforms do it thousands of times a day, but it explains why the signing certificate and key must be available to the platform, usually delivered as a PKCS #12 file.

Most "pass will not add" reports trace back here: an expired signing certificate, the wrong WWDR generation in the chain, a file edited after the manifest was written. Google Wallet has no equivalent pair of files because a Google pass is not a file; its authenticity rests on the API call that created it and the signed save link that delivers it.

See the platform
Next step

See what this looks like on a pass.

The definition is the short version. The next pages show it on the terminals merchants already run, and the merchants running it.