APNS Tools

This repository contains scripts to assist with testing APNS clients with the APNS simulator.

The tools currently provided are described below.

Fake Apple Push Certificates and Keys

fake_apple_certs.sh will generate

• A fake Apple Root CA certificate and private key
• A fake Apple Worldwide Developer Relations CA certificate and private key
• A fake Apple intermediate certificate (ISTCA2G1) and private key
• A fake Apple api.push.apple.com production server certificate and private key
• A fake Apple api.development.push.apple.com development server certificate and private key
• A chain file for the fake WWDR CA certificate, consisting of the fake root and the fake WWDR CA certificate
• A chain file for the fake ISTCA2G1 certificate, consisting of the fake root and the fake ISTCA2G1 CA certificate
• A fake VoIP client certificate and private key for com.example.FakeApp.
• Two elliptic curve private keys for testing APNS token-based authentication.

These attempt to duplicate the real Apple certificates as closely as possible, obviously with different serial numbers, public keys, Subject Key Identifiers, and Authority Key Identifiers.

The purpose of these certs is to create fake Apple Push certificates for use in an APNS simulation environment. The simulation environment would need to provide the fake Apple WWDR chain file to any test clients, and serve the ISTCA2G1 chain file along with the server cert on the simulation server.

The same is true for the elliptic curve private keys, which can be used for testing token-based authentication in an APNS simulation environment.

File locations

The directory tree containing the certificates looks like this:

|- CA
|  |- certs/FakeAppleCA.cert.pem
|  |- private/FakeAppleCA.key.unencrypted.pem
|  |- ISTCA2G1
|  |  | - FakeAppleISTCA2G1.csr
|  |  | - certs/FakeAppleDevPushServer.cert.pem
|  |  | - certs/FakeAppleISTCA2G1.cert.pem
|  |  | - certs/FakeAppleISTCA2G1.chain.cert.pem
|  |  | - certs/FakeAppleProdPushServer.cert.pem
|  |  | - private/FakeAppleDevPushServer.key.unencrypted.pem
|  |  | - private/FakeAppleISTCA2G1.key.unencrypted.pem
|  |  | - private/FakeAppleProdPushServer.key.unencrypted.pem
|  |- WWDRCA
|  |  | - FakeAppleWWDRCA.csr
|  |  | - com.example.FakeApp.universal.csr
|  |  | - com.example.FakeApp.voip.csr
|  |  | - certs/FakeAppleWWDRCA.chain.cert.pem
|  |  | - certs/FakeAppleWWDRCA.cert.pem
|  |  | - certs/com.example.FakeApp.universal.cert.pem
|  |  | - certs/com.example.FakeApp.voip.cert.pem
|  |  | - private/FakeAppleWWDRCA.key.unencrypted.pem
|  |  | - private/com.example.FakeApp.universal.key.unencrypted.pem
|  |  | - private/com.example.FakeApp.voip.key.unencrypted.pem
|- apns_auth_keys
|  |- APNsAuthKey_6F44JJ9SDF_com.example.FakeApp_UB40ZZXKCDZ.p8
|  |- APNsAuthKey_6F44JJ9SDF_com.example.FakeApp.voip_V782ZPDP1Z.p8

The entire tree may be deleted. It will be regenerated by the script; note that some details of the certificates and keys will change due to the random key generation and the deletion of the serial and index files.

Token-based auth keys

The token-based auth keys are generated using the openssl ecparam command, using the prime256v1 elliptic curve, then converted to PKCS8 format.

For convenience, the key files are named

APNsAuthKey_${team_id}_${bundle_id}_${key_id}.p8

where (at present)

• ${team_id} is 6F44JJ9SDF
• ${bundle_id} is one of
  • com.example.FakeApp
  • com.example.FakeApp.voip
• ${key_id} is one of
  • UB40ZZXKCDZ
  • V782ZPDP1Z

Being regular EC private keys not generated by Apple, they obviously are not associated with any key id and so on. The naming convention is aimed to simplify key lookup in a simulation environment; when receiving a JWT, iss, apns-topic and kid correspond to ${team_id}, ${bundle_id}, and ${key_id}, respectively.

Deviations

The Apple push server certificates are issued by the ISTCA2G1 certificate. The real ISTCA2G1 CA certificate is issued by GeoTrust. Obviously, we can't issue the fake certificate from GeoTrust unless we make a fake one of those, too, which seems unnecessarily burdensome. To mitigate this, the issuer for the fake ISTCA2G1 CA certificate is the fake Apple Root CA.

TODO

• Add generation of fake APNS client certificates for
  • enterprise development/production
  • (optionally) Apple Watch, Mac Push, others