Certificates and signing
You can build without a certificate, but you can't install on a device. Put your .p12 and .mobileprovision in the keychain folder and every build signs automatically. Also covers choosing a certificate in the project and overriding it on the command line.
Set up signing certificates
Put your .p12 certificate, .mobileprovision profile and the password file password.properties into a keychain folder. If you don't have a certificate and profile yet, see Create a certificate and provisioning profile below.
The keychain folder can be in two places, and certificates from both are used together:
- <project>/keychain/: for that project only
- KXBUILD_HOME/keychain/: shared by all projects. By default %USERPROFILE%\kxbuild\keychain\ on Windows and ~/kxbuild/keychain/ on WSL, Linux and macOS
On macOS, certificates in the system keychain can also be used directly.
password.properties has one line per certificate in the form file=password. The file name must match the .p12 exactly, and the password has no quotes.
development.p12=123456
distribution.p12=123456From then on, every build signs automatically according to the project's signing settings. There's nothing to configure in KXBuild. Without a certificate the project still builds, but the product is unsigned and won't install on an iPhone.
Create a certificate and provisioning profile
You need two files: a .p12 certificate that contains your private key, and a .mobileprovision profile. See the certificate and profile type tables at the end of this page. When you switch to a new iPhone with a Development profile, add its UDID in your developer account and download the profile again.
Both files come from your Apple Developer account. On Windows there are three ways to get them.
Generate them with Appuploader (recommended)
Appuploader is an App Store helper for Windows. Sign in with your developer account to create certificates, export .p12 files, and create and download provisioning profiles. You can also use it to submit to the App Store.
Export them from a Mac
In Keychain Access, export the certificate together with its private key as a .p12, then download the profile from developer.apple.com. A .cer file alone won't work because it has no private key.
Generate them with OpenSSL
Generate a private key and a CSR, upload the CSR on the Certificates page at developer.apple.com, download the .cer, then combine them into a .p12.
> openssl req -new -newkey rsa:2048 -nodes -keyout ios.key -out ios.csr -subj "/emailAddress=you@example.com/CN=Your Name/C=CN"> openssl x509 -in development.cer -inform DER -out development.pem> openssl pkcs12 -export -inkey ios.key -in development.pem -out development.p12How kxbuild picks a certificate
As in Xcode, it follows the project's signing settings (General > Signing in the Project Settings Editor) and picks from the keychain folder in three steps:
Certificate type
If the signing identity CODE_SIGN_IDENTITY is Apple Development, a development certificate is used; if it is Apple Distribution, a distribution certificate.
Team
Only certificates and profiles of the team in DEVELOPMENT_TEAM are used.
Provisioning profile
With automatic signing, the profile is matched by Bundle ID and team; with manual signing, it is looked up by the name in PROVISIONING_PROFILE_SPECIFIER.
New projects use Apple Development with automatic signing, so there is nothing to change for day-to-day work.
To avoid editing the project file on the command line, override settings with -D:
Switch to the distribution certificate for an App Store build:
> kxbuild build .\MyApp.xcodeproj -c Release -D CODE_SIGN_IDENTITY="Apple Distribution"Build without signing:
> kxbuild build .\MyApp.xcodeproj -D CODE_SIGNING_ALLOWED=NOIf a build fails with No signing certificate matching '…' found, the keychain folder has no certificate of the type or team the project asks for. Add the matching .p12, or use -D as above to switch to a certificate you already have.
Certificate types
The certificate (.p12) identifies who signed the app. The common types:
| Certificate | Used for | Goes with profile |
|---|---|---|
| Apple Development | Development: run and debug on a test iPhone | Development |
| Apple Distribution | Release: upload to the App Store / TestFlight, Ad Hoc test distribution, in-house distribution with an Enterprise account | App Store Connect, Ad Hoc, In-House |
| iOS App Development | Older development certificate, same use as Apple Development, still works | Development |
| iOS Distribution | Older distribution certificate, same use as Apple Distribution, still works | App Store Connect, Ad Hoc, In-House |
| Apple Push Notification service SSL | Lets your server send push notifications. It does not sign apps, so don't put it in the keychain folder | — |
Provisioning profile types
The provisioning profile (.mobileprovision) says which certificate may sign the app and which devices it may be installed on. It is tied to a Bundle ID, which must match the project. The common types:
| Profile | Used for | Certificate | Devices |
|---|---|---|---|
| Development | Development and debugging; Debug builds | Apple Development | Only iPhones whose UDID is registered in the profile |
| Ad Hoc | Send a test build to a few testers outside the App Store | Apple Distribution | Only registered UDIDs, up to 100 per device type per year |
| App Store Connect | Upload to App Store Connect for TestFlight and App Store release | Apple Distribution | Not installed directly; installed via TestFlight or the App Store |
| In-House | In-house distribution with an Enterprise account; employees install directly | Apple Distribution (Enterprise account) | Any device, internal use only |
Next steps
Set up your device
Get your computer to recognize your iPhone. Install the driver, trust the computer and turn on Developer Mode, download device symbols before your first debug session, and choose between multiple devices.
Troubleshooting
Run kxbuild doctor first. Then look up your error message by category: install, project, signing, device, release or extension. Also covers where to find the logs.