Versionado, actualización y compatibilidad de extensiones

Hubo errores de script en esta página. Mientras los editores del sitio lo solucionan, puedes ver un contenido parcial debajo.

 

{{ Traducción("inglés", "Extension_Versioning%2C_Update_and_Compatibility", "en") }}

 

Las versiones de extensiones

Las extensiones deberán especificar su versión utilizando la herramienta para el formato de versión. En general son unas cadenas de caracteres cortadas por un punto, algunos ejemplos:

  • 2.0
  • 1.0b1
  • 3.0pre1
  • 5.0.1.2

{{ Note() }}

Como determinan la compatibilidad las aplicaciones

Al instalar extensiones/complementos las aplicaciones (programas) comprueban las entradas targetApplication en el archivo de instalación (install.rdf) de la extensión. La identificación (ID) de una entrada debe coincidir con la ID de la aplicación. Además, el número de versión de la aplicación debe encontrarse dentro del rango definido en minVersion y maxVersion.

Si la aplicación tiene una entrada targetApplication pero es para una versión incompatible, la aplicación intentará obtendrá información actualizada sobre su compatibilidad del archivo updateURL.

Si el archivo de instalación tiene entradas en targetPlatform, la plataforma utilizada para instalar la aplicación debe aparecer listada en ella o se cancelará la instalación.

{{ Fx_minversion_inline(3) }} En las aplicaciones basadas en Gecko 1.9 se puede utilizar una entrada targetApplication con una ID toolkit@mozilla.org; minVersion, y maxVersion que coincidan con la versión de la aplicación. Esto permitirá garantizar que la extensión se podrá instalar en cualquier aplicación basada en Toolkit.

Cancelar el control de compatibilidad

{{ Fx_minversion_inline(1.5) }} Para la evaluación de extensiones se puede hacer que la aplicación ignore los controles de compatibilidad durante la instalación. Lo único que hay que hacer es crear la preferencia extensions.checkCompatibility y darle valor False.

{{ Nota("Antes de la versión 1.5 de Firefox, se podía utilizar la preferencia app.extensions.version para que la aplicación ignorase su versión e instalar así extensiones de otra forma incompatibles.") }}

Elección de minVersion y maxVersion

minVersion y maxVersion deberían especificar las diferentes versiones de la aplicación que se han probado. No se debe introducir un valor maxVersion superior a la versión disponible ya que no se saben qué cambios podrían introducirse en su interfaz de programación (API) y de usuario. Con la actualización de compatibilidad no hace falta publicar una versión nueva completa de la extensión, sólo habrá que aumentar su maxVersion.

Generalmente, en maxVersion es permitido sustituir el número de versión secundario de la aplicación por un asterisco '*', por ejemplo: 2.0.0.* significaría que admite cualquier actualización secundaria de la versión 2 de la aplicación. Normalmente, la aplicación suele sugerir al autor de extensiones con qué parte de la versión conviene más hacer lo antedicho.

El asterisco '*' no representa una versión por sí mismo. En realidad el * representa un número infinitamente alto, por lo que es más sensato usarlo en maxVersion que en minVersion ya que no suele producir el efecto deseado.

Comprobación automática de actualización de extensiones

Periódicamente, las aplicaciones buscarán actualizaciones de las extensiones instaladas recuperando el archivo updateURL. La información recuperada puede servir para notificar al usuario que existe una actualización de la extensión e informar a la aplicación de las nuevas versiones compatibles con la extensión.

Actualizaciones de compatibilidad

Durante la comprobación automática de actualizaciones, las aplicaciones buscan nuevas versiones e información actualizada sobre la compatibilidad de la versión instalada de una extensión. Esto quiere decir que si el manifiesto de la actualización incluye una entrada para la versión actual de la extensión instalada y el targetApplication de la entrada especifica un maxVersion mayor, la aplicación utilizará este valor en lugar del especificado en el archivo install.rdf de la extensión. Esto puede causar que se activen extensiones que estaban desactivadas por ser incompatibles y que se instalen aquellas que normalmente no se instalarían.

Formato RDF de actualización

Si alberga uno mismo el archivo updateURL del complemento será necesario devolver la información de la versión en un formato RDF. Encontrará un ejemplo de manifiesto de actualización más abajo. Muestra información sobre dos versiones diferentes de la extensión para la 'id' foobar@developer.mozilla.org. Las versiones incluidas son 2.2 y 2.5, y cada una especifica la compatibilidad con las versiones de Firefox 1.5 a 2.0.0.*. Para la versión 2.2 se utiliza un enlace de actualización https mientras que para la 2.5 es un enlace regular http con un 'hash' para verificar el archivo recuperado.

Es importante recuperar correctamente la descripción RDF inicial del atributo 'about'. Permite saber de que complemento se trata:

  • Para una extensión: urn:mozilla:extension:<id>
  • Para un tema:

urn:mozilla:theme:<id>

  • Para cualquier otro tipo de complemento: urn:mozilla:item:<id>

En cualquiera de los ejemplos siguientes, la secuencia ordenada de las versiones dentro del elemento <RDF:Seq> es importante, con las versiones más nuevas después que las más antiguas. No hay que escribir todas las versiones intermedias si la última es suministrada.

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

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

  <!-- Esta forma de descripción incluye toda la
       información de actualización y compatibilidad
       para un simple complemento con la id
       foobar@developer.mozilla.org.
       Un único archivo RDF admite listados con
       información de varios complementos. -->
  <RDF:Description about="urn:mozilla:extension:foobar@developer.mozilla.org">
    <em:updates>
      <RDF:Seq>

        <!-- Cada "li" es una versión diferente
             del mismo complemento -->
        <RDF:li>
          <RDF:Description>
            <em:version>2.2</em:version> <!-- Esto
           es el número de la versión del complemento -->

            <!-- Un targetApplication para cada aplicación
                 compatible con el complemento -->
            <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>

                <!-- Dice donde hay que ir para descargar
                     esa versión del complemento -->
                <em:updateLink>https://www.mysite.com/foobar2.2.xpi</em:updateLink>

                <!-- Una página sobre lo nuevo
                     de esta actualización -->
                <em:updateInfoURL>http://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>http://www.mysite.com/foobar2.5.xpi</em:updateLink>
                <um:updateHash>sha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6</em:updateHash>
              </RDF:Description>
            </em:targetApplication>
          </RDF:Description>
        </RDF:li>

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

    <!-- Una firma sólo es necesaria en el caso de haber
         incluido un 'updateKey' en el archivo de
         instalación 'install.rdf' del complemento. -->
    <em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
                  ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
                  jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
                  BcVq13ad</em:signature>
  </RDF:Description>
</RDF:RDF>

Mucha gente prefiere este formato alternativo (se ha quitado mucha información en este ejemplo para ver mejor la estructura básica):

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

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

  <!-- Esta forma de descripción incluye toda la
       información de actualización y compatibilidad
       para un simple complemento con la id
       foobar@developer.mozilla.org.
       Un único archivo RDF admite listados con
       información de varios complementos. -->
  <RDF:Description about="urn:mozilla:extension:foobar@developer.mozilla.org">
    <em:updates>
      <RDF:Seq>
        <!-- El atributo de recurso apunta a una entrada
             de descripción 'about' que está más abajo.
             La uri actual puede ser cualquier cosa -->
        <RDF:li resource="urn:mozilla:extension:foobar@developer.mozilla.org:2.2"/>
        <RDF:li resource="urn:mozilla:extension:foobar@developer.mozilla.org:2.5"/>
      </RDF:Seq>
    </em:updates>
    <em:signature>MIGTMA0GCSqGSIb3DQEBBQUAA4GBAMO1O2gwSCCth1GwYMgscfaNakpN40PJfOWt
                  ub2HVdg8+OXMciF8d/9eVWm8eH/IxuxyZlmRZTs3O5tv9eWAY5uBCtqDf1WgTsGk
                  jrgZow1fITkZI7w0//C8eKdMLAtGueGfNs2IlTd5P/0KH/hf1rPc1wUqEqKCd4+L
                  BcVq13ad</em:signature>
  </RDF:Description>

  <!-- Esto es lo mismo que la descripción con
       'li' del ejemplo anterior -->
  <RDF:Description about="urn:mozilla:extension:foobar@developer.mozilla.org:2.2">
    <em:version>2.2</em:version>

    <!-- El contenido de esta parte se ha quitado -->

  </RDF:Description>
  <RDF:Description about="urn:mozilla:extension:foobar@developer.mozilla.org:2.5">
    <em:version>2.5</em:version>

    <!-- El contenido de esta parte se ha quitado -->

  </RDF:Description>
</RDF:RDF>

Facilitar detalles sobre las actualizaciones

{{ Fx_minversion_header(3) }}

En general

Podemos dar a conocer a los usuarios las novedades incluidas en la versión actualizada de nuestro complemento. El usuario al recibir una notificación de que hay una nueva versión puede ver de un vistazo esa información que contiene las mejoras y los arreglos de cualquier problema de seguridad.

Para que así sea, hay que agregar una entrada updateInfoURL en el manifiesto de actualización (ver el ejemplo de encima). La página de esta URL será recuperada y mostrada, al usuario, fuera del contexto normal de una página web por lo cual su contenido es mucho más "limpio", lo que significa que hay muy pocas opciones de formatos y que las secuencias de órdenes e imágenes no están permitidas. Como regla general, sólo se admite el uso de las etiquetas siguientes (cualquier otra cosa se ignorará):

  • Para cabeceras: h1, h2, h3
  • Para párrafos: p
  • Para listas: ul y ol.

Dentro de las listas se usará la etiqueta habitual 'li' para cada ítem de la lista.

Dentro de las etiquetas 'h1', 'h2', 'h3', 'p' y 'li' se utilizará:

  • Para texto en negrita: b o strong
  • Para texto en cursiva/itálica: i o em

La página de información recuperada debe ser completamente válida en XHTML, y entregada con el tipo MIME application/xhtml+xml.

Para poder personalizar el texto según la configuración regional/local del usuario se colocará %APP_LOCALE% en updateInfoURL para que esta información esté incluida en la URL, o bien cualquier otras cadenas de substitución admitidas por updateURL, pero no es tan funcional.

Lo que ve el usuario final

El contenido de updateInfoURL será mostrado al usuario en una pantalla del complemento, con una lista de todas las actualizaciones disponibles. Entonces, el usuario puede hacer clic en el botón "Mostrar la información" y la verá a la derecha. (El botón cambiará a "Esconder la información")

Image:Example_updateInfoURL2.PNG

Asegurando las actualizaciones

{{ Gecko_minversion_header(1.9) }} {{ Fx_minversion_header(3) }}

Gecko 1.9 has added additional requirements designed to protect users from man-in-the-middle attacks and the like during add-on updates. In the install.rdf of the already installed add-on updateURL must be specified in one of the following ways:

  • The updateURL uses https, or there is no updateURL at all (which defaults to addons.mozilla.org which is https)
  • The updateURL uses http and the updateKey entry is specified which will be used to verify the data in the update manifest.

Si se especifica una actualización de clave/firma (updateKey) en el archivo de instalación ( install.rdf), hay que incluir una firma digital en el manifiesto de actualización sino la información será rechazada.

In the update manifest delivered from the updateURL the updateLink must be specified in one of the following ways:

  • The updateLink to the XPI file must use https
  • The updateLink can use http and you must include an updateHash for the XPI file using sha1, sha256, sha384 or sha512 hash algorithms.

Any entries in the update manifest that do not meet one of those two requirements will be ignored when checking for new versions.

Note that https links to sites with invalid certificates or that redirect to http sites will fail for both the update.rdf and updateLink cases.

Los cifrados de actualización

Al fin de verificar la integridad del XPI descargado se puede proveer una entrada updateHash (cifrado de actualización) junto a updateLink. Este debe ser un cifrado generado desde los datos del fichero según un algoritmo admitido ('sha1', 'sha256', 'sha384' y 'sha512'). El algoritmo de cifrado utilizado debe anteponerse y separarse del cifrado en sí con ':'.

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

{{ Note("El valor updateHash, debe empezar con la cadena del algoritmo de cifrado, es un error común quitar ese prefijo al poner un valor nuevo en updateHash:\nsha1:78fc1d2887eda35b4ad2e3a0b60120ca271ce6e6") }}

Además el cifrado del archivo descargado y el cifrado especificado también deben coincidir, sino dará un error.

Varias herramientas permiten generar un cifrado:

Diversas variantes de Unix incluyen: sha1sum, sha256sum y demás. Los usuarios de Windows pueden utilizar HashTab para un uso interactivo (fuera de compilación). Tienen también las utilidades para Win (aparte de los clásicos como Cygwin), las cuales son buenas para un uso no-interactivo:

sha1sum ARCHIVO

Además de md5deep que es múlti-plataforma

sha1deep FILE

OpenSSL también genera cifrado:

openssl sha1 FILE

Para los usuarios de Windows, HashTab es una extensión shell... un simple clic da valores de cifrado para cualquier archivo.

Aquí hay además un bug de mejoras sobre como insertar a McCoy la generación automática de cifrado en archivos XPI.

Y todos los lenguajes (de programación) populares lo ofrecen, por ejemplo: Python, Perl: CPAN Digest, PHP

Firmar el manifiesto de actualización

{{ Gecko_minversion_header(1.9) }} {{ Fx_minversion_header(3) }}

If you wish to serve your update RDF over regular http, Gecko 1.9 based applications will require that you digitally sign the update manifest to ensure that it's information isn't tampered with between you creating it and applications retrieving it. The McCoy tool should be used to sign the update RDF.

The technical details of the signing mechanism are beyond the scope of this document however the basics are as follows:

The add-on author creates a public/private RSA cryptographic key pair.

The public part of the key is DER encoded and then base 64 encoded and added to the add-on's install.rdf as an updateKey entry.

When the author creates the update rdf file a tool is used to sign it using the private part of the key. Roughly speaking the update information is converted to a string, then hashed using a sha512 hashing algorithm and this hash is signed using the private key. The resultant data is DER encoded then base 64 encoded for inclusion in the update rdf as an em:signature entry.

 

 

{{ languages( { "en": "en/Extension_Versioning,_Update_and_Compatibility", "fr": "fr/Versions_d\'une_extension,_mise_\u00e0_jour_et_compatibilit\u00e9", "ja": "ja/Extension_Versioning,_Update_and_Compatibility", "ko": "ko/Extension_Versioning,_Update_and_Compatibility" } ) }}

Etiquetas y colaboradores del documento

Colaboradores de esta página: Nathymig, Wrongloop, Jseldon, StripTM, Mgjbot, RickieesES
Última actualización por: StripTM,