Skip to main content

Apple signing keys

Overview​

Apple Signing and Distribution keys are obtained through the Apple Developer Portal Certificates, Identifiers, and Profiles

Developers will each need to have a development certificate created for them, or else a team will need a shared key for each machine.

Apple and iOS Distribution certificates are limited in the organization. Currently, the Health and Benefits App has its own certificate for Apple Distribution. In the future, it may be that teams have a shared signing path with different provisioning profiles, but at this time it is not necessary.

Apple Certificates expire every year and need to be renewed. This process is linked below and requires updating both the Certificates' area in the Developer Portal, and work to update the Fastlane Match system used to sign apple builds.

Fastlane Match and Apple Signing​

Apple Signing in our build system is managed with Fastlane match. Match manages and stores the certificates so that a single Distribution certificate can be shared with the team through GitHub authorization to the private, encrypted repository.

Match can be called from a local machine to download the certificates and provisioning profiles for distribution or development. It is also used to sign certificates in the CI during Fastlane scripts.

Renewing Certificates​

In order to renew certificates you will need to revoke the old certificates with Apple and delete them from the private key repository.

Revoking old certificates​

In Apple Developer, revoke the old certificate(s) and delete the associated profile(s). The follow are examples for renewing a distribution certificate:

CERT NAMETYPEPLATFORM
US Department of Veterans Affairs (VA)DistributionAll
PROFILE NAMEPLATFORMTYPE
match AppStore gov.va.vamobileappiOSApp Store

Deleting certificates​

Delete the following from your local copy of the private key repository:

- `/profiles/appstore/<filename>.mobileprovision`
- `/certs/distribution/<filename>.cer`
- `/certs/distribution/<filename>.p12`

Then push up your changes to the remote repository.This needs to be done on in the remote repository, not just locally, as Match will clone the remote repository to a temporary directory and then try (and fail) to decrypt them. You may need to delete additional certs from other paths (e.g., /certs/developer/...) if you run into a decrpyt error when running the fastlane match command below.

Creating new certificates​

Once the certificates have been deleted from both locations you can run match in your terminal to renew the certs navigate to ~/VAMobile/ios/fastlane and then run fastlane match appstore. You should be able to follow the prompt to create a new Distribution Certificate and Provisioning Profile that will be uploaded to the private repository and can then be used for signing apps.

If you run into issues, review the following:

  • Try using brew install fastlane if your build is erroring out
  • Does the Apple ID in the ../ios/fastlane/Appfile belong to you?
  • The Apple ID is case sensitive. If your Apple ID password is getting rejected, this might be the issue.

After generating the new certs make sure the MATCH_PASSWORD secret in the va-mobile-app repository is updated so GH Actions can use it and test by running the iOS On Demand workflow. If the signing part doesn't fail before build everything should be good to go. You can PR any file changes that may have happened.

info

You may need to update the configs and profiles in the VAMobile.plist with xCode if the name strings are changed. If you receive a build error about not finding a cert, double check this first

Special guidance for Apple Push Service certificates​

Apple Push Service certificates need to be refreshed yearly in August and sent to the VANotify team. Review Apple Documentation on how to create a push certificate and how to create a signing request. The VA Notify team needs the certificate in .p12 and the private key unencrypted (.cer file). Review documentation on converting the .cer file into .p12. Coordination for this happens into the #va-mobile-app-push-notifications Slack channel.

Full testing should be completed with QA before retiring the old certificate.

Location in the CI​

Apple certificates are encrypted by Fastlane match into a private repository and fetched at build time.

On your local machine they can be found in the Keychain Access application.

ENV Constants for the keys​

All keys are stored in match

More Documentation​