Cette page a été traduite par l'API Cloud Translation.

apksigner

L'outil apksigner, disponible dans la version de révision 24.0.3 de SDK Build-Tools pour Android, vous permet de signer les fichiers APK et de confirmer que la signature d'un APK est validée avec succès sur toutes les versions d'Android de la plate-forme Android compatibles avec ce fichier APK.

Cette page propose un guide rapide d'utilisation de l'outil et sert de référence pour les différentes options de ligne de commande compatibles avec l'outil. Pour obtenir une description plus complète de la façon dont l'outil apksigner est utilisé pour signer vos fichiers APK, consultez le guide Signer votre application.

Attention : Si vous signez le fichier APK à l'aide d'apksigner et que vous y apportez des modifications supplémentaires, sa signature n'est plus valide. Si vous utilisez zipalign pour aligner votre fichier APK, utilisez-le avant de signer l'APK.

Utilisation

Signer un fichier APK

La syntaxe de signature d'un fichier APK à l'aide de l'outil apksigner est la suivante :

apksigner sign --ks keystore.jks |
  --key key.pk8 --cert cert.x509.pem
  [signer_options] app-name.apk

Lorsque vous signez un fichier APK à l'aide de l'outil apksigner, vous devez fournir la clé privée et le certificat du signataire. Vous pouvez inclure ces informations de deux façons :

Spécifiez un fichier KeyStore à l'aide de l'option --ks.
Spécifiez le fichier de clé privée et le fichier de certificat séparément à l'aide des options --key et --cert. Le fichier de clé privée doit utiliser le format PKCS #8 et le fichier de certificat le format X.509.

En général, vous signez un fichier APK avec un seul signataire. Si vous devez signer un fichier APK à l'aide de plusieurs signataires, utilisez l'option --next-signer pour séparer l'ensemble des options générales à appliquer à chacun d'eux :

apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk

Vérifier la signature d'un fichier APK

Voici la syntaxe permettant de confirmer la validation de la signature d'un fichier APK sur les plates-formes compatibles :

apksigner verify [options] app-name.apk

Effectuer une rotation des clés de signature

Voici la syntaxe permettant d'effectuer la rotation d'une lignée de certificats de signature ou d'une nouvelle séquence de signatures :

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file \
  --old-signer --ks old-signer-jks \
  --new-signer --ks new-signer-jks

Options

Les listes suivantes répertorient l'intégralité des options pour chaque commande compatible avec l'outil apksigner.

Commande de signature

La commande de signature apksigner propose les options suivantes.

Options générales

Les options suivantes spécifient les paramètres de base à appliquer à un signataire :

--out <apk-filename>

Emplacement où vous souhaitez enregistrer le fichier APK signé. Si cette option n'est pas fournie explicitement, le package APK est signé sur place, ce qui remplace le fichier APK d'entrée.

--min-sdk-version <integer>

Niveau d'API du framework Android le plus bas utilisé par apksigner pour s'assurer que la signature du fichier APK sera vérifiée. Des valeurs plus élevées permettent à l'outil d'utiliser des paramètres de sécurité renforcée lors de la signature de l'application, mais limitent la disponibilité du fichier APK aux appareils exécutant des versions plus récentes d'Android. Par défaut, apksigner utilise la valeur de l'attribut minSdkVersion du fichier manifeste de l'application.

--max-sdk-version <integer>

Niveau d'API du framework Android le plus élevé utilisé par apksigner pour s'assurer que la signature du fichier APK sera vérifiée. Par défaut, l'outil utilise le niveau d'API le plus élevé.

--rotation-min-sdk-version <integer>

Niveau d'API le plus bas que la clé de signature de l'APK avec rotation doit utiliser pour générer la signature de l'APK. La clé de signature d'origine (n'ayant fait l'objet d'aucune rotation) du fichier APK est utilisée pour toutes les versions de plate-forme précédentes. Par défaut, les clés de signature ayant subi une rotation, qui sont compatibles avec les appareils exécutant Android 13 (niveau d'API 33) ou version ultérieure, sont utilisées avec le bloc de signature v3.1.

Remarque : Si votre application a été signée par une clé de signature ayant fait l'objet d'une rotation sur un appareil équipé d'Android 12L (niveau d'API 32) ou version antérieure, vous devez utiliser --rotation-min-sdk-version 28 pour continuer à signer votre application avec cette clé de signature pour Android 9 (niveau d'API 28).

--v1-signing-enabled <true | false>

Détermine si apksigner signe le package APK donné à l'aide du schéma de signature traditionnel JAR. Par défaut, l'outil utilise les valeurs de --min-sdk-version et --max-sdk-version pour décider quand appliquer ce schéma de signature.

--v2-signing-enabled <true | false>

Détermine si apksigner signe le package APK donné à l'aide du schéma de signature des fichiers APK v2. Par défaut, l'outil utilise les valeurs de --min-sdk-version et --max-sdk-version pour décider quand appliquer ce schéma de signature.

--v3-signing-enabled <true | false>

Détermine si apksigner signe le package APK donné à l'aide du schéma de signature des fichiers APK v3. Par défaut, l'outil utilise les valeurs de --min-sdk-version et --max-sdk-version pour décider quand appliquer ce schéma de signature.

--v4-signing-enabled <true | false | only>

Détermine si apksigner signe le package APK donné à l'aide du schéma de signature des fichiers APK v4. Ce schéma génère une signature dans un fichier distinct (apk-name.apk.idsig). Si true et l'APK ne sont pas signés, une signature v2 ou v3 est générée en fonction des valeurs de --min-sdk-version et --max-sdk-version. La commande génère ensuite le fichier .idsig en fonction du contenu du fichier APK signé.

Utilisez only pour générer uniquement la signature v4 sans modifier l'APK ni les signatures dont il disposait avant l'appel. only échoue si l'APK ne possède pas encore de signature v2 ou v3, ou si la signature a utilisé une clé différente de celle fournie pour l'appel en cours.

Par défaut, l'outil utilise les valeurs de --min-sdk-version et --max-sdk-version pour décider quand appliquer ce schéma de signature.

-v, --verbose

Utilisez le mode de sortie détaillé.

Options par signataire

Les options suivantes spécifient la configuration d'un signataire particulier. Ces options ne sont pas nécessaires si vous signez votre application avec un seul signataire.

--next-signer <signer-options>: Permet de spécifier différentes options générales pour chaque signataire.
--v1-signer-name <basename>: Nom de base des fichiers comprenant la signature basée sur JAR pour le signataire actuel. Par défaut, apksigner utilise l'alias de clé du keystore ou le nom de base du fichier de clé de ce signataire.

Options de clé et de certificat

Les options suivantes spécifient la clé privée et le certificat du signataire :

--ks <filename>

La clé privée et la chaîne de certificats du signataire résident dans le fichier keystore Java donné. Si le nom de fichier est défini sur "NONE", il n'est pas nécessaire de spécifier un fichier pour le keystore contenant la clé et le certificat, ce qui est le cas de certains keystores PKCS #11.

--ks-key-alias <alias>

Nom de l'alias qui représente les données de clé privée et de certificat du signataire dans le keystore. Si le keystore associé au signataire contient plusieurs clés, vous devez spécifier cette option.

--ks-pass <input-format>

Mot de passe du keystore contenant la clé privée et le certificat du signataire. Vous devez fournir un mot de passe pour ouvrir un keystore. L'outil apksigner accepte les formats suivants :

pass:<password> : mot de passe fourni avec le reste de la commande apksigner sign.
env:<name> : mot de passe stocké dans la variable d'environnement donnée.
file:<filename> : mot de passe stocké sur une seule ligne dans le fichier donné.
stdin : mot de passe fourni sur une seule ligne dans le flux d'entrée standard. Il s'agit du comportement par défaut pour --ks-pass.

Remarque : Si vous incluez plusieurs mots de passe dans le même fichier, saisissez-les sur des lignes distinctes. L'outil apksigner associe les mots de passe aux signataires d'un fichier APK en fonction de l'ordre dans lequel vous les spécifiez. Si vous avez fourni deux mots de passe pour un signataire, apksigner interprète le premier mot de passe comme le mot de passe du keystore et le second comme mot de passe de la clé.

--pass-encoding <charset>

Inclut les encodages des caractères spécifiés (tels que ibm437 ou utf-8) lorsque vous essayez de gérer des mots de passe contenant des caractères non ASCII.

L'utilitaire keytool chiffre souvent les keystores en convertissant le mot de passe à l'aide du charset par défaut de la console. Par défaut, apksigner tente de déchiffrer les données à l'aide de plusieurs formats de mot de passe :

Format Unicode

Format encodé à l'aide du jeu de caractères par défaut de la JVM

Format encodé à l'aide du charset par défaut de la console (sur Java 8 et les versions antérieures)

Sous Java 9, apksigner n'est pas en mesure de détecter le charset de la console. Dès lors, vous serez peut-être amené à spécifier --pass-encoding lorsqu'un mot de passe non ASCII est utilisé. Vous devrez peut-être également spécifier cette option avec les keystores créés par l'utilitaire keytool dans un système d'exploitation ou des paramètres régionaux différents.

--key-pass <input-format>

Mot de passe de la clé privée du signataire, qui est nécessaire si la clé privée est protégée par un mot de passe. L'outil apksigner accepte les formats suivants :

pass:<password> : mot de passe fourni avec le reste de la commande apksigner sign.
env:<name> : mot de passe stocké dans la variable d'environnement donnée.
file:<filename> : mot de passe stocké sur une seule ligne dans le fichier donné.
stdin : mot de passe fourni sur une seule ligne dans le flux d'entrée standard. Il s'agit du comportement par défaut pour --key-pass.

--ks-type <algorithm>

Type ou algorithme associé au keystore contenant la clé privée et le certificat du signataire. Par défaut, apksigner utilise le type défini comme constante keystore.type dans le fichier de propriétés de sécurité.

--ks-provider-name <name>

Nom du fournisseur JCA à utiliser lorsque vous demandez l'implémentation du keystore du signataire. Par défaut, apksigner utilise le fournisseur doté de la priorité la plus élevée.

--ks-provider-class <class-name>

Nom de classe complet du fournisseur JCA à utiliser lorsque vous demandez l'implémentation du keystore du signataire. Cette option sert d'alternative à --ks-provider-name. Par défaut, apksigner utilise le fournisseur spécifié avec l'option --ks-provider-name.

--ks-provider-arg <value>

Valeur de chaîne à transmettre en tant qu'argument pour le constructeur de la classe JCA du fournisseur. La classe, quant à elle, est définie avec l'option --ks-provider-class. Par défaut, apksigner utilise le constructeur d'argument 0 de la classe.

--key <filename>

Nom du fichier contenant la clé privée du signataire. Ce fichier doit utiliser le format DER PKCS #8. Si la clé est protégée par un mot de passe, apksigner demande le mot de passe à l'aide d'une entrée standard, sauf si vous spécifiez un autre type de format d'entrée à l'aide de l'option --key-pass.

--cert <filename>

Nom du fichier contenant la chaîne de certificats du signataire. Ce fichier doit utiliser le format PEM ou DER X.509.

Commande de validation

La commande de validation apksigner propose les options suivantes.

--print-certs: Affiche les informations sur les certificats de signature du fichier APK
--min-sdk-version <integer>: Niveau d'API du framework Android le plus bas utilisé par apksigner pour s'assurer que la signature du fichier APK sera vérifiée. Des valeurs plus élevées permettent à l'outil d'utiliser des paramètres de sécurité renforcée lors de la signature de l'application, mais limitent la disponibilité du fichier APK aux appareils exécutant des versions plus récentes d'Android. Par défaut, apksigner utilise la valeur de l'attribut minSdkVersion du fichier manifeste de l'application.
--max-sdk-version <integer>: Niveau d'API du framework Android le plus élevé utilisé par apksigner pour s'assurer que la signature du fichier APK sera vérifiée. Par défaut, l'outil utilise le niveau d'API le plus élevé.
-v, --verbose: Utilisez le mode de sortie détaillé.
-Werr: Traitez les avertissements comme des erreurs.

Exemples

Voici des exemples utilisant apksigner.

Signer un fichier APK

Signez un fichier APK à l'aide de release.jks, qui est la seule clé du keystore :

$ apksigner sign --ks release.jks app.apk

Signez un fichier APK à l'aide d'une clé privée et d'un certificat, stockés dans des fichiers distincts :

$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk

Signez un fichier APK à l'aide de deux clés :

$ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk

Signez un fichier APK avec une clé de signature ayant fait l'objet d'une rotation et la rotation ciblant la version de SDK 28 (ou version ultérieure) :

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk \
  --rotation-min-sdk-version 28

Signez un fichier APK avec une clé de signature ayant fait l'objet d'une rotation et la rotation ciblant la version de SDK 33+ :

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk

Vérifier la signature d'un fichier APK

Vérifiez si la validité des signatures du fichier APK doit être confirmée sur toutes les plates-formes Android compatibles avec le fichier APK :

$ apksigner verify app.apk

Vérifiez si la validité des signatures du fichier APK doit être confirmée sur Android 4.0.3 (niveau d'API 15) ou version ultérieure :

$ apksigner verify --min-sdk-version 15 app.apk

Effectuer une rotation des clés de signature

Activez une lignée de certificats de signature compatible avec la rotation des clés :

$ apksigner rotate --out /path/to/new/file --old-signer \
    --ks release.jks --new-signer --ks release2.jks

Effectuez une nouvelle rotation de vos clés de signature :

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file --old-signer --ks release2.jks \
  --new-signer --ks release3.jks