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 haya entregado. En las siguientes instrucciones, se explica cómo configurar intercambios firmados con Web Packager. Se incluyen instrucciones para los certificados autofirmados y CanSignHttpExchanges.

Publica 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 entregar a los rastreadores.

Requisitos previos

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

Genera un certificado autofirmado

En esta sección, se explica cómo generar un certificado autofirmado que se puede 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 a 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 un entorno de producción de SXG, este sería un sitio de tu propiedad. Sin embargo, en un entorno de pruebas como el que se describe en estas instrucciones, puede ser cualquier sitio.

  3. Crea un certificado con 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")

    En este comando, se usa 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 de objeto para la extensión CanSignHttpExchanges). Además, la marca -extfile también define example.com como un Nombre alternativo del asunto.

    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 las 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 debería mostrar información sobre el uso de webpkgserver. Si esto no funciona, un buen primer paso para solucionar problemas es verificar que tu GOPATH esté configurado correctamente.

Instrucciones

  1. Navega al directorio webpkgserver (es posible que ya estés 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 elijas y realiza los siguientes cambios:

    • Cambia la línea #AllowTestCert = false a AllowTestCert = true.
    • Cambia la línea PEMFile = 'path/to/your.pem' para que refleje la ruta de acceso al certificado PEM, cert.pem, que creaste. No cambies la línea que menciona TLS.PEMFile, ya que 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 publicación del certificado de SXG. Esta información se usa para establecer el parámetro cert-url en el encabezado Signature del SXG. En los entornos de producción, CertURLBase se usa de la siguiente manera: CertURLBase = 'https://mysite.com/'. Sin embargo, en las pruebas locales, se puede usar CertURLBase = 'data:' para indicar 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' de modo que refleje el dominio para el que creaste un certificado. Si seguiste al pie de la letra las instrucciones de este artículo, debería cambiarse 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 de webpkgserver mostrarán el mensaje de error URL doesn't match the fetch targets.

    Opcional

    Si quieres habilitar o inhabilitar la carga previa de subrecursos, las siguientes opciones de configuración de webpkgserver.toml son relevantes:

    • Si quieres tener directivas de inserción webpkgserver para precargar subrecursos de hojas de estilo y 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. Al hacerlo, 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 cargas previas existentes que no son 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 un poco diferentes. En particular, el directorio que usa webpkgserver para almacenar en caché los certificados varía según el sistema operativo.

    Si no ves estos mensajes, un buen 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 SXG con un certificado de prueba. Si Chrome se inicia sin este comando, la inspección de la SXG en DevTools 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 correctamente, 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, significa que no indicaste correctamente la ubicación del certificado SXG.

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

    Esto genera 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 Red de DevTools que muestra un SXG y su certificado.

    En la pestaña Red, se enumeran los siguientes recursos:

    • Un recurso con el tipo signed-exchange. Este es el SXG.
    • Un recurso con el tipo cert-chain+cbor Este es el certificado de SXG. Los certificados de 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 que muestra un SXG

Publica intercambios firmados con un certificado CanSignHttpExchanges

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

Para abreviar, estas instrucciones se escribieron con la suposición de que comprendes los conceptos que se analizan en la sección Configura 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 tu webpkgserver para que recupere automáticamente certificados de tu AC. Puedes seguir las instrucciones de lo que se incluye en webpkgserver.toml en esta página.

  • Aunque no es un requisito, se recomienda 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 de SXG deben entregarse a través de HTTPS para que el navegador los considere válidos. Configurar TLS.PEMFile y TLS.KeyFile permite que webpkgserver use HTTPS y, por lo tanto, entregue el certificado SXG directamente al navegador.

Instrucciones

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

    PEM es un formato de archivo que se usa comúnmente 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 que refleje la ubicación del archivo PEM que contiene la cadena de certificados completa.
    • Cambia la línea KeyFile = 'priv.key' para que refleje la ubicación de la clave privada correspondiente a tu archivo PEM.
    • Cambia la línea Domain = 'example.org' para que refleje tu sitio.
    • Opcional: 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 los sitios con una cuenta de ACME de Google o DigiCert configurada.

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

    webpkgserver controla dos tipos principales de solicitudes: solicitudes de SXG (que entrega el extremo /priv/doc/) y solicitudes del certificado de SXG (que entrega el extremo /webpkg/cert/). Las reglas de reescritura de URL para cada uno de estos tipos de solicitudes varían ligeramente. Para obtener más información, consulta Ejecución detrás del servidor de borde del 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 =