Skip to content

Commit d1787da

Browse files
fpseverinofpseverino
committed
Add documentation on how to generate the certificates
1 parent 8fdf51d commit d1787da

File tree

6 files changed

+146
-2
lines changed

6 files changed

+146
-2
lines changed

‎Sources/WalletOrders/OrderBuilder.swift

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ public struct OrderBuilder: Sendable {
1818

1919
/// Creates a new ``OrderBuilder``.
2020
///
21-
/// > Tip: Obtaining the three certificates files could be a bit tricky. You could get some guidance from [this guide](https://github.com/alexandercerutti/passkit-generator/wiki/Generating-Certificates) and [this video](https://www.youtube.com/watch?v=rJZdPoXHtzI). Those guides are for Wallet passes, but the process is similar for Wallet orders.
21+
/// > Tip: Obtaining the three certificates files could be a bit tricky. See <doc:Certificates> to get some guidance.
2222
///
2323
/// - Parameters:
2424
/// - pemWWDRCertificate: Apple's WWDR.pem certificate in PEM format.

‎Sources/WalletOrders/WalletOrders.docc/Certificates.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Generating the Certificates
2+
3+
Generate the certificates you need to sign your order.
4+
5+
## Overview
6+
7+
To instanciate a ``OrderBuilder`` you need to provide the following elements:
8+
- WWDR (Apple WorldWide Developer Relations) G4 Certificate
9+
- Order Type ID Certificate
10+
- Order Type ID Certificate Private Key
11+
12+
The following steps will guide you through the process of generating these certificates on macOS.
13+
14+
You'll need to have OpenSSL installed on your machine.
15+
Check if you have it installed by running the following command in your terminal:
16+
17+
```shell
18+
openssl --version
19+
```
20+
21+
> Important: To obtain the certificates you have to be a member of the Apple Developer Program.
22+
23+
### Create an Order Type Identifier
24+
25+
See [Create an order type identifier](https://developer.apple.com/documentation/walletorders/building-a-distributable-order-package#Create-an-order-type-identifier) in the Apple Developer Documentation.
26+
27+
### Download the WWDR G4 Certificate
28+
29+
Download the [WWDR G4 certificate](https://www.apple.com/certificateauthority/AppleWWDRCAG4.cer), open it (or import it) in Keychain Access, filter for "Certificates" and identify your imported certificate.
30+
Right-click on it and select Export AppleWWDRCAG4.
31+
Choose the `.pem` file format and save it.
32+
33+
### Generate a Signing Certificate
34+
35+
Now follow Apple's guide on how to [Generate a signing certificate](https://developer.apple.com/documentation/walletorders/building-a-distributable-order-package#Generate-a-signing-certificate) in the Apple Developer Documentation.
36+
After following the guide, you should have a `.cer` file.
37+
38+
Now open (or import) the Signing Certificate in Keychain Access.
39+
Filter for "Certificates" and identify your imported certificate.
40+
Right-click on it and select Export "CertificateName".
41+
Choose the `.p12` file format and save it.
42+
You'll be asked to set a password for the exported certificate.
43+
You can leave it empty if you don't want to encrypt the certificate, but if you do, remember the password.
44+
45+
Next, open the Terminal and navigate to the directory where you saved the exported `.p12` file.
46+
Run the following command to extract the certificate from the `.p12` file.
47+
Change `<SigningCertificate>` to the name of your exported `.p12` certificate and `<p12Password>` to the password you set when exporting the certificate.
48+
If you didn't set a password, remove `-passin pass:<p12Password>` from the command.
49+
50+
```shell
51+
openssl pkcs12 -in <SigningCertificate>.p12 -clcerts -nokeys -out certificate.pem -passin pass:<p12Password> -legacy
52+
```
53+
54+
Now run the following command to extract the private key from the `.p12` file.
55+
Again, change `<SigningCertificate>` to the name of your exported `.p12` certificate and `<p12Password>` to the password you set when exporting the certificate, if you set one.
56+
If you want to encrypt the private key with a password, change `<pemPrivateKeyPassword>` to the password you want to set.
57+
Remember this password, you'll have to provide it when creating the ``OrderBuilder``.
58+
If you don't want to encrypt the private key, remove `-passout pass:<pemPrivateKeyPassword>` from the command.
59+
60+
```shell
61+
openssl pkcs12 -in <cert-name>.p12 -nocerts -out privateKey.pem -passin pass:<p12Password> -passout pass:<pemPrivateKeyPassword> -legacy
62+
```
63+
64+
### Wrapping Up
65+
66+
You now have the WWDR G4 Certificate, the Order Type ID Certificate, and the Order Type ID Certificate Private Key, all in `.pem` format, and optionally a password for the private key.
67+
Open the `.pem` files in a text editor and copy the content.
68+
You'll need to provide this content as Swift `String`s when creating the ``OrderBuilder``.
69+
It's highly recommended to provide the content and the password as environment variables to avoid hardcoding sensitive information in your code.
70+
71+
You can look at [this guide](https://github.com/alexandercerutti/passkit-generator/wiki/Generating-Certificates) and [this video](https://www.youtube.com/watch?v=rJZdPoXHtzI) if you need more help. Those guides are for Wallet passes, but the process is similar for Wallet orders.

‎Sources/WalletOrders/WalletOrders.docc/WalletOrders.md

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ For information on Apple Wallet orders, see the [Apple Developer Documentation](
1212

1313
### Essentials
1414

15+
- <doc:Certificates>
1516
- ``OrderBuilder``
1617
- ``OrderJSON``
1718

‎Sources/WalletPasses/PassBuilder.swift

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ public struct PassBuilder: Sendable {
1818

1919
/// Creates a new ``PassBuilder``.
2020
///
21-
/// > Tip: Obtaining the three certificates files could be a bit tricky. You could get some guidance from [this guide](https://github.com/alexandercerutti/passkit-generator/wiki/Generating-Certificates) and [this video](https://www.youtube.com/watch?v=rJZdPoXHtzI).
21+
/// > Tip: Obtaining the three certificates files could be a bit tricky. See <doc:Certificates> to get some guidance.
2222
///
2323
/// - Parameters:
2424
/// - pemWWDRCertificate: Apple's WWDR.pem certificate in PEM format.

‎Sources/WalletPasses/WalletPasses.docc/Certificates.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Generating the Certificates
2+
3+
Generate the certificates you need to sign your pass.
4+
5+
## Overview
6+
7+
To instanciate a ``PassBuilder`` you need to provide the following elements:
8+
- WWDR (Apple WorldWide Developer Relations) G4 Certificate
9+
- Pass Type ID Certificate
10+
- Pass Type ID Certificate Private Key
11+
12+
The following steps will guide you through the process of generating these certificates on macOS.
13+
14+
You'll need to have OpenSSL installed on your machine.
15+
Check if you have it installed by running the following command in your terminal:
16+
17+
```shell
18+
openssl --version
19+
```
20+
21+
> Important: To obtain the certificates you have to be a member of the Apple Developer Program.
22+
23+
### Create a Pass Type Identifier
24+
25+
See [Create a Pass Type Identifier](https://developer.apple.com/documentation/walletpasses/building-a-pass#Create-a-Pass-Type-Identifier) in the Apple Developer Documentation.
26+
27+
### Download the WWDR G4 Certificate
28+
29+
Download the [WWDR G4 certificate](https://www.apple.com/certificateauthority/AppleWWDRCAG4.cer), open it (or import it) in Keychain Access, filter for "Certificates" and identify your imported certificate.
30+
Right-click on it and select Export AppleWWDRCAG4.
31+
Choose the `.pem` file format and save it.
32+
33+
### Generate a Signing Certificate
34+
35+
Now follow Apple's guide on how to [Generate a Signing Certificate](https://developer.apple.com/documentation/walletpasses/building-a-pass#Generate-a-Signing-Certificate) in the Apple Developer Documentation.
36+
After following the guide, you should have a `.cer` file.
37+
38+
Now open (or import) the Signing Certificate in Keychain Access.
39+
Filter for "Certificates" and identify your imported certificate.
40+
Right-click on it and select Export "CertificateName".
41+
Choose the `.p12` file format and save it.
42+
You'll be asked to set a password for the exported certificate.
43+
You can leave it empty if you don't want to encrypt the certificate, but if you do, remember the password.
44+
45+
Next, open the Terminal and navigate to the directory where you saved the exported `.p12` file.
46+
Run the following command to extract the certificate from the `.p12` file.
47+
Change `<SigningCertificate>` to the name of your exported `.p12` certificate and `<p12Password>` to the password you set when exporting the certificate.
48+
If you didn't set a password, remove `-passin pass:<p12Password>` from the command.
49+
50+
```shell
51+
openssl pkcs12 -in <SigningCertificate>.p12 -clcerts -nokeys -out certificate.pem -passin pass:<p12Password> -legacy
52+
```
53+
54+
Now run the following command to extract the private key from the `.p12` file.
55+
Again, change `<SigningCertificate>` to the name of your exported `.p12` certificate and `<p12Password>` to the password you set when exporting the certificate, if you set one.
56+
If you want to encrypt the private key with a password, change `<pemPrivateKeyPassword>` to the password you want to set.
57+
Remember this password, you'll have to provide it when creating the ``PassBuilder``.
58+
If you don't want to encrypt the private key, remove `-passout pass:<pemPrivateKeyPassword>` from the command.
59+
60+
```shell
61+
openssl pkcs12 -in <cert-name>.p12 -nocerts -out privateKey.pem -passin pass:<p12Password> -passout pass:<pemPrivateKeyPassword> -legacy
62+
```
63+
64+
### Wrapping Up
65+
66+
You now have the WWDR G4 Certificate, the Pass Type ID Certificate, and the Pass Type ID Certificate Private Key, all in `.pem` format, and optionally a password for the private key.
67+
Open the `.pem` files in a text editor and copy the content.
68+
You'll need to provide this content as Swift `String`s when creating the ``PassBuilder``.
69+
It's highly recommended to provide the content and the password as environment variables to avoid hardcoding sensitive information in your code.
70+
71+
You can look at [this guide](https://github.com/alexandercerutti/passkit-generator/wiki/Generating-Certificates) and [this video](https://www.youtube.com/watch?v=rJZdPoXHtzI) if you need more help.

‎Sources/WalletPasses/WalletPasses.docc/WalletPasses.md

+1
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ For information on Apple Wallet passes, see the [Apple Developer Documentation](
2020

2121
### Essentials
2222

23+
- <doc:Certificates>
2324
- ``PassBuilder``
2425
- ``PassJSON``
2526

0 commit comments

Comments
 (0)