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 distribution qui permet d'authentifier l'origine d'une ressource indépendamment de la manière dont elle a été fournie. Les instructions suivantes expliquent comment configurer des échanges signés à l'aide de Web Packager. Des instructions sont incluses pour les certificats autosignés et CanSignHttpExchanges.

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

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

Prérequis

Pour suivre ces instructions, vous devez installer 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 dans un fichier nommé 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 fournit les informations nécessaires pour demander un certificat à une autorité de certification. Bien que vous ne demandiez pas de certificat à une autorité de certification, vous devez tout de même créer une requête 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 et dont le nom commun est example.com. Le nom commun doit être le nom de domaine complet du site sur lequel figure le contenu que vous souhaitez empaqueter en tant qu'échanges signés.

   Dans une configuration de production SXG, il s'agit d'un site qui vous appartient. Toutefois, dans un environnement de test tel que celui décrit dans ces instructions, il peut s'agir de n'importe quel site.

3. Créez un certificat portant 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 requête de signature de certificat créées aux étapes 1 et 2 pour créer le fichier de certificat cert.pem. L'option -extfile associe le certificat à l'extension de certificat CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 est l'identifiant d'objet de l'extension CanSignHttpExchanges). En outre, l'option -extfile définit également example.com comme Autre nom de l'objet.

   Si vous êtes curieux de connaître le contenu de cert.pem, vous pouvez les 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 à des fins de test

Prérequis

1. Installez Web Packager.

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

2. Compilez webpkgserver.

   cd webpackager/cmd/webpkgserver
   go build .
   

   webpkgserver est un binaire spécifique dans le projet Web Packager.

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

   ./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ée.

Instructions

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

   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 option de configuration différente.
   • Modifiez la ligne KeyFile = 'priv.key' pour refléter le chemin d'accès à la clé privée priv.key que vous avez créée. Ne modifiez pas la ligne mentionnant TLS.KeyFile. Il s'agit d'une option de configuration différente.
   • Remplacez la ligne #CertURLBase = '/webpkg/cert' par CertURLBase = 'data:'. CertURLBase indique l'emplacement de diffusion du certificat d'échange signé. Ces informations sont utilisées pour définir le paramètre cert-url dans l'en-tête Signature de l'échange signé. Dans les environnements de production, CertURLBase est utilisé comme suit: CertURLBase = 'https://mysite.com/'. Toutefois, pour les tests en local, CertURLBase = 'data:' peut être utilisé pour demander à webpkgserver d'utiliser une URL de données afin d'intégrer le certificat dans le champ cert-url. Pour les tests en local, il s'agit du moyen le plus pratique de transmettre le certificat SXG.
   • Modifiez la ligne Domain = 'example.org' afin de refléter le domaine pour lequel vous avez créé un certificat. Si vous avez suivi les instructions de cet article telles quelles, vous devez le remplacer par example.com. webpkgserver ne récupère que le contenu du domaine indiqué par webpkgserver.toml. Si vous essayez de récupérer des pages d'un autre domaine sans mettre à jour webpkgserver.toml, les journaux webpkgserver affichent le message d'erreur URL doesn't match the fetch targets.

   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 instructions de préchargement de la feuille de style et des sous-ressources de script en tant qu'échanges signés, remplacez la ligne #PreloadCSS = false par PreloadCSS = true. De plus, remplacez 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 récupérer ce contenu en tant qu'échanges signés. Ainsi, webpkgserver définit les instructions allowed-alt-sxg et header-integrity selon les besoins. Les auteurs HTML n'ont pas besoin de les ajouter manuellement. Pour ignorer ce comportement et conserver les préchargements non SXG existants, remplacez #KeepNonSXGPreloads (default = false) par KeepNonSXGPreloads = true. Gardez à l'esprit que l'activation de cette option peut rendre le SXG inéligible au cache SXG Google conformément à ces exigences.

4. Démarrez webpkgserver.

   ./webpkgserver
   

   Si le serveur a bien démarré, 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

   L'apparence de vos messages de journal peut être légèrement différente. En particulier, le répertoire utilisé par webpkgserver pour mettre en cache les certificats varie selon le système d'exploitation.

   Si vous ne voyez pas ces messages, nous vous conseillons de commencer par 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 échanges signés à l'aide d'un certificat de test. Si Chrome est lancé sans cette commande, l'inspection de l'échange signé dans les outils de développement 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 l'avez correctement fait, un avertissement doit s'afficher sous la barre d'adresse. L'avertissement doit se présenter comme suit: 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, cela signifie que vous n'avez pas correctement indiqué l'emplacement du certificat SXG.

6. Ouvrez l'onglet Réseau des outils de développement, puis accédez à l'URL suivante : http://localhost:8080/priv/doc/https://example.com.

   Une requête est alors envoyée à l'instance webpackager exécutée à l'adresse http://localhost:8080 pour un échange signé 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 répertoriées dans l'onglet Network (Réseau) :

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

   Si ces ressources ne s'affichent pas, essayez de vider le cache du navigateur, puis actualisez http://localhost:8080/priv/doc/https://example.com.

   Cliquez sur l'onglet Aperçu pour afficher plus d'informations 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 échanges signés à l'aide d'un certificat CanSignHttpExchanges. L'utilisation en production d'échanges signés nécessite un certificat CanSignHttpExchanges.

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

Prérequis

• Vous possédez un certificat CanSignHttpExchanges. Cette page liste les autorités de certification qui proposent ce type de certificat.

• Si vous ne possédez pas de certificat, vous pouvez configurer votre webpkgserver pour qu'il récupère automatiquement les certificats de votre autorité de certification. Vous pouvez suivre les instructions concernant la saisie de webpkgserver.toml sur cette page.

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

Instructions

1. Créez un fichier PEM en concaténant le certificat SXG de votre site, suivi du certificat CA de votre site. Pour en savoir plus, cliquez ici.

   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 dans 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 corresponde à votre site.
   • (Facultatif) Pour que webpkgserver renouvelle automatiquement le certificat SXG tous les 90 jours (45 jours pour Google), configurez les options dans la section [SXG.ACME] de webpkgserver.toml. Cette option ne s'applique qu'aux sites disposant d'un compte DigiCert ou Google ACME.

4. Configurez votre serveur de périphérie pour qu'il transfère le trafic vers l'instance webpkgserver.

   Il existe deux principaux types de requêtes traitées par webpkgserver: les requêtes pour les échanges signés (qui sont diffusés par le point de terminaison /priv/doc/) et les requêtes pour le certificat SXG (qui sont diffusé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écution derrière un serveur de périphérie frontal.

   Remarque :

   Par défaut, webpkgserver diffuse le certificat SXG à l'adresse /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 =