APNs SSL/TLS certificate

Get and configure an SSL/TLS certificate to establish secure connections to the Apple Push Notification service.

Important:

On March 31 2021 Apple® discontinued the APNs legacy binary protocol. Therefore, the com.APNS class is now desupported. The documentation pages related to the APNS binary protocol are still provided for information. Contact your support center, if you need to implement APNS with the new HTTP/2-based provider API.

Starting with Genero V5.00, the com.APNS classe will be removed from the com package.

Basics

The Apple Push Notification Certificate identifies the push notification service for a given mobile app. This certificate is created from an App ID (also known as Bundle ID) and is used by the APNs system to dispatch the notification message to the registered devices.

You can create two types of APN certificates for a given App ID:
  • Sandbox (for development and test purpose)
  • Production (for deployment)
An APNS push notification provider or an APNS feedback handler needs to establish a secure connection to Apple's APNs server.

Get an APNs certificate for your app

In this section we will produce the .cer certificate file and the myapp-key.p12 file.

To create an Apple Push Notification Certificate:

  1. Log in to Apple's Member Center with you iOS developer or enterprise account.
  2. Select Certificates, Identifiers & Profiles.
  3. Under App IDs, make sure that you have created an App ID with the Push Notification service enabled, for development and/or distribution.
  4. Under Certificates, select the + symbol.
  5. Select Apple Push Notification service SSL (Sandbox) for development, or Apple Push Notification service SSL (Sandbox & Production) for production.
  6. Choose the App ID with push notifications service enabled.
  7. Follow the instructions to create a Certificate Signing Request (CSR) file from your Mac, then click Continue.
  8. Back in the web browser and IOS Certificate page, upload the CSR file you have generated.
  9. Generate the certificate.
  10. Once the certificate is generated, download it. The certificate will be downloaded into your Downloads folder, as "aps_development.cer" file in case the sandbox certificate is chosen, or as "aps.cer" in case the production certificate is chosen. In the next sections, this certificate file will be referenced as "myapp.cer".
  11. Double-click this file to import the certificate into the Mac® Keychain®.
  12. The new certificate is now listed in the Certificates list.
  13. Open your Keychain app and locate the certificate you created, export the private key in p12 format (for example, myapp-key.p12). Note that you will be asked for a password to encode the .p12 file, and for your session password, to exported Keychain files.

Configure Genero to use the APNs certificate

On the Genero push provider server, you will need the public certificate (myapp.crt file) and the private key (myapp-key.pem file) for you app. These files will be referenced in the security.global.certificate and security.global.privatekey entries of FGLPROFILE.

In order to authenticate the APNs server, you will also need the root certificate authority (apple_entrust_root_certification_authority.pem), that can be downloaded from Apple's web site. This file will be referenced by the security.global.ca entry in FGLPROFILE.
Note:

When executing on a Mac, the root certificate (security.global.ca entry) is not required: The Web Services library reads the Keystore of the Mac computer, to authenticate the APNs server.

Create the myapp.crt file (public certificate) from the myapp.cer file, with the openssl x509 command: 
$ openssl x509 -in myapp.cer -inform der -out myapp.crt
Convert the myapp-key.p12 file (containing the private key) to a myapp-key.pem format, with the openssl pkcs12 command:
$ openssl pkcs12 -nocerts -in myapp-key.p12 -out myapp-key.pem
Note:

You need to enter the passphrase for the .p12 file so that openssl can read it. Then you need to enter a new passphrase that will be used to encrypt the .pem file.

The FGLPROFILE entry security.global.privatekey expects unencrypted private key files. Therefore, you need to remove the passphrase from the myapp-key.pem file, with the openssl rsa command: 
$ openssl rsa -in myapp-key.pem -out myapp-key-noenc.pem
Set up your FGLPROFILE with the appropriate security.* entries: 
security.global.ca           = "apple_entrust_root_certification_authority.pem"
security.global.certificate  = "myapp.crt"
security.global.privatekey   = "myapp-key-noenc.pem"
In the above example:
  1. apple_entrust_root_certification_authority.pem is the HTTPS root certificate authenticating the APNs server (if the computer is not a Mac).
  2. myapp.crt is the public certificate for your app.
  3. myapp-key-noenc.pem is the unencrypted private key file for your app.
Note:

If you want to keep the private key encrypted, you need to configure a password agent, as described in Using the password agent