dotnet-passbook

To generate a pass, follow these steps:

1. Instantiate a PassGenerator.
2. Create a PassGeneratorRequest and populate mandatory fields (PassTypeIdentifier, TeamIdentifier, SerialNumber, Description, OrganizationName, LogoText).
3. Set colors using HTML (e.g., #FFFFFF) or RGB (e.g., rgb(255,255,255)) formats.
4. Assign your AppleWWDRCACertificate and PassbookCertificate.
5. Add images as byte[] (standard and retina sizes are required).
6. Set the Style (e.g., PassStyle.BoardingPass) and add fields to the appropriate sections (Primary, Secondary, Auxiliary).
7. Call generator.Generate(request) to receive a byte[] representing the .pkpass file.

PassGenerator generator = new PassGenerator();
PassGeneratorRequest request = new PassGeneratorRequest();

// Mandatory Data
request.PassTypeIdentifier = "pass.tomsamcguinness.events";   
request.TeamIdentifier = "RW121242";
request.SerialNumber = "121212";
request.Description = "My first pass";
request.OrganizationName = "Tomas McGuinness";
request.LogoText = "My Pass";

// Colors
request.BackgroundColor = "#FFFFFF";
request.LabelColor = "#000000";
request.ForegroundColor = "#000000";

// Certificates
request.AppleWWDRCACertificate = new X509Certificate(...);
request.PassbookCertificate = new X509Certificate(...);

// Images (Standard and Retina required)
request.Images.Add(PassbookImage.Icon, System.IO.File.ReadAllBytes("icon.png"));
request.Images.Add(PassbookImage.Icon2X, System.IO.File.ReadAllBytes("icon@2x.png"));
request.Images.Add(PassbookImage.Icon3X, System.IO.File.ReadAllBytes("icon@3x.png"));

// Pass Specifics
request.Style = PassStyle.BoardingPass;
request.AddPrimaryField(new StandardField("origin", "San Francisco", "SFO"));
request.AddPrimaryField(new StandardField("destination", "London", "LDN"));
request.AddSecondaryField(new StandardField("boarding-gate", "Gate", "A55"));
request.AddAuxiliaryField(new StandardField("seat", "Seat", "G5"));
request.AddAuxiliaryField(new StandardField("passenger-name", "Passenger", "Thomas Anderson"));

request.TransitType = TransitType.PKTransitTypeAir;

// Barcode
request.AddBarcode(BarcodeType.PKBarcodeFormatPDF417, "01927847623423234234", "ISO-8859-1", "01927847623423234234");

// Generate
byte[] generatedPass = generator.Generate(request);

To use dotnet-passbook, you need two certificates: the Apple Worldwide Developer Relations certificate (G1) and an application-specific certificate. If you are not using IIS and the Windows certificate store, you can generate these using OpenSSL following these steps:

1. Download the Apple WWDR Certificate: Download the G1 version from Apple and save it as AppleWWDRCA.cer.
   • ⚠️ Important: Only the G1 certificate will generate valid Apple Wallet passes. Other generations (G2, G3, etc.) will result in the error: "Sorry, your Pass cannot be installed to Passbook at this time."
2. Create a Pass Type ID: In the Apple Developer portal, go to Certificates, Identifiers & Profiles > Identifiers, select Pass Type IDs from the dropdown, and create a new one (e.g., pass.com.company.appname).
3. Generate a Certificate Signing Request (CSR): Use OpenSSL to create a .csr file and a private .key file.
4. Sign the CSR: Upload your .csr to the Apple Developer portal under Certificates > Services > Pass Type ID Certificate to download a pass.cer file.
5. Convert to PEM: Convert the binary pass.cer to a text-based PEM format.
6. Convert to PKCS12: Convert the PEM certificate and your private key into a .pfx file.
7. Configure Application: Add both the AppleWWDRCA.cer and the passbook.pfx to your project and provide the paths and the export password to the PassGeneratorRequest.

var request = new PassGeneratorRequest();
request.AppleWWDRCACertificate = File.ReadAllBytes("AppleWWDRCA.cer");
request.Certificate = File.ReadAllBytes("passbook.pfx");
request.CertificatePassword = "<your_export_password>";

To generate valid passes, you must provide two specific certificates as X509Certificate instances in your PassGeneratorRequest:

1. Passbook Certificate: Obtained from your Apple Developer Portal. Ensure it includes the private key component.
2. Apple WWDR (WorldWide Developer Relations) Certificate: Downloadable from Apple's Certificate Authority.

Note on WWDR versions:

• If your Passbook certificate was generated on or before January 27, 2022, use the G1 WWDR certificate.
• Otherwise, use the G4 certificate.

When loading certificates in cloud environments, it is recommended to use MachineKeySet and Exportable flags to avoid signing issues:

X509KeyStorageFlags flags = X509KeyStorageFlags.MachineKeySet | X509KeyStorageFlags.Exportable;
X509Certificate2 certificate = new X509Certificate2(bytes, password, flags);