Cómo configurar intercambios firmados con Web Packager

Obtén información para publicar intercambios firmados (SXG) con Web Packager.

Katie Hempenius
Katie Hempenius
X

Un intercambio firmado (SXG) es un mecanismo de entrega que permite autenticar el origen de un recurso, independientemente de cómo se entregó. En las siguientes instrucciones, se explica cómo configurar intercambios firmados con Web Packager. Se incluyen instrucciones para los certificados autofirmados y CanSignHttpExchanges.

Entrega archivos SXG con un certificado autofirmado

El uso de un certificado autofirmado para entregar SXG se usa principalmente con fines de demostración y prueba. Los SXG firmados con un certificado autofirmado generarán mensajes de error en el navegador cuando se usen fuera de los entornos de prueba y no se deben publicar a los rastreadores.

Requisitos previos

Para seguir estas instrucciones, deberás tener instalados openssl y Go en el entorno de desarrollo.

Cómo generar un certificado autofirmado

En esta sección, se explica cómo generar un certificado autofirmado que se pueda usar con intercambios firmados.

Instrucciones

  1. Genera una clave privada.

    openssl ecparam -out priv.key -name prime256v1 -genkey

    La clave privada se guardará como un archivo llamado priv.key.

  2. Crea una solicitud de firma de certificado (CSR).

    openssl req -new -sha256 -key priv.key -out cert.csr -subj '/O=Web Packager Demo/CN=example.com'

    Una solicitud de firma de certificado es un bloque de texto codificado que transmite la información necesaria para solicitar un certificado a una autoridad certificadora(AC). Aunque no solicitarás un certificado de una AC, es necesario crear una solicitud de firma de certificado.

    El comando anterior crea una solicitud de firma de certificado para una organización llamada Web Packager Demo que tiene el nombre común example.com. El nombre común debe ser el nombre de dominio completamente calificado del sitio que incluye el contenido que deseas empaquetar como SXG.

    En una configuración de producción de SXG, este sería un sitio que te pertenece. Sin embargo, en un entorno de pruebas como el que se describe en estas instrucciones, puede ser cualquier sitio.

  3. Crea un certificado que tenga la extensión CanSignHttpExchanges.

    openssl x509 -req -days 90 -in cert.csr -signkey priv.key -out cert.pem -extfile <(echo -e "1.3.6.1.4.1.11129.2.1.22 = ASN1:NULL\nsubjectAltName=DNS:example.com")

    Este comando utiliza la clave privada y la CSR creada en los pasos 1 y 2 para crear el archivo de certificado cert.pem. La marca -extfile asocia el certificado con la extensión de certificado CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 es el identificador del objeto de la extensión CanSignHttpExchanges). Además, la marca -extfile también define example.com como un nombre alternativo del sujeto.

    Si te interesa el contenido de cert.pem, puedes verlo con el siguiente comando:

    openssl x509 -in cert.pem -noout -text

    Terminaste de crear claves privadas y certificados. Necesitarás los archivos priv.key y cert.pem en la siguiente sección.

Configura el servidor de Web Packager para realizar pruebas

Requisitos previos

  1. Instala Web Packager.

    git clone https://github.com/google/webpackager.git

  2. Compila webpkgserver.

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver es un objeto binario específico dentro del proyecto Web Packager.

  3. Verifica que webpkgserver se haya instalado correctamente.

    ./webpkgserver --help

    Este comando debe mostrar información sobre el uso de webpkgserver. Si esto no funciona, un primer paso para solucionar el problema es verificar que tu GOPATH esté configurado de forma correcta.

Instrucciones

  1. Navega al directorio webpkgserver (es posible que ya te encuentres en este directorio).

    cd /path/to/cmd/webpkgserver

  2. Copia el ejemplo para crear un archivo webpkgsever.toml.

    cp ./webpkgserver.example.toml ./webpkgserver.toml

    Este archivo contiene las opciones de configuración de webpkgserver.

  3. Abre webpkgserver.toml con el editor que prefieras y realiza los siguientes cambios:

    • Cambia la línea #AllowTestCert = false a AllowTestCert = true.
    • Cambia la línea PEMFile = 'path/to/your.pem' para reflejar la ruta al certificado PEM, cert.pem, que creaste. No cambies la línea en la que se menciona TLS.PEMFile, ya que esta es una opción de configuración diferente.
    • Cambia la línea KeyFile = 'priv.key' para reflejar la ruta de acceso de la clave privada, priv.key, que creaste. No cambies la línea que menciona TLS.KeyFile, ya que esta es una opción de configuración diferente.
    • Cambia la línea #CertURLBase = '/webpkg/cert' a CertURLBase = 'data:'. CertURLBase indica la ubicación de entrega del certificado SXG. Esta información se usa para establecer el parámetro cert-url en el encabezado Signature de SXG. En entornos de producción, CertURLBase se usa de la siguiente manera: CertURLBase = 'https://mysite.com/'. Sin embargo, para las pruebas locales, se puede usar CertURLBase = 'data:' a fin de indicarle a webpkgserver que use una URL de datos para intercalar el certificado en el campo cert-url. Para las pruebas locales, esta es la forma más conveniente de entregar el certificado SXG.
    • Cambia la línea Domain = 'example.org' a fin de reflejar el dominio para el que creaste un certificado. Si seguiste al pie de la letra las instrucciones de este artículo, se debe cambiar a example.com. webpkgserver solo recuperará contenido del dominio que indique webpkgserver.toml. Si intentas recuperar páginas de un dominio diferente sin actualizar webpkgserver.toml, los registros webpkgserver mostrarán el mensaje de error URL doesn't match the fetch targets.

    Opcional

    Si deseas habilitar o inhabilitar la precarga de los subrecursos, las siguientes opciones de configuración de webpkgserver.toml son relevantes:

    • Para que webpkgserver inserte directivas para la precarga de hojas de estilo y subrecursos de secuencias de comandos como SXG, cambia la línea #PreloadCSS = false a PreloadCSS = true. Además, cambia la línea #PreloadJS = false a PreloadJS = true.

      Como alternativa al uso de esta opción de configuración, puedes agregar de forma manual encabezados Link: rel="preload" y etiquetas <link rel="preload"> al código HTML de una página.

    • De forma predeterminada, webpkgserver reemplaza las etiquetas <link rel="preload"> existentes con las etiquetas <link> equivalentes necesarias para recuperar este contenido como SXG. De esa manera, webpkgserver establecerá las directivas allowed-alt-sxg y header-integrity según sea necesario. Los autores de HTML no necesitan agregarlas de forma manual. Para anular este comportamiento y mantener las precargas existentes que no sean de SXG, cambia #KeepNonSXGPreloads (default = false) a KeepNonSXGPreloads = true. Ten en cuenta que habilitar esta opción puede hacer que el SXG no sea apto para la caché de SXG de Google según estos requisitos.

  4. Inicia webpkgserver.

    ./webpkgserver

    Si el servidor se inició correctamente, deberías ver los siguientes mensajes de registro: shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

    Es posible que los mensajes de registro se vean ligeramente diferentes. En particular, el directorio que usa webpkgserver para almacenar certificados en caché varía según el sistema operativo.

    Si no ves estos mensajes, un primer paso para solucionar el problema es volver a verificar webpkgserver.toml.

    Si actualizas webpkgserver.toml, debes reiniciar webpkgserver.

  5. Inicia Chrome con el siguiente comando: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ --user-data-dir=/tmp/udd \ --ignore-certificate-errors-spki-list=`openssl x509 -noout -pubkey -in cert.pem | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64`

    Este comando le indica a Chrome que ignore los errores de certificado asociados con cert.pem. Esto permite probar los SXG con un certificado de prueba. Si Chrome se inicia sin este comando, cuando inspeccionas el SXG en las Herramientas para desarrolladores, se mostrará el error Certificate verification error: ERR_CERT_INVALID.

    Nota:

    Es posible que debas ajustar este comando para que refleje la ubicación de Chrome en tu máquina, así como la ubicación de cert.pem. Si lo hiciste de manera correcta, deberías ver una advertencia debajo de la barra de direcciones. La advertencia debería ser similar a la siguiente: You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

    Si la advertencia no incluye una cadena de hash, no indicaste de forma correcta la ubicación del certificado SXG.

  6. Abre la pestaña Red de Herramientas para desarrolladores y, luego, visita la siguiente URL: http://localhost:8080/priv/doc/https://example.com.

    Esto crea una solicitud a la instancia webpackager que se ejecuta en http://localhost:8080 para un SXG con el contenido de https://example.com. /priv/doc/ es el extremo de API predeterminado que usa webpackager.

    Captura de pantalla de la pestaña Network de Herramientas para desarrolladores donde se muestra un SXG y su certificado.

    Los siguientes recursos se enumeran en la pestaña Red:

    • Un recurso con el tipo signed-exchange Este es el SXG.
    • Un recurso con el tipo cert-chain+cbor Este es el certificado SXG. Los certificados SXG deben usar el formato application/cert-chain+cbor.
    • Un recurso con el tipo document Este es el contenido que se publicó a través de SXG.

    Si no ves estos recursos, intenta borrar la caché del navegador y, luego, vuelve a cargar http://localhost:8080/priv/doc/https://example.com.

    Haz clic en la pestaña Vista previa para ver más información sobre el intercambio firmado y su firma.

    Captura de pantalla de la pestaña Vista previa en la que se muestra un SXG

Entrega intercambios firmados con un certificado CanSignHttpExchanges

En las instrucciones de esta sección, se explica cómo entregar SXG mediante un certificado CanSignHttpExchanges. El uso de producción de SXG requiere un certificado CanSignHttpExchanges.

Para ser más breves, estas instrucciones se escriben con la suposición de que comprendes los conceptos analizados en la sección Cómo configurar intercambios firmados con un certificado autofirmado.

Requisitos previos

  • Tienes un certificado de CanSignHttpExchanges. En esta página, se enumeran las AC que ofrecen este tipo de certificado.

  • Si no tienes un certificado, puedes configurar webpkgserver para que recupere automáticamente los certificados de tu AC. Puedes seguir las instrucciones del contenido de webpkgserver.toml en esta página.

  • Aunque no es un requisito, te recomendamos que ejecutes webpkgserver detrás de un servidor perimetral. Si no usas un servidor perimetral, deberás configurar las opciones TLS.PEMFile y TLS.KeyFile en webpkgserver.toml. De forma predeterminada, webpkgserver se ejecuta en HTTP. Sin embargo, los certificados SXG deben entregarse a través de HTTPS para que el navegador los considere válidos. La configuración de TLS.PEMFile y TLS.KeyFile permite que webpkgserver use HTTPS y, por lo tanto, entregue el certificado SXG directamente en el navegador.

Instrucciones

  1. Crea un archivo PEM. Para ello, concatena el certificado SXG del sitio seguido del certificado de la AC del sitio. Puedes encontrar más instrucciones sobre este tema aquí.

    PEM es un formato de archivo que se usa, por lo general, como "contenedor" para almacenar varios certificados.

  2. Copia el ejemplo para crear un archivo webpkgsever.toml nuevo.

    cp ./webpkgserver.example.toml ./webpkgserver.toml

  3. Abre webpkgserver.toml con el editor que prefieras y realiza los siguientes cambios:

    • Cambia la línea PEMFile = cert.pem para reflejar la ubicación del archivo PEM que contiene tu cadena de certificados completa.
    • Cambia la línea KeyFile = 'priv.key' para reflejar la ubicación de la clave privada correspondiente a tu archivo PEM.
    • Cambia la línea Domain = 'example.org' para que refleje tu sitio.
    • Para que webpkgserver renueve automáticamente el certificado SXG cada 90 días (45 días para Google), configura las opciones en la sección [SXG.ACME] de webpkgserver.toml. Esta opción solo se aplica a sitios con una cuenta de DigiCert o una cuenta de ACME de Google.

  4. Configura tu servidor perimetral para reenviar tráfico a la instancia webpkgserver.

    Hay dos tipos principales de solicitudes que maneja webpkgserver: solicitudes para SXG (que entrega el extremo /priv/doc/) y solicitudes para el certificado SXG (que entrega el extremo /webpkg/cert/). Las reglas de reescritura de URL para cada uno de estos tipos de solicitud varían un poco. Para obtener más información, consulta Ejecuta detrás del servidor perimetral de frontend.

    Nota:

    De forma predeterminada, webpkgserver entrega el certificado SXG en /webpkg/cert/$CERT_HASH, por ejemplo, /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY. Para generar $CERT_HASH, ejecuta el siguiente comando: shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =