Versions d'une extension, mise à jour et compatibilité

Versions d'un module

Les modules doivent spécifier leurs versions en utilisant le Format de version du toolkit. Il s'agit approximativement d'une chaîne de caractères découpée par des points, comme par exemple :

• 2.0
• 1.0b1
• 3.0pre1
• 5.0.1.2

Comment les applications déterminent la compatibilité

Lors de l'installation de modules, les applications regardent les entrées de targetApplication dans le fichier <tt>install.rdf</tt> du module. L'id de cette entrée doit correspondre exactement à l'id de l'application. De plus, les valeurs minVersion et maxVersion de cette entrée doivent former un intervalle comprenant la version de l'application.

Si l'application possède une entrée targetApplication pour une version incompatible, elle tentera alors d'obtenir des informations de mise à jour à partir de l'updateURL du module.

Si le fichier install.rdf contient des entrées targetPlatform, la plateforme devant faire tourner l'application doit y être listée. Dans le cas contraire, l'installation sera refusée.

Passer outre les tests de compatibilité

Pour des besoins de tests, vous pouvez dire à l'application d'ignorer quelque peu les vérifications de compatibilité lors de l'installation de modules. Créez simplement une préférence booléenne extensions.checkCompatibility avec la valeur false.

Choix de minVersion et maxVersion

minVersion et maxVersion doivent spécifier la plage de versions de l'application sur laquelle vous avez fait des tests. En particulier, vous ne devriez jamais spécifier un maxVersion plus grand que la version actuelle de l'application, puisque vous ne connaissez pas les modifications possibles à venir des API et de l'interface utilisateur. Avec la mise à jour de compatibilité, il n'est pas nécessaire de fournir une version entière nouvelle de l'extension simplement pour augmenter son maxVersion.

Pour la valeur maxVersion, il est généralement permis d'utiliser un * à la place de la version mineure de l'application supportée, par exemple 2.0.0.* signifiera que vous supporterez toutes les mises à jour mineures de la version 2.

N'allez pas imaginer que * dans une version représente n'importe quelle version. Le * représente en fait un nombre infiniment grand et n'a réellement un sens que lorsqu'il est utilisé dans maxVersion. Si vous l'utilisez dans minVersion, vous n'obtiendrez pas le résultat escompté.

Vérification automatique des mises à jour de modules

Les applications vont vérifier périodiquement les mises à jour à installer des modules en récupérant le fichier updateURL. L'information renvoyée peut servir à prévenir l'utilisateur d'une mise à jour d'un module, aussi bien qu'indiquer à l'application qu'il existe des nouvelles versions d'applications compatibles avec ce module.

Mise à jour de compatibilité

Pendant la phase de vérification automatique, les applications examinent à la fois s'il existe des nouvelles versions et des mises à jour de compatibilité concernant la version installée d'un module. Cela signifie que votre manifeste de mise à jour contient une entrée pour la version actuellement installée du module, et l'entrée targetApplication spécifie un maxVersion plus grand, l'application utilisera cette valeur à la place de celle spécifiée dans le fichier <tt>install.rdf</tt> du module. De ce fait, des modules qui étaient désactivés car incompatibles peuvent s'activer, et des modules qui ne s'installaient normalement pas peuvent être installés.

Format RDF de mise à jour

Si vous hébergez l'updateURL de votre module vous-même, vous devrez alors retourner l'information de version dans un format RDF. Vous trouverez ci dessous un exemple de manifeste de mise à jour. Il liste les informations de 2 différentes versions de l'extension ayant pour id [email protected]. Les versions incluses sont 2.2 et 2.5, et chacune d'elles définit une compatibilité avec les versions de 1.5 à 2.0.0.* de Firefox. Pour la version 2.2, un lien https de mise à jour est employé tandis que pour la version 2.5, c'est un lien régulier http avec un hash pour vérifier le fichier récupéré.

Il est important de récupérer correctement l'attribut about du RDF:Description initial. Cette information précisera de quel type de module il s'agit :

• Pour une extension, il s'agit de urn:mozilla:extension:<id>
• Pour un thème, il s'agit de urn:mozilla:theme:<id>
• Pour tout autre type de module, il s'agit de urn:mozilla:item:<id>

Dans chacun des exemples qui vont suivre, la séquence des versions au sein de l'élément <RDF:Seq> est significative, les versions plus récentes devant être présentées après les versions plus anciennes. Il n'est pas nécessaire de lister toutes les versions intermédiaires si la dernière version est fournie.

<?xml version="1.0" encoding="UTF-8"?>

<RDF:RDF xmlns:RDF="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:em="https://www.mozilla.org/2004/em-rdf#">

  <!-- Cette ressource de description inclut toutes les informations de mise à jour 
       et de compatibilité pour un unique module ayant l'id [email protected]. 
       Vous pouvez lister plusieurs informations de module dans un même fichier RDF. -->
  <RDF:Description about="urn:mozilla:extension:[email protected]">
    <em:updates>
      <RDF:Seq>

        <!-- Chaque li est une version différente du même module -->
        <RDF:li>
          <RDF:Description>
            <em:version>2.2</em:version> <!-- Ceci est le numéro de version du module -->

            <!-- Un targetApplication pour chacune des applications avec laquelle le module est compatible -->
            <em:targetApplication>
              <RDF:Description>
                <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
                <em:minVersion>1.5</em:minVersion>
                <em:maxVersion>2.0.0.*</em:maxVersion>

                <!-- Ceci est l'emplacement de téléchargement du module -->
                <em:updateLink>https://www.mysite.com/foobar2.2.xpi</em:updateLink>

                <!-- Une page décrivant les nouveautés de la mise à jour -->
                <em:updateInfoURL>https://www.mysite.com/updateinfo2.2.xhtml</em:updateInfoURL>
              </RDF:Description>
            </em:targetApplication>
          </RDF:Description>
        </RDF:li>

        <RDF:li>
          <RDF:Description>
            <em:version>2.5</em:version>
            <em:targetApplication>
              <RDF:Description>
                <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
                <em:minVersion>1.5</em:minVersion>
                <em:maxVersion>2.0.0.*</em:maxVersion>
                <em:updateLink>https://www.mysite.com/foobar2.5.xpi</em:updateLink>
                <em:updateHash>sha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6</em:updateHash>
              </RDF:Description>
            </em:targetApplication>
          </RDF:Description>
        </RDF:li>

      </RDF:Seq>
    </em:updates>

    <!-- Une signature est nécessaire seulement si votre module inclut un updateKey dans 
         son fichier install.rdf. -->
    <em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
                  ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
                  jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
                  BcVq13ad</em:signature>
  </RDF:Description>
</RDF:RDF>

Certaines personnes préfèrent le format alternatif suivant (notez que beaucoup d'informations ont été retirées de cet exemple par souci de clarté) :

<?xml version="1.0" encoding="UTF-8"?>

<RDF:RDF xmlns:RDF="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:em="https://www.mozilla.org/2004/em-rdf#">

  <!-- Cette ressource de description inclut toutes les informations de mise à jour 
       et de compatibilité pour un unique module ayant l'id [email protected]. 
       Vous pouvez lister plusieurs informations de module dans un même fichier RDF. -->
  <RDF:Description about="urn:mozilla:extension:[email protected]">
    <em:updates>
      <RDF:Seq>
        <!-- L'attribut resource pointe vers une entrée RDF:Description correspondante 
             plus bas. L'uri peut être ce que vous voulez -->
        <RDF:li resource="urn:mozilla:extension:[email protected]:2.2"/>
        <RDF:li resource="urn:mozilla:extension:[email protected]:2.5"/>
      </RDF:Seq>
    </em:updates>
    <em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
                  ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
                  jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
                  BcVq13ad</em:signature>
  </RDF:Description>

  <!-- Ceci représente la même description qu'avec le li de l'exemple précédent -->
  <RDF:Description about="urn:mozilla:extension:[email protected]:2.2">
    <em:version>2.2</em:version>

    <!-- suppression du contenu ici -->

  </RDF:Description>

  <RDF:Description about="urn:mozilla:extension:[email protected]:2.5">
    <em:version>2.5</em:version>

    <!-- suppression du contenu ici -->

  </RDF:Description>

</RDF:RDF>

Fournir des détails sur les mises à jour

En général

Il est possible de fournir à l'utilisateur quelques détails sur les nouveautés d'une mise à jour d'un module. Ils seront visibles lorsque l'utilisateur reçoit une notification de mise à jour et devraient lui permettre d'avoir un aperçu rapide des nouvelles fonctionnalités et des problèmes de sécurité résolus.

Pour réaliser cela, vous devez ajouter une entrée updateInfoURL à votre manifeste de mise à jour (voir l'exemple plus haut). La page à cette URL sera récupérée et affichée à l'utilisateur. Puisqu'elle est affichée en dehors du contexte d'une page Web normale, son contenu est énormément assaini, ce qui signifie qu'il n'y a pas beaucoup d'options de formatage disponibles et les scripts et images ne sont pas autorisés.

• h1, h2 et h3 pour les en-têtes généraux
• p pour les paragraphes
• ul et ol pour les listes.

À l'intérieur des listes, utilisez les balises habituelles li pour chaque item.

À l'intérieur des balises h1, h2, h3, p et li, vous pouvez utiliser :

• b ou strong pour du texte en gras
• i ou em pour du texte en italique

La page d'information récupérée doit pour l'instant être totalement valide en XHTML, et doit être servie avec le type MIME application/xhtml+xml.

Vous pouvez ajouter %APP_LOCALE% dans votre updateInfoURL si vous désirez que les informations de locale soient fournis dans l'URL — ceci permet de personnaliser le texte selon la locale de l'utilisateur. Vous pouvez également utiliser les autres chaînes de substitution gérées par updateURL, bien qu'elles soient probablement moins utiles.

Ce que voit l'utilisateur

Le contenu de updateInfoURL sera affiché pour l'utilisateur dans la page des modules complémentaires, dans une liste des mises à jour disponibles. L'utilisateur peut ensuite cliquer sur le bouton Afficher les informations et verra celles-ci sur le côté droit. (notez que l'intitulé du bouton devient Masquer les informations)

Mises à jour sécurisées

Gecko 1.9 dispose d'un processus supplémentaire destiné à protéger les utilisateurs contre les attaques de l'homme du milieu ainsi que pendant des mises à jour de modules. Dans le fichier install.rdf du module déjà installé, updateURL doit être défini d'une des façons suivantes :

• L'updateURL utilise https, ou il n'y a aucun updateURL (ce qui par défaut correspond à <tt>addons.mozilla.org</tt> qui est en https)
• L'updateURL utilise http et l'entrée updateKey est spécifiée pour permettre de vérifier les données du manifeste d'installation.

Lorsque vous spécifier une updateKey dans <tt>install.rdf</tt>, vous devez inclure une signature numérique dans le manifeste de mise à jour ou l'information sera rejetée.

Dans le manifeste de mise à jour délivré par updateURL, updateLink doit être défini d'une des façons suivantes :

• Le lien updateLink vers un fichier XPI doit utiliser https
• Le lien updateLink peut utiliser http et vous devez inclure une entrée updateHash pour le fichier XPI en utilisant des algorithmes de hachage sha1, sha256, sha384 ou sha512.

Toutes les entrées du manifeste de mise à jour qui ne respectent pas ces deux exigences seront ignorées lors de la vérification des nouvelles versions.

Notez que les liens https vers des sites ayant des certificats invalides ou qui redirigent les requêtes vers des sites http échoueront également pour les cas <tt>update.rdf</tt> et updateLink

Hachages de mise à jour

Afin de vérifier l'intégrité du XPI téléchargé, vous devez fournir une entrée updateHash en même temps que le lien updateLink. Il s'agit d'un hachage généré à partir des données du fichier selon l'un des algorithmes gérés (sha1, sha256, sha384 et sha512). Dans Firefox 3, si la valeur updateLink n'est pas https le hachage doit être fait à l'aide d'un des membres de la famille d'algorithmes sha. L'algorithme de hachage utilisé est placé en préfixe de la chaîne de caractères et séparé par « : ».

  <em:updateHash>sha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6</em:updateHash>

Une erreur est affichée lorsque le hachage d'un fichier téléchargé diffère de son hachage spécifié.

Différents outils peuvent être utilisés pour générer des hachages :

De nombreuses variantes d'Unix fournissent sha1sum, sha256sum et ainsi de suite. Les utilisateurs de Windows peuvent utiliser HashTab pour une utilisation interactive (hors script de compilation). On pensera aussi aux outils GNU pour Windows (en dehors des classiques comme Cygwin), qui peuvent servir en utilisation non interactive :

sha1sum FICHIER

On peut encore citer md5deep, qui est multiplateforme :

sha1deep FICHIER

OpenSSL peut également générer des hachages :

openssl sha1 FICHIER

Sous Windows, HashTab peut servir d'extension au shell… un clic droit vous donnera des valeurs de hachage pour n'importe quel fichier.

De plus, un bug d'amélioration est ouvert pour ajouter une génération automatique de hachages pour les fichiers XPI à l'outil McCoy.

Enfin, tous les langages (de script) populaires offrent cette fonctionnalité, par exemple : Python, Perl: CPAN Digest, PHP.

Signature de manifestes de mise à jour

Si vous souhaitez servir votre RDF de mise à jour depuis un serveur http classique, les applications basées sur Gecko 1.9 auront besoin que vous signez numériquement le manifeste de mise à jour pour garantir que l'information n'est pas altérée entre le moment où vous l'avez créée et celui où les applications la récupèrent. L'outil McCoy doit être utilisé pour signer le RDF de mise à jour.

Les détails techniques du mécanisme de signature dépasse le cadre de ce document, toutefois les bases sont les suivantes :

Première étape — à faire une seule fois, avant de publier le module

L'objectif et d'ajouter updateKey au fichier <tt>install.rdf</tt>.

L'auteur du module crée une paire de clés cryptée RSA publique/privée.

La partie publique de la clé est encodée en DER et encodée en base 64, puis ajoutée au fichier <tt>install.rdf</tt> du module dans l'entrée updateKey.

Deuxième étape — à faire à chaque modification du fichier « update.rdf »

L'objectif est de définir la valeur de signature dans <tt>update.rdf</tt>.

Lorsque l'auteur crée le fichier rdf de mise à jour, un outil sert à le signer en utilisant la partie privée de la clé. Plus simplement, l'information de mise à jour est convertie en chaîne de caractères, puis hachée par un algorithme sha512 et le hachage obtenu est signé grâce à la clé privée. La donnée résultante est encodée en DER, puis encodée en base 64 pour être inclue dans <tt>update.rdf</tt> et comme une entrée de signature.

Débogage et résolution de problèmes

Les mécanismes de mise à jour peuvent envoyer des informations à la console, et afficher différentes informations pouvant vous aider à résoudre un problème. Pour activer l'affichage des messages :

1. Définissez la valeur de extensions.logging.enabled à true (en utilisant l'URL about:config).
2. Lancez Firefox en ligne de commande avec l'option -console

Si vous rencontrez des problèmes, examinez la sortie en console pour l'id de votre extension, et regardez si des erreurs ont été enregistrées.