Configurer des échanges signés à l'aide de Web Packager

Découvrez comment diffuser des échanges signés (SXG) à l'aide de Web Packager.

Katie Hempenius

Un échange signé (SXG) est un mécanisme de diffusion qui permet d'authentifier l'origine d'une ressource indépendamment de la manière dont elle a été diffusée. Les instructions suivantes expliquent comment configurer des échanges signés à l'aide de Web Packager. Des instructions sont fournies pour les certificats autosignés et CanSignHttpExchanges.

Diffuser des SXG à l'aide d'un certificat autosigné

L'utilisation d'un certificat autosigné pour diffuser des SXG est principalement utilisée à des fins de démonstration et de test. Les SXG signés avec un certificat autosigné génèrent des messages d'erreur dans le navigateur lorsqu'ils sont utilisés en dehors des environnements de test et ne doivent pas être diffusés auprès des robots d'exploration.

Prérequis

Pour suivre ces instructions, vous devez avoir installé openssl et Go dans votre environnement de développement.

Générer un certificat autosigné

Cette section explique comment générer un certificat autosigné pouvant être utilisé avec des échanges signés.

Instructions

1. Générez une clé privée.

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

   La clé privée sera enregistrée sous le nom de fichier priv.key.

2. Créez une requête de signature de certificat (CSR).

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

   Une requête de signature de certificat est un bloc de texte encodé qui transmet les informations nécessaires pour demander un certificat à une autorité de certification(CA). Bien que vous ne demandiez pas de certificat à une autorité de certification, vous devez tout de même créer une demande de signature de certificat.

   La commande ci-dessus crée une requête de signature de certificat pour une organisation nommée Web Packager Demo avec le nom commun example.com. Le nom commun doit correspondre au nom de domaine complet du site contenant le contenu que vous souhaitez empaqueter en tant que SXG.

   Dans une configuration SXG de production, il s'agit d'un site dont vous êtes propriétaire. Toutefois, dans un environnement de test comme celui décrit dans ces instructions, il peut s'agir de n'importe quel site.

3. Créez un certificat avec l'extension 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")
   

   Cette commande utilise la clé privée et la CSR créées aux étapes 1 et 2 pour créer le fichier de certificat cert.pem. L'indicateur -extfile associe le certificat à l'extension de certificat CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 est l'identifiant de l'objet pour l'extension CanSignHttpExchanges). De plus, l'option -extfile définit également example.com comme nom alternatif du sujet.

   Si vous souhaitez connaître le contenu de cert.pem, vous pouvez l'afficher à l'aide de la commande suivante:

   openssl x509 -in cert.pem -noout -text
   

   Vous avez terminé de créer des clés privées et des certificats. Vous aurez besoin des fichiers priv.key et cert.pem dans la section suivante.

Configurer le serveur Web Packager pour les tests

Prérequis

1. Installez Web Packager.

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

2. Créez webpkgserver.

   cd webpackager/cmd/webpkgserver
   go build .
   

   webpkgserver est un binaire spécifique du projet Web Packager.

3. Vérifiez que webpkgserver a été correctement installé.

   ./webpkgserver --help
   

   Cette commande doit renvoyer des informations sur l'utilisation de webpkgserver. Si cela ne fonctionne pas, la première étape de dépannage consiste à vérifier que votre GOPATH est correctement configuré.

Instructions

1. Accédez au répertoire webpkgserver (vous vous y trouvez peut-être déjà).

   cd /path/to/cmd/webpkgserver
   

2. Créez un fichier webpkgsever.toml en copiant l'exemple.

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

   Ce fichier contient les options de configuration pour webpkgserver.

3. Ouvrez webpkgserver.toml avec l'éditeur de votre choix et apportez les modifications suivantes:

   • Remplacez la ligne #AllowTestCert = false par AllowTestCert = true.
   • Modifiez la ligne PEMFile = 'path/to/your.pem' pour refléter le chemin d'accès au certificat PEM, cert.pem, que vous avez créé. Ne modifiez pas la ligne mentionnant TLS.PEMFile. Il s'agit d'une autre option de configuration.
   • Modifiez la ligne KeyFile = 'priv.key' pour refléter le chemin d'accès de la clé privée, priv.key, que vous avez créée. Ne modifiez pas la ligne mentionnant TLS.KeyFile. Il s'agit d'une autre option de configuration.
   • Remplacez la ligne #CertURLBase = '/webpkg/cert' par CertURLBase = 'data:'. CertURLBase indique l'emplacement de diffusion du certificat SXG. Ces informations permettent de définir le paramètre cert-url dans l'en-tête Signature de l'élément SXG. Dans les environnements de production, CertURLBase est utilisé comme suit: CertURLBase = 'https://mysite.com/'. Toutefois, pour les tests locaux, CertURLBase = 'data:' peut être utilisé pour demander à webpkgserver d'utiliser une URL de données pour intégrer le certificat dans le champ cert-url. Pour les tests locaux, il s'agit du moyen le plus pratique de diffuser le certificat SXG.
   • Modifiez la ligne Domain = 'example.org' pour refléter le domaine pour lequel vous avez créé un certificat. Si vous avez suivi les instructions de cet article à la lettre, ce paramètre doit être remplacé par example.com. webpkgserver n'extrait que le contenu du domaine indiqué par webpkgserver.toml. Si vous essayez d'extraire des pages à partir d'un autre domaine sans mettre à jour webpkgserver.toml, le message d'erreur URL doesn't match the fetch targets s'affiche dans les journaux webpkgserver.

   Optional

   Si vous souhaitez activer ou désactiver le préchargement des sous-ressources, les options de configuration webpkgserver.toml suivantes sont pertinentes:

   • Pour que webpkgserver insère des directives de préchargement des sous-ressources de feuille de style et de script en tant que SXG, remplacez la ligne #PreloadCSS = false par PreloadCSS = true. Remplacez également la ligne #PreloadJS = false par PreloadJS = true.

     Au lieu d'utiliser cette option de configuration, vous pouvez ajouter manuellement des en-têtes Link: rel="preload" et des balises <link rel="preload"> au code HTML d'une page.

   • Par défaut, webpkgserver remplace les balises <link rel="preload"> existantes par les balises <link> équivalentes nécessaires pour extraire ce contenu au format SXG. webpkgserver définira les directives allowed-alt-sxg et header-integrity si nécessaire. Les auteurs HTML n'ont pas besoin de les ajouter manuellement. Pour remplacer ce comportement et conserver les préchargements non-SXG existants, remplacez #KeepNonSXGPreloads (default = false) par KeepNonSXGPreloads = true. N'oubliez pas que l'activation de cette option peut rendre l'échange signé inéligible au cache d'échanges signés Google, conformément aux exigences suivantes.

4. Démarrez webpkgserver.

   ./webpkgserver
   

   Si le serveur a démarré correctement, les messages de journal suivants doivent s'afficher : shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

   Vos messages de journal peuvent être légèrement différents. En particulier, le répertoire que webpkgserver utilise pour mettre en cache les certificats varie selon le système d'exploitation.

   Si vous ne voyez pas ces messages, la première étape de dépannage consiste à vérifier webpkgserver.toml.

   Si vous mettez à jour webpkgserver.toml, vous devez redémarrer webpkgserver.

5. Lancez Chrome à l'aide de la commande suivante : 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`

   Cette commande indique à Chrome d'ignorer les erreurs de certificat associées à cert.pem. Cela permet de tester les SXG à l'aide d'un certificat de test. Si Chrome est lancé sans cette commande, l'inspection de l'élément SXG dans les outils pour les développeurs affiche l'erreur Certificate verification error: ERR_CERT_INVALID.

   Remarque :

   Vous devrez peut-être ajuster cette commande pour refléter l'emplacement de Chrome sur votre ordinateur, ainsi que l'emplacement de cert.pem. Si vous avez bien effectué cette opération, un avertissement s'affiche sous la barre d'adresse. L'avertissement devrait ressembler à ceci: You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

   Si l'avertissement n'inclut pas de chaîne de hachage, vous n'avez pas indiqué correctement l'emplacement du certificat SXG.

6. Ouvrez l'onglet Network (Réseau) des outils pour les développeurs, puis accédez à l'URL suivante : http://localhost:8080/priv/doc/https://example.com.

   Une requête est envoyée à l'instance webpackager exécutée à http://localhost:8080 pour une SXG contenant le contenu de https://example.com. /priv/doc/ est le point de terminaison de l'API par défaut utilisé par webpackager.

   

   Les ressources suivantes sont listées dans l'onglet Network (Réseau) :

   • Ressource de type signed-exchange. Il s'agit de l'échange signé.
   • Ressource de type cert-chain+cbor. Il s'agit du certificat SXG. Les certificats SXG doivent utiliser le format application/cert-chain+cbor.
   • Ressource de type document. Il s'agit du contenu qui a été diffusé via SXG.

   Si vous ne voyez pas ces ressources, essayez de vider le cache du navigateur, puis de recharger http://localhost:8080/priv/doc/https://example.com.

   Cliquez sur l'onglet Aperçu pour en savoir plus sur l'échange signé et sa signature.

   

Diffuser des échanges signés à l'aide d'un certificat CanSignHttpExchanges

Les instructions de cette section expliquent comment diffuser des SXG à l'aide d'un certificat CanSignHttpExchanges. L'utilisation en production des SXG nécessite un certificat CanSignHttpExchanges.

Par souci de concision, nous partons du principe que vous comprenez les concepts abordés dans la section Configurer des échanges signés à l'aide d'un certificat autosigné.

Prérequis

• Vous disposez d'un certificat CanSignHttpExchanges. Cette page répertorie les autorités de certification qui proposent ce type de certificat.

• Si vous ne disposez pas de certificat, vous pouvez configurer votre webpkgserver pour qu'il récupère automatiquement les certificats auprès de votre autorité de certification. Vous pouvez suivre les instructions concernant ce qui doit être ajouté à webpkgserver.toml sur cette page.

• Bien que cela ne soit pas obligatoire, il est vivement recommandé d'exécuter webpkgserver derrière un serveur de bordure. Si vous n'utilisez pas de serveur de bord, vous devez configurer les options TLS.PEMFile et TLS.KeyFile dans webpkgserver.toml. Par défaut, webpkgserver s'exécute sur HTTP. Toutefois, les certificats SXG doivent être diffusés via HTTPS pour être considérés comme valides par le navigateur. La configuration de TLS.PEMFile et de TLS.KeyFile permet à webpkgserver d'utiliser HTTPS et donc de diffuser le certificat SXG directement dans le navigateur.

Instructions

1. Créez un fichier PEM en concatenant le certificat SXG de votre site, suivi du certificat CA de votre site. Pour en savoir plus, consultez cette page.

   PEM est un format de fichier couramment utilisé comme "conteneur" pour stocker plusieurs certificats.

2. Créez un nouveau fichier webpkgsever.toml en copiant l'exemple.

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

3. Ouvrez webpkgserver.toml avec l'éditeur de votre choix et apportez les modifications suivantes:

   • Modifiez la ligne PEMFile = cert.pem pour refléter l'emplacement du fichier PEM contenant votre chaîne de certificats complète.
   • Modifiez la ligne KeyFile = 'priv.key' pour refléter l'emplacement de la clé privée correspondant à votre fichier PEM.
   • Modifiez la ligne Domain = 'example.org' pour qu'elle reflète votre site.
   • (Facultatif) Pour que webpkgserver renouvelle automatiquement le certificat SXG tous les 90 jours (45 jours pour Google), configurez les options de la section [SXG.ACME] de webpkgserver.toml. Cette option ne s'applique qu'aux sites avec un compte DigiCert ou Google ACME configuré.

4. Configurez votre serveur Edge pour transférer le trafic vers l'instance webpkgserver.

   webpkgserver gère deux principaux types de requêtes: les requêtes pour les SXG (qui sont gérées par le point de terminaison /priv/doc/) et les requêtes pour le certificat SXG (qui sont gérées par le point de terminaison /webpkg/cert/). Les règles de réécriture d'URL pour chacun de ces types de requêtes varient légèrement. Pour en savoir plus, consultez la section Exécuter derrière le serveur de bord de l'interface utilisateur.

   Remarque :

   Par défaut, webpkgserver diffuse le certificat SXG sur /webpkg/cert/$CERT_HASH (par exemple, /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY). Pour générer $CERT_HASH, exécutez la commande suivante : shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =