Signature manuelle de l’APKManually Signing the APK

Une fois l’application générée pour sa mise en production, l’APK doit être signé avant distribution afin de pouvoir être exécuté sur un appareil Android.After the application has been built for release, the APK must be signed prior to distribution so that it can be run on an Android device. Ce processus est généralement géré par l’environnement IDE. Toutefois, dans certaines situations, il est nécessaire de signer l’APK manuellement au niveau de la ligne de commande.This process is typically handled with the IDE, however there are some situations where it is necessary to sign the APK manually, at the command line. La signature d’un APK met en œuvre les étapes suivantes :The following steps are involved with signing an APK:

  1. Créer une clé privée – Cette étape ne doit être effectuée qu’une seule fois.Create a Private Key – This step needs to be performed only once. Une clé privée est nécessaire pour signer numériquement l’APK.A private key is necessary to digitally sign the APK. Une fois la clé privée préparée, cette étape peut être ignorée pour les prochaines builds de mise en production.After the private key has been prepared, this step can be skipped for future release builds.

  2. Compresser l’APK dans un fichier zipalignZipalign est un processus d’optimisation qui est réalisé sur une application.Zipalign the APKZipalign is an optimization process that is performed on an application. Il permet à Android d’interagir plus efficacement avec l’APK au moment de l’exécution.It enables Android to interact more efficiently with the APK at runtime. Xamarin.Android effectue une vérification au moment de l’exécution et n’autorise pas l’exécution de l’application si l’APK n’a pas été compressé dans un fichier zipalign.Xamarin.Android conducts a check at runtime, and will not allow the application to run if the APK has not been zipaligned.

  3. Signer l’APK – Cette étape implique l’utilisation de l’utilitaire apksigner d’Android SDK et la signature de l’APK avec la clé privée qui a été créée à l’étape précédente.Sign the APK – This step involves using the apksigner utility from the Android SDK and signing the APK with the private key that was created in the previous step. Les applications développées avec des versions des outils de génération du kit Android SDK antérieures à la version 24.0.3 utiliseront l’application jarsigner du JDK.Applications that are developed with older versions of the Android SDK build tools prior to v24.0.3 will use the jarsigner app from the JDK. Ces deux outils sont décrits plus en détail ci-dessous.Both of these tools will be discussed in more detail below.

L’ordre des étapes est important et dépend de l’outil utilisé pour signer l’APK.The order of the steps is important and is dependent on which tool used to sign the APK. Si vous utilisez apksigner, il est important de commencer par compresser l’application dans un fichier zipalign, puis de le signer avec apksigner.When using apksigner, it is important to first zipalign the application, and then to sign it with apksigner. Si jarsigner doit être utilisé pour signer l’APK, il est important de commencer par signer l’APK, puis d’exécuter zipalign.If it is necessary to use jarsigner to sign the APK, then it is important to first sign the APK and then run zipalign.

PrérequisPrerequisites

Ce guide met l’accent sur l’utilisation de l’utilitaire apksigner disponible dans les outils de génération du kit Android SDK v24.0.3 ou version supérieure.This guide will focus on using apksigner from the Android SDK build tools, v24.0.3 or higher. Il est supposé qu’un APK a déjà été généré.It assumes that an APK has already been built.

Les applications qui sont générées à l’aide d’une version antérieure des outils de génération du kit Android SDK doivent utiliser jarsigner comme décrit dans Signer l’APK avec jarsigner ci-dessous.Applications that are built using an older version of the Android SDK Build Tools must use jarsigner as described in Sign the APK with jarsigner below.

Créer un magasin de clés privéCreate a Private Keystore

Un magasin de clés est une base de données de certificats de sécurité créée à l’aide du programme keytool du SDK Java.A keystore is a database of security certificates that is created by using the program keytool from the Java SDK. Un magasin de clés est un élément essentiel pour la publication d’une application Xamarin.Android. En effet, Android n’exécutera pas les applications qui n’ont pas été signées numériquement.A keystore is critical to publishing a Xamarin.Android application, as Android will not run applications that have not been digitally signed.

Au cours du développement, Xamarin.Android utilise un magasin de clés de débogage pour signer l’application, ce qui permet le déploiement direct de l’application sur l’émulateur ou sur des appareils configurés pour utiliser des applications pouvant être déboguées.During development, Xamarin.Android uses a debug keystore to sign the application, which allows the application to be deployed directly to the emulator or to devices configured to use debuggable applications. Toutefois, ce magasin de clés n’est pas reconnu comme magasin de clés valide pour les besoins de la distribution d’applications.However, this keystore is not recognized as a valid keystore for the purposes of distributing applications.

Pour cette raison, un magasin de clés privé doit être créé et utilisé pour la signature des applications.For this reason, a private keystore must be created and used for signing applications. Cette étape ne doit être effectuée qu’une seule fois, car la même clé sera utilisée pour la publication des mises à jour et pourra ensuite être utilisée pour signer d’autres applications.This is a step that should only be performed once, as the same key will be used for publishing updates and can then be used to sign other applications.

Il est important de protéger ce magasin de clés.It is important to protect this keystore. S’il est perdu, il ne sera pas possible de publier des mises à jour de l’application sur Google Play.If it is lost, then it will not be possible to publish updates to the application with Google Play. En cas de perte d’un magasin de clés, la seule solution est de créer un nouveau magasin de clés, de resigner l’APK avec la nouvelle clé, puis de soumettre une nouvelle application.The only solution to the problem caused by a lost keystore would be to create a new keystore, re-sign the APK with the new key, and then submit a new application. L’ancienne application devra ensuite être supprimée de Google Play.Then the old application would have to be removed from Google Play. De même, si ce nouveau magasin de clés est compromis ou distribué publiquement, des versions non officielles ou malveillantes d’une application peuvent alors être distribuées.Likewise, if this new keystore is compromised or publicly distributed, then it is possible for unofficial or malicious versions of an application to be distributed.

Créer un magasin de clésCreate a New Keystore

La création d’un magasin de clés requiert l’outil en ligne de commande keytool du SDK Java.Creating a new keystore requires the command line tool keytool from the Java SDK. L’extrait de code suivant montre comment utiliser keytool (remplacez <my-filename> par le nom de fichier du magasin de clés et <key-name> par le nom de la clé dans le magasin de clés) :The following snippet is an example of how to use keytool (replace <my-filename> with the file name for the keystore and <key-name> with the name of the key within the keystore):

$ keytool -genkeypair -v -keystore <filename>.keystore -alias <key-name> -keyalg RSA \
          -keysize 2048 -validity 10000

La première chose que demande keytool est le mot de passe du magasin de clés.The first thing that keytool will ask for is the password for the keystore. Il demande ensuite des informations afin de créer la clé.Then it will ask for some information to help with creating the key. L’extrait de code suivant est un exemple de création d’une nouvelle clé nommée publishingdoc qui sera stockée dans le fichier xample.keystore :The following snippet is an example of creating a new key called publishingdoc that will be stored in the file xample.keystore:

$ keytool -genkeypair -v -keystore xample.keystore -alias publishingdoc -keyalg RSA -keysize 2048 -validity 10000
Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  Ham Chimpanze
What is the name of your organizational unit?
  [Unknown]:  NASA
What is the name of your organization?
  [Unknown]:  NASA
What is the name of your City or Locality?
  [Unknown]:  Cape Canaveral
What is the name of your State or Province?
  [Unknown]:  Florida
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=Ham Chimpanze, OU=NASA, O=NASA, L=Cape Canaveral, ST=Florida, C=US correct?
  [no]:  yes

Generating 2,048 bit RSA key pair and self-signed certificate (SHA1withRSA) with a validity of 10,000 days
        for: CN=Ham Chimpanze, OU=NASA, O=NASA, L=Cape Canaveral, ST=Florida, C=US
Enter key password for <publishingdoc>
        (RETURN if same as keystore password):
Re-enter new password:
[Storing xample.keystore]

Pour afficher la liste des clés qui sont stockées dans un magasin de clés, utilisez keytool avec l’option – list :To list the keys that are stored in a keystore, use the keytool with the – list option:

$ keytool -list -keystore xample.keystore

Compresser l’APK dans un fichier zipalignZipalign the APK

Avant de signer un APK avec apksigner, il est important de commencer par optimiser le fichier à l’aide de l’outil zipalign du SDK Android.Before signing an APK with apksigner, it is important to first optimize the file using the zipalign tool from the Android SDK. zipalign va restructurer les ressources d’un APK sur des limites de 4 octets.zipalign will restructure the resources in an APK along 4-byte boundaries. Cette alignement permet à Android de charger rapidement les ressources de l’APK, augmentant ainsi les performances de l’application et réduisant potentiellement l’utilisation de la mémoire.This alignment allows Android to quickly load the resources from the APK, increasing the performance of the application and potentially reducing memory use. Xamarin.Android effectuera une vérification au moment de l’exécution pour déterminer si le fichier APK a été compressé dans un fichier zipalign.Xamarin.Android will conduct a run-time check to determine if the APK has been zipaligned. Si l’APK n’a pas été compressé dans un fichier zipalign, l’application ne fonctionnera pas.If the APK is not zipaligned, then the application will not run.

La commande suivante utilise l’APK signé et produit un APK compressé dans un fichier zipalign et signé nommé helloworld.apk qui est prêt pour la distribution.The follow command will use the signed APK and produce a signed, zipaligned APK called helloworld.apk that is ready for distribution.

$ zipalign -f -v 4 mono.samples.helloworld-unsigned.apk helloworld.apk

Signer l’APKSign the APK

Après avoir compressé l’APK dans un fichier zipalign, il est nécessaire de le signer à l’aide d’un magasin de clés.After zipaligning the APK, it is necessary to sign it using a keystore. Cette opération est réalisée avec l’outil apksigner, disponible dans le répertoire build-tools de la version des outils de génération du kit SDK.This is done with the apksigner tool, found in the build-tools directory of the version of the SDK build tools. Par exemple, si les outils de génération du kit Android SDK v25.0.3 sont installés, apksigner se trouve dans le répertoire suivant :For example, if the Android SDK build tools v25.0.3 is installed, then apksigner can be found in the directory:

$ ls $ANDROID_HOME/build-tools/25.0.3/apksigner
/Users/tom/android-sdk-macosx/build-tools/25.0.3/apksigner*

L’extrait de code suivant suppose que l’outil apksigner est accessible par la variable d’environnement PATH.The following snippet assumes that apksigner is accessible by the PATH environment variable. Il signe un APK à l’aide de l’alias de clé publishingdoc contenu dans le fichier xample.keystore :It will sign an APK using the key alias publishingdoc that is contained in the file xample.keystore:

$ apksigner sign --ks xample.keystore --ks-key-alias publishingdoc mono.samples.helloworld.apk

Lorsque cette commande est exécutée, apksigner vous demande le mot de passe du magasin de clés si nécessaire.When this command is run, apksigner will ask for the password to the keystore if necessary.

Consultez la documentation de Google pour plus d’informations sur l’utilisation de l’outil apksigner.See Google's documentation for more details on the use of apksigner.

Notes

D’après problème 62696222 signalé dans Google Issue Tracker, apksigner est absent du kit Android SDK.According to Google issue 62696222, apksigner is "missing" from the Android SDK. La solution consiste à installer les outils de génération du kit Android SDK v25.0.3 et d’utiliser cette version de l’outil apksigner.The workaround for this is to install the Android SDK build tools v25.0.3 and use that version of apksigner.

Signer l’APK avec jarsignerSign the APK with jarsigner

Avertissement

Cette section s’applique uniquement s’il est nécessaire de signer l’APK avec l’utilitaire jarsigner.This section only applies if it is nececssary to sign the APK with the jarsigner utility. Les développeurs sont encouragés à utiliser apksigner pour signer l’APK.Developers are encouraged to use apksigner to sign the APK.

Cette technique implique la signature du fichier APK à l’aide de la commande jarsigner du SDK Java.This technique involves signing the APK file using the jarsigner command from the Java SDK. L’outil jarsigner est fourni par le SDK Java.The jarsigner tool is provided by the Java SDK.

L’extrait de code suivant montre comment signer un APK à l’aide de jarsigner et de la clé publishingdoc qui est contenue dans un fichier de magasin de clés nommé xample.keystore :The following shows how to sign an APK by using jarsigner and the key publishingdoc that is contained in a keystore file named xample.keystore :

$ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore xample.keystore mono.samples.helloworld.apk publishingdoc

Notes

Lorsque vous utilisez jarsigner, il est important de commencer par signer l’APK, puis d’utiliser zipalign.When using jarsigner, it is important to sign the APK first, and then to use zipalign.