PKPASS-Datei

1. Was ist eine .pkpass-Datei?

Eine .pkpass-Datei ist ein digital signiertes Paket, das einen einzelnen Pass an Apple Wallet ausliefert — die App auf iPhone, iPad, Apple Watch und Mac, in der Nutzer Bordkarten, Eventtickets, Coupons, Kundenkarten, Hotelkarten, Fahrkarten und ähnliche Berechtigungen aufbewahren. Apple stellte das Format am 11. Juni 2012 auf der WWDC unter dem Namen Passbook vor und veröffentlichte es drei Monate später in iOS 6 am 19. September 2012. Mit iOS 9 im September 2015 wurde es in Apple Wallet umbenannt — ein Jahr nachdem Apple Pay mit iOS 8.1 gestartet war — und vereinte damit Pässe und Zahlungskarten unter einer gemeinsamen Wallet-Marke. Das zugrunde liegende Dateiformat und das Entwickler-Framework — PassKit — sind die ganze Zeit kompatibel geblieben.

Mechanisch gesehen ist eine .pkpass ein ZIP-Archiv, das mit der Erweiterung .pkpass umbenannt wurde. Darin befinden sich eine JSON-Datei namens pass.json, die den Pass beschreibt, ein paar PNG-Bilder, eine manifest.json mit SHA-1-Hashes jeder anderen Datei und eine signature-Datei, die belegt, dass der Pass von einem registrierten Apple-Developer-Team stammt. Der MIME-Typ ist application/vnd.apple.pkpass — Apple Mail, Safari und die meisten modernen E-Mail-Apps stützen sich darauf, um beim Antippen eines Anhangs die Vorschau „Zu Apple Wallet hinzufügen" auszulösen.

Das Format ist in seiner Struktur offen und im Vertrauen geschlossen: Die Daten sind JSON und PNGs, die in Apples Wallet Developer Guide dokumentiert sind, aber eine PKCS#7-Signatur bindet jeden Pass an ein Pass-Type-ID-Zertifikat, das einem einzelnen Apple-Developer-Team ausgestellt wurde. Jede Person kann eine .pkpass lesen, aber nur dieses Team kann eine neue Datei erzeugen, die Wallet installiert.

Aussteller — Fluggesellschaften, Veranstaltungsorte, Einzelhändler, Verkehrsbetriebe, Hotels, Arbeitgeber — erzeugen eine .pkpass auf ihrem Backend und schicken sie per E-Mail, SMS-Link oder eigene App an die Kundschaft. Die Person tippt darauf, Wallet rendert eine Vorschau, und einen Tipp später liegt die Datei auf ihrem Gerät. Von dort kann Apple Wallet den Pass über einen Push-Kanal aktuell halten, ihn zur richtigen Zeit am richtigen Ort auf dem Sperrbildschirm einblenden und (bei Bordkarten und Tickets) automatisch an die Apple Watch oder an NFC-Lesegeräte übergeben.

Falls du noch keinen Pass zur Hand hast, kannst du in unter einer Minute einen erstellen — aus einem beliebigen Barcode — und alles Folgende mitvollziehen.

2. .pkpass-Dateiformat

Eine .pkpass ist ein standardmäßiges PKZip-Archiv. Du kannst example.pkpass in example.zip umbenennen, und jedes ZIP-Werkzeug listet und extrahiert die Inhalte. Das Archiv muss die Pass-Dateien direkt im Stammverzeichnis enthalten — sie in einen Ordner zu packen ist der häufigste Grund, warum ein selbst gebauter Pass nicht installiert wird. Die Dateimenge im Inneren ist klein und vorhersagbar.

Bildabmessungen

Apple gibt Bildgrößen in Punkten an; @2x bedeutet 2 Pixel pro Punkt, @3x entsprechend 3. Die meisten Aussteller liefern 1×-, @2x- und @3x-Assets aus, damit der Pass auf jedem Bildschirm — von der Watch bis zum Pro Max — gestochen scharf wirkt. Die kanonischen Größen aus Apples Leitfaden Pass Design and Creation sind:

Bilder sind PNG, sRGB, mit Alphakanal dort, wo Transparenz wichtig ist (icon, logo). Apple war historisch streng bei den exakten Abmessungen für Strip-Bilder auf Coupons; ein paar Pixel zu viel oder zu wenig können hässliche Beschnitte erzeugen, der Pass installiert sich aber meist trotzdem.

MIME-Typ, Erweiterung, Kodierung

• Erweiterung: .pkpass für einen einzelnen Pass; .pkpasses für ein Bündel mehrerer Pässe.
• MIME-Typ: application/vnd.apple.pkpass (einzeln) oder application/vnd.apple.pkpasses (Bündel).
• Zeichenkodierung: JSON-Dateien sind UTF-8. Lokalisierte pass.strings-Dateien müssen UTF-16 sein, sobald sie ein Zeichen außerhalb von ASCII enthalten — Apples Tooling liest UTF-8-Strings-Dateien stillschweigend falsch ein.

Lokalisierung

Um mehrere Sprachen zu unterstützen, fügt ein Aussteller {lang}.lproj/-Unterverzeichnisse hinzu — zum Beispiel en.lproj/, de.lproj/, ja.lproj/. Jedes davon enthält eine pass.strings-Schlüssel-/Werte-Datei mit Übersetzungen sowie optional Ersatzbilder. Bei der Anzeige wählt iOS die Locale, die der Sprache des Geräts am nächsten kommt. Apples eine strenge Regel: Lege ein Bild nicht gleichzeitig auf der obersten Ebene und in einer .lproj mit gleichem Namen ab — das führt zu undefiniertem Verhalten.

3. Inhalt von pass.json

In pass.json steckt fast jede interessante Entscheidung über einen Pass — wie er aussieht, welche Daten er anzeigt, wo er auftaucht und wie er sich aktualisiert. Das Schema ist in Apples PassKit Bundle Reference dokumentiert und ist seit 2012 bemerkenswert stabil geblieben.

Schlüssel auf oberster Ebene

Sechs Schlüssel sind auf jedem Pass erforderlich; alles Übrige ist optional, aber nützlich.

Feldgruppen

Innerhalb des gewählten Stil-Dictionarys sind die Felder in fünf Arrays organisiert: headerFields, primaryFields, secondaryFields, auxiliaryFields und backFields. Jedes ist eine Liste von Feld-Dictionarys. Header-Felder erscheinen oben rechts auf dem Pass und sind selbst dann sichtbar, wenn der Pass im Wallet-Stapel zusammengeklappt ist; primäre Felder sind groß und mittig; sekundäre und Hilfsfelder sind die kleinen Label-/Wert-Paare in einer Zeile darunter; Back-Felder sind alles, was du siehst, wenn du auf das i auf der Rückseite der Karte tippst.

Ein Feld-Dict braucht key (eindeutig innerhalb des Passes) und value; alles Übrige — label, Ausrichtung, Datums- und Zahlenformatierung, changeMessage, dataDetectorTypes, attributierte Werte mit HTML — ist optional. Datumsfelder verwenden ISO-8601-Strings und werden auf dem Gerät gemäß dateStyle, timeStyle und der Locale der Person formatiert.

Back-Felder sind in zweierlei Hinsicht besonders: Ihre value-Strings werden standardmäßig auf URLs, Telefonnummern, Daten und Adressen durchsucht und als antippbare Links gerendert — pro Feld mit dataDetectorTypes: [] überschreibbar — und sie unterstützen attributedValue mit einer kleinen Untermenge von HTML, von der <a href> die nützlichste ist, weil sie es erlaubt, eine antippbare URL mit einem Anzeigetext zu versehen, der sich von der URL selbst unterscheidet. Back-Felder sind die einzige Stelle auf einem Pass, an der die Person Inhalte antippen kann.

Barcodes

Ein Barcode-Dictionary hat vier Schlüssel: format, message, messageEncoding und das optionale altText. Die vier unterstützten Formate sind PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec und PKBarcodeFormatCode128. Die 2D-Formate (QR, PDF417, Aztec) wurden mit iOS 9 zusammen mit dem neuen barcodes-Array hinzugefügt; vor iOS 9 war der singulare Schlüssel barcode mit Code 128 der einzige Mechanismus. Code 128 ist ein 1D-linearer Barcode und wird auf der Apple Watch nicht gerendert, daher müssen Pässe für die Watch QR, PDF417 oder Aztec wählen. messageEncoding ist erforderlich und ist typischerweise iso-8859-1; verwende utf-8, wenn die Payload Zeichen außerhalb von Latin-1 enthält.

Farben

Apples Farbparser akzeptiert nur die CSS-Funktionsform rgb(R, G, B) mit ganzzahligen Werten von 0 bis 255. #RRGGBB, rgba() und benannte Farben werden stillschweigend ignoriert, sodass Wallet auf Standardwerte zurückfällt. Das ist einer der häufigsten Gründe, warum ein Pass installiert wird, aber falsch aussieht: Jemand hat einen Hex-Wert eingefügt, und der Parser ist still auf Schwarz auf Weiß zurückgefallen.

Semantische Tags

Seit iOS 12 trägt das optionale semantics-Dict strukturierte Metadaten, die iOS für Siri-Vorschläge, Sperrbildschirm-Relevanz und Apple-Watch-Awareness verwendet. Bei einem Flug sind das airlineCode + flightNumber + departureAirportCode + currentDepartureDate; bei einem Event eventName + venueLocation + eventStartDate; bei einem Transitpass transitProvider + departureStationName + currentDepartureDate. Wallet bindet eine Bordkarte über diese Tags an Apples Flug-Tracker, ohne dass der Aussteller dafür einen Webservice betreiben muss.

4. Wie die Signatur funktioniert

Die Signatur ist das, was einen echten Pass von einem manipulierten oder gefälschten unterscheidet. Hier ist die Vertrauenskette von oben nach unten:

• Apple Root CA — Apples Offline-Root, eingebettet in die Trust Stores von iOS, macOS und watchOS.
• Apple Worldwide Developer Relations (WWDR) Intermediate — Apple hat dieses Intermediate mehrmals rotiert. Die Generationen G2 bis G6 sind alle aktuell ausgestellt und für unterschiedliche Zertifikatstypen gültig; Pass-Type-ID-Zertifikate haben jahrelang über das ursprüngliche WWDR (und nun über neuere Generationen, da Apple rotiert) verkettet. Die Signatur muss diejenige WWDR-Generation bündeln, über die das Pass-Type-ID-Zertifikat verkettet ist. Ältere Tutorials kodieren ein abgelaufenes Intermediate fest — wenn die Signatur fehlschlägt, lade das WWDR-Zertifikat, das zur Generation deines Pass Type ID passt, neu von apple.com/certificateauthority herunter.
• Pass-Type-ID-Zertifikat — wird einem einzelnen Apple-Developer-Team ausgestellt, gebunden an einen einzelnen Reverse-DNS-pass-type-identifier (z. B. pass.com.example.coupon). Das ist das Leaf-Zertifikat, dessen privater Schlüssel jeden Pass signiert.

Jedes Pass-Type-ID-Zertifikat kodiert den pass type identifier als UID in seinem Subject und die 10-stellige Team ID des Teams als OU. Apple Wallet prüft beides bei der Installation.

Der Signaturablauf

Aus Apples offiziellem Leitfaden ergeben sich die folgenden Schritte:

1. Baue das unsignierte Pass-Paket: pass.json plus alle Bilder, in einem Verzeichnis.
2. Gehe das Verzeichnis rekursiv durch, berechne den SHA-1 über den Inhalt jeder Datei und schreibe das Ergebnis als JSON-Objekt in manifest.json, das jeden relativen Pfad auf seinen SHA-1-Hex-Digest abbildet — z. B. "icon.png" → "abc123…", "pass.json" → "def456…". Schließe manifest.json und signature selbst nicht ein.
3. Erstelle eine PKCS#7-Detached-Signatur über die Bytes von manifest.json, mit dem privaten Schlüssel des Pass-Type-ID-Zertifikats. Bündle das passende WWDR-Intermediate-Zertifikat in der Signatur, damit Wallet eine Kette zur Apple-Root aufbauen kann, und transportiere das S/MIME-Attribut signing-time.
4. Zippe die Inhalte des Pass-Verzeichnisses (nicht das Verzeichnis selbst) in eine Datei mit der Erweiterung .pkpass.

Die meisten Referenzimplementierungen verwenden für den Signaturschritt OpenSSL:

openssl smime -binary -sign \
  -certfile WWDR.pem \
  -signer passcert.pem \
  -inkey passkey.pem \
  -in manifest.json \
  -out signature \
  -outform DER

Apple liefert außerdem ein kleines Objective-C-Tool namens signpass im Archiv Wallet Companion Files aus, das dieselbe Logik kapselt.

Was iOS validiert

Wenn eine Person eine .pkpass öffnet, führt Apple Wallet ungefähr diese Prüfung durch:

1. Parse das ZIP-Archiv; lade manifest.json, signature und pass.json.
2. Verifiziere die PKCS#7-Detached-Signatur über die exakten Bytes von manifest.json.
3. Baue eine Zertifikatskette vom Leaf über das gebündelte WWDR-Intermediate zur Apple Root CA und prüfe, ob das Leaf nicht abgelaufen oder widerrufen ist.
4. Berechne die Hashes aller Dateien im Bundle neu und bestätige, dass jeder Digest mit dem Wert in manifest.json übereinstimmt.
5. Bestätige, dass passTypeIdentifier in pass.json der UID des Leaf-Zertifikats entspricht und teamIdentifier dem OU des Zertifikats.

Jeder Fehler erzeugt einen generischen Installationsfehler; iOS verrät weder der Person noch der Entwicklerin, welcher Schritt gescheitert ist. Deshalb beginnt fast jede „Dieser Pass kann nicht installiert werden"-Debugging-Session mit der Verifikation der Manifest-Hashes und der Zertifikatskette.

Warum du den Pass von jemand anderem nicht erneut signieren kannst

Das Pass-Type-ID-Zertifikat ist bei Ausstellung an ein Team und einen Identifier gebunden. Apple stellt kein Zertifikat für den Identifier einer anderen Person aus, und das Ändern von passTypeIdentifier in pass.json auf einen, der dir gehört, zerstört das Manifest und den darauf bezogenen Push-Update-Kanal pro Pass. Selbst mit der originalen .pkpass in der Hand kannst du also den Pass eines Drittanbieters nicht unter deinem eigenen Zertifikat neu signieren und installieren lassen — so ist es per Design.

5. Eine .pkpass-Datei öffnen

Wo du eine .pkpass öffnen kannst — und welche Funktionen erhalten bleiben — hängt von der Plattform ab.

Eine .pkpass-Datei auf iPhone, iPad und Apple Watch öffnen

Das native Erlebnis. Tippe in Mail, Nachrichten, Safari oder Dateien auf den .pkpass-Anhang: iOS erkennt den MIME-Typ, öffnet eine Vollbild-Wallet-Vorschau und bietet einen Hinzufügen-Button. Nach dem Hinzufügen synchronisiert sich der Pass automatisch mit einer gekoppelten Apple Watch. Ab iOS 27 (erscheint im September 2026) wird Apple Wallet außerdem einen integrierten Pass erstellen-Button enthalten, mit dem Nutzer jeden QR-Code in einen Pass verpacken können, ohne einen Developer-Account zu benötigen — wir behandeln das hier.

Eine .pkpass-Datei auf dem Mac öffnen

macOS hat keine Wallet-App — Wallet auf dem Mac ist nur ein Einstellungsbereich für Apple-Pay-Karten. Aber ein Doppelklick auf eine .pkpass im Finder öffnet eine private System-App namens Pass Viewer (/System/Library/CoreServices/Pass Viewer.app), die den Pass rendert und Zu Apple Wallet hinzufügen anbietet. Die Hinzufügen-Aktion sendet den Pass an den iCloud-Account der Person; er taucht dann auf jedem iPhone, iPad und jeder Apple Watch auf, die mit derselben Apple ID angemeldet sind. Der Mac selbst speichert den Pass nie lokal. Safari auf macOS macht dasselbe, wenn du auf einer Website auf einen „Zu Apple Wallet hinzufügen"-Button tippst.

Eine .pkpass-Datei auf Android öffnen

Apple Wallet ist auf Android nicht verfügbar, aber du kannst eine .pkpass-Datei auf Android — Stand 2026 — auf fünf verschiedene Arten öffnen:

• Google Wallet (nativ, teilweise). Seit April 2024 kann Google Wallet auf Android .pkpass-Dateien direkt importieren: Tippe in deinem Dateimanager, in Gmail oder im Browser auf die Datei, und das Teilen-Menü bietet Zu Google Wallet hinzufügen an. Die Verbreitung ist regional gesteuert, und Websites, die deinen User-Agent erkennen, bieten die Datei einem Android-Browser oft gar nicht erst an. Als Alternative kannst du auf jedem Gerät unseren PKPASS-zu-Google-Wallet-Konverter nutzen, um einen Speicherlink zu erzeugen.
• Pass2U Wallet (com.passesalliance.wallet). Die beliebteste Drittanbieter-Option, zuletzt im Januar 2026 aktualisiert. Importiert .pkpass, fragt webServiceURL auf Updates ab, kann auf Google Drive sichern, hat einen integrierten Pass-Designer.
• WalletPasses (io.walletpasses.android). Langjährige App, werbefrei, unterstützt Geofence- und iBeacon-Benachrichtigungen. Zuletzt im Juni 2025 aktualisiert.
• FossWallet (nz.eloque.foss_wallet). Die — Stand 2026 — aktiv gepflegte Open-Source-Option, GPL-3.0, auf F-Droid. Nachfolger von PassAndroid (das moderne Pässe nicht mehr zuverlässig installiert).
• PassWallet (com.attidomobile.passwallet). Die ursprüngliche Drittanbieter-Option; wird weiterhin gepflegt, aber die Oberfläche zeigt ihr Alter.

Auf keiner dieser Apps stehen NFC-Value-Added-Services (Apple-Pay-artiges Tippen), Apple-Watch-Sync und Express-Modus zur Verfügung. Auto-Updates werden gepollt, statt über APNs gepusht zu werden.

Eine .pkpass-Datei auf Windows, Linux und ChromeOS öffnen

Kein nativer Handler. Drei gute Wege:

• Browserbasierter Viewer. Lege die Datei in unseren PKPASS Viewer — er parst alles clientseitig und zeigt die Kartenvorschau, jedes Feld und das rohe pass.json.
• In PDF konvertieren. Verwende unseren PKPASS-zu-PDF-Konverter, um eine druckbare A4-Datei mit dem Barcode in Druckauflösung zu erhalten.
• Wie ein ZIP behandeln. Benenne in .zip um (Windows) oder führe unzip pass.pkpass aus (Linux/macOS) und sieh dir die Dateien direkt an. Praktisch, wenn du nur pass.json lesen möchtest.

Auf ChromeOS macht das Android-Subsystem Pass2U / WalletPasses zur einfachsten Installation, falls du volle Lese- und Update-Unterstützung möchtest. Ansonsten funktioniert der Browser-Viewer-Weg auf jedem Chromebook.

6. Pass-Stile

Jede .pkpass entspricht einem von fünf Stilen, deklariert durch den Top-Level-Schlüssel, der in pass.json vorhanden ist. Der Stil bestimmt das Layout, welche Bilder verwendet werden und was den Pass auf dem Sperrbildschirm einblendet.

Hinweise zum Verhalten:

• boardingPass rendert Start und Ziel als übergroße primäre Felder mit einem Chevron dazwischen, mit dem Footer-Bild direkt über dem Barcode. Mehrere Pässe, die einen groupingIdentifier teilen, werden zu einem Stapel zusammengeklappt.
• eventTicket hat zwei Darstellungen: ein randloses (stark unscharfes) background.png mit Thumbnail und kreisförmigem Barcode, oder ein strip.png oben, ohne Thumbnail. Apple empfiehlt, beides nicht zu mischen.
• coupon wird vom Strip-Bild dominiert; primärer Text liegt darüber. suppressStripShine ist hier am wichtigsten für moderne, flache Designs.
• storeCard zeigt typischerweise ein Guthaben als primäres Feld. Wenn nfc vorhanden ist, lebt hier Wallets Tap-to-Redeem-UI.
• generic ist das Fallback-Layout: kleines Logo und Thumbnail rechts, primäres Feld neben dem Logo. Verwende es für Mitgliedskarten, Ausweise — alles, was nicht zu einem spezifischeren Stil passt.

7. Fehler und Fehlerbehebung

Die Installationsfehler von Apple Wallet sind absichtlich generisch: „Dieser Pass kann nicht auf dem iPhone installiert werden", „Dieser Pass ist ungültig", „Pass konnte nicht hinzugefügt werden". Sie alle bedeuten dasselbe — einer der Validierungsschritte aus Abschnitt 4 ist gescheitert — aber iOS sagt nicht, welcher. Die üblichen Verdächtigen, nach Häufigkeit geordnet:

Im Zweifel lege den Pass in den PKPASS Viewer — er zeigt, ob das Bundle überhaupt parst, ob die Signatur vorhanden ist, ob pass.json validiert und welche Bilder gebündelt sind. Die meisten Pässe, deren Installation fehlschlägt, parsen im Viewer trotzdem sauber, was das Problem auf die Signatur eingrenzt.

8. Eine .pkpass erstellen

Du hast drei praktikable Wege, eine .pkpass zu erstellen.

1. Verwende ein gehostetes Tool wie WalletWallet. Der einfachste, schnellste, kostenlose Weg: Lege einen Barcode (oder ein Foto davon) hinein, wähle Farben, erhalte eine signierte .pkpass zurück. Probier es aus. Wir signieren jeden Pass mit unserem eigenen Pass-Type-ID-Zertifikat, sodass Installationen auf jedem iPhone, iPad, jeder Watch und jedem Mac funktionieren, ohne dass du dich mit dem Apple Developer Program befassen musst. Vollständige Anleitung zum kostenlosen Pass.
2. Selbst bauen mit Apples Tools. Registriere ein Pass Type ID im Apple Developer Portal (Mitgliedschaft 99 US$/Jahr), lade ein Pass-Type-ID-Zertifikat plus das passende WWDR-Intermediate von Apples PKI-Seite herunter, schreibe deine eigene pass.json, erzeuge das Manifest und die Signatur mit OpenSSL oder Apples signpass-Tool, und zippe. Ausgereifte sprachspezifische Bibliotheken — passkit-generator (Node), alvinbaena/passkit (Go), applepassgenerator (Python), walletkit (Rust) — übernehmen das Manifest-Hashing und die PKCS#7-Signaturschritte für dich.
3. Nutze eine gehostete Aussteller-Plattform. Passcreator, PassNinja, Passslot und ähnliche Dienste lassen dich einen Pass als Vorlage anlegen, dein eigenes Zertifikat einbinden und Werte per POST übergeben, um signierte Pässe zu erzeugen. Sinnvoll, wenn du Push-Updates und eine API möchtest, die Zertifikatserneuerung aber nicht selbst betreiben willst.

Ein Pass ist „kostenlos" zu hosten, aber nicht kostenlos im großen Maßstab auszustellen: Die Mitgliedschaft im Apple Developer Program kostet 99 US$ pro Jahr und Team, Zertifikate werden jährlich erneuert, und APNs-Push für Pass-Updates ist kostenlos, aber rate-limitiert.

9. Häufig gestellte Fragen