Instrument iOS application with customer certificate​

During the normal instrumentation process, a Perfecto library is added to the app’s binary. Specific function calls inside the app may be replaced with calls to functions from the Perfecto library.  As a result of this processing:

  • Apps have to be resigned with a Perfecto iOS certificate after the binary has been modified, due to iOS code signature requirements

  • Apps using special entitlements, that require the original author's certificate, may not work after the resigning process.

Perfecto offers a feature that enables customers to instrument an application with the Perfecto library and then re-sign with the customer's own certificate. The main advantages of the Customized Instrumentation feature include:

  • Users have the ability to instrument the app while maintaining the original application entitlements and signature.

  • The instrumentation process remains the same, except for the resign step;

    • Instead of resigning with Perfecto certificate, the application signature is performed locally, at the customer's premises, on a Mac machine with the customer’s enterprise certificate.

How it works

The resign process is performed on a Mac machine within the Customer's environs.

The Keychain on the signing Mac should include:

  • The enterprise certificate used to resign the instrumented application, 
  • Mobileprovision file matching the enterprise certificate.

Perfecto will provide the user with a script, to run on the Mac machine, that executes the following steps (see diagram above):

Step 1: Upload the application file (*.ipa file) to Perfecto's instrumentation service.

Step 2: Download the instrumented application file (*.ipa file) from Perfecto's instrumentation service.

Step 3: Resign the instrumented application file with the customer's certificate.

Requirements for the Mac machine

  • OS - High Sierra or later

  • XCode 8.3.3 or later 

  • Python 3.6 and later - with "requests" module installed.

    • To install "requests" module run the following command:

      Copy
      pip3 install requests
  • Open to internet connection (to access Perfecto services)

  • Keychain on Mac should contain the required enterprise certificate (no duplicate names- verify only a single entry with this name in the keychain list)

  • Keychain password

  • Mobileprovisionfile matching the enterprise certificate

  • *.ipa file of the application (which should be instrumented) 

Download the Python Script

Go to GitHub to download the Python script: customInstrumentWrapper.py

Run Perfecto's resign script on the Mac machine

  • Run the script with the Python service.

    Copy

    Example script activation

    python3 customInstrumentWrapper.py -i inputIPA.ipa -o outputIPA.ipa -t token.txt -p provision.mobileprovision -c "certificate name" -u LAB.perfectomobile.com -v <labVersionNum> -ih -is

    Script name: customInstrumentWrapper.py

Required parameters

Parameter Description
 -i (IPA) Original ipa File to Instrument
-o (OUTPUT_FILE) Name for the Instrumented ipa File
-p PROVISIONING_PROFILE Mobile Provisioning Profile File to use
-c CERTIFICATE_NAME Name of the Certificate to use, as saved in the Keychain
-t TOKEN Text file Containing a Valid Security Token
-u URL Perfecto Lab URL
-v VERSION Perfecto Lab Version

Instrumentation flags

At least one of the following instrumentation flags is required.

Flag Description
-ih  Enables Hybrid Instrumentation
-is Enables Sensors Instrumentation

Optional Parameters

Parameter Description
-en (Optional) Entitlements File. Add a prepared entitlements plist profile in place of the generic entitlements section generated by the script, based on the information provided.

Script Output

During execution - the script reports its progress through the steps indicated above.

Upon completion, the fully instrumented and signed ipa file is generated.

Demo

Limitations and troubleshooting

  • Using multiple certificates to sign the application is not supported.
  • For troubleshooting, see this article.