웹 패키지 도구를 사용하여 서명된 교환을 설정하는 방법

웹 패키지 도구를 사용하여 서명된 교환 (SXG)을 제공하는 방법을 알아보세요.

Katie Hempenius
Katie Hempenius
X

서명된 교환 (SXG)은 전송 방법과는 별개로 리소스의 출처를 인증할 수 있는 전송 메커니즘입니다. 다음 안내에서는 웹 패키지 도구를 사용하여 서명된 교환을 설정하는 방법을 설명합니다. 자체 서명 인증서와 CanSignHttpExchanges 인증서 모두에 관한 안내가 포함되어 있습니다.

자체 서명 인증서를 사용하여 SXG 제공

자체 서명된 인증서를 사용하여 SXG를 제공하는 것은 주로 데모 및 테스트 목적으로 사용됩니다. 자체 서명 인증서로 서명된 SXG는 테스트 환경 외부에서 사용할 때 브라우저에 오류 메시지를 생성하므로 크롤러에 제공해서는 안 됩니다.

기본 요건

이 안내를 따르려면 개발 환경에 openssl 및 Go가 설치되어 있어야 합니다.

자체 서명 인증서 생성

이 섹션에서는 서명된 교환에 사용할 수 있는 자체 서명 인증서를 생성하는 방법을 설명합니다.

안내

  1. 비공개 키를 생성합니다.

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

    비공개 키는 priv.key이라는 파일로 저장됩니다.

  2. 인증서 서명 요청 (CSR)을 만듭니다.

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

    인증서 서명 요청은 인증 기관(CA)으로부터 인증서를 요청하는 데 필요한 정보를 전달하는 인코딩된 텍스트 블록입니다. CA에서 인증서를 요청하지 않더라도 인증서 서명 요청을 만들어야 합니다.

    위 명령어는 일반 이름 example.com를 사용하는 Web Packager Demo이라는 조직에 대한 인증서 서명 요청을 만듭니다. 일반 이름은 SXG로 패키징하려는 콘텐츠가 포함된 사이트의 정규화된 도메인 이름이어야 합니다.

    프로덕션 SXG 설정에서는 내가 소유한 사이트가 됩니다. 그러나 이 안내에서 설명하는 것과 같은 테스트 환경에서는 어떤 사이트든 가능합니다.

  3. 확장자가 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")

    이 명령어는 1단계와 2단계에서 만든 비공개 키와 CSR을 사용하여 인증서 파일 cert.pem를 만듭니다. -extfile 플래그는 인증서를 CanSignHttpExchanges 인증서 확장 프로그램과 연결합니다. 1.3.6.1.4.1.11129.2.1.22는 CanSignHttpExchanges 확장 프로그램의 객체 식별자입니다. 또한 -extfile 플래그는 example.com를 주체 대체 이름으로 정의합니다.

    cert.pem의 콘텐츠가 궁금한 경우 다음 명령어를 사용하여 확인할 수 있습니다.

    openssl x509 -in cert.pem -noout -text

    비공개 키와 인증서 만들기가 완료되었습니다. 다음 섹션에서는 priv.key 및 cert.pem 파일이 필요합니다.

테스트를 위한 웹 패키지 도구 서버 설정

기본 요건

  1. 웹 패키지 도구를 설치합니다.

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

  2. webpkgserver를 빌드합니다.

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver는 웹 패키지 도구 프로젝트 내의 특정 바이너리입니다.

  3. webpkgserver가 올바르게 설치되었는지 확인합니다.

    ./webpkgserver --help

    이 명령어는 webpkgserver 사용에 관한 정보를 반환해야 합니다. 그래도 문제가 해결되지 않으면 첫 번째 문제 해결 단계로 GOPATH가 올바르게 구성되었는지 확인합니다.

안내

  1. webpkgserver 디렉터리로 이동합니다 (이미 이 디렉터리에 있을 수 있음).

    cd /path/to/cmd/webpkgserver

  2. 예를 복사하여 webpkgsever.toml 파일을 만듭니다.

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

    이 파일에는 webpkgserver의 구성 옵션이 포함되어 있습니다.

  3. 원하는 편집기로 webpkgserver.toml를 열고 다음과 같이 변경합니다.

    • #AllowTestCert = false 줄을 AllowTestCert = true로 변경합니다.
    • 생성한 PEM 인증서 cert.pem의 경로를 반영하도록 PEMFile = 'path/to/your.pem' 줄을 변경합니다. TLS.PEMFile를 언급하는 줄을 변경하지 마세요. 이는 다른 구성 옵션입니다.
    • 생성한 비공개 키 priv.key의 경로를 반영하도록 KeyFile = 'priv.key' 줄을 변경합니다. TLS.KeyFile을 언급하는 줄을 변경하지 마세요. 이는 다른 구성 옵션입니다.
    • #CertURLBase = '/webpkg/cert' 줄을 CertURLBase = 'data:'로 변경합니다. CertURLBase는 SXG 인증서의 제공 위치를 나타냅니다. 이 정보는 SXG의 Signature 헤더에 cert-url 매개변수를 설정하는 데 사용됩니다. 프로덕션 환경에서는 CertURLBase가 CertURLBase = 'https://mysite.com/'과 같이 사용됩니다. 하지만 로컬 테스트의 경우 CertURLBase = 'data:'를 사용하여 webpkgserver에 데이터 URL을 사용하여 cert-url 필드에 인증서를 인라인하도록 지시할 수 있습니다. 이는 로컬 테스트에서 SXG 인증서를 제공하는 가장 편리한 방법입니다.
    • 인증서를 만든 도메인을 반영하도록 Domain = 'example.org' 줄을 변경합니다. 이 문서의 안내를 그대로 따랐다면 example.com로 변경해야 합니다. webpkgserver는 webpkgserver.toml로 표시된 도메인에서만 콘텐츠를 가져옵니다. webpkgserver.toml를 업데이트하지 않고 다른 도메인에서 페이지를 가져오려고 하면 webpkgserver 로그에 URL doesn't match the fetch targets 오류 메시지가 표시됩니다.

    Optional

    하위 리소스 미리 로드를 사용 설정하거나 사용 중지하려면 다음 webpkgserver.toml 구성 옵션이 적합합니다.

    • 스타일시트와 스크립트 하위 리소스를 SXG로 미리 로드하기 위한 webpkgserver 삽입 지시어를 사용하려면 #PreloadCSS = false 줄을 PreloadCSS = true로 변경합니다. 또한 #PreloadJS = false 줄을 PreloadJS = true로 변경합니다.

      이 구성 옵션을 사용하는 대신 페이지의 HTML에 Link: rel="preload" 헤더 및 <link rel="preload"> 태그를 수동으로 추가할 수 있습니다.

    • 기본적으로 webpkgserver는 기존 <link rel="preload"> 태그를 이 콘텐츠를 SXG로 가져오는 데 필요한 상응하는 <link> 태그로 바꿉니다. 이렇게 하면 webpkgserver가 필요에 따라 allowed-alt-sxg 및 header-integrity 지시어를 설정합니다. HTML 작성자가 이를 직접 추가할 필요가 없습니다. 이 동작을 재정의하고 기존 비 SXG 미리 로드를 유지하려면 #KeepNonSXGPreloads (default = false)를 KeepNonSXGPreloads = true로 변경합니다. 이 옵션을 사용 설정하면 이러한 요구사항에 따라 SXG에서 Google SXG 캐시를 사용하지 못할 수도 있습니다.

  4. webpkgserver를 시작합니다.

    ./webpkgserver

    서버가 성공적으로 시작되면 다음과 같은 로그 메시지가 표시됩니다. shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

    로그 메시지는 약간 다르게 표시될 수 있습니다. 특히 webpkgserver에서 인증서를 캐시하는 데 사용하는 디렉터리는 운영체제에 따라 다릅니다.

    이러한 메시지가 표시되지 않으면 우선 문제 해결 단계로 webpkgserver.toml를 다시 확인해 보는 것이 좋습니다.

    webpkgserver.toml를 업데이트하면 webpkgserver를 다시 시작해야 합니다.

  5. 다음 명령어를 사용하여 Chrome을 실행합니다. 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`

    이 명령어는 Chrome이 cert.pem와 관련된 인증서 오류를 무시하도록 지시합니다. 이렇게 하면 테스트 인증서를 사용하여 SXG를 테스트할 수 있습니다. 이 명령어 없이 Chrome을 실행하면 DevTools에서 SXG를 검사하면 Certificate verification error: ERR_CERT_INVALID 오류가 표시됩니다.

    참고:

    머신에 있는 Chrome의 위치와 cert.pem의 위치를 반영하도록 이 명령어를 조정해야 할 수 있습니다. 이 작업을 올바르게 수행하면 주소 표시줄 아래에 경고가 표시됩니다. 경고는 다음과 비슷하게 표시됩니다. You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

    경고에 해시 문자열이 포함되지 않으면 SXG 인증서의 위치가 올바르게 표시되지 않은 것입니다.

  6. DevTools 네트워크 탭을 열고 URL http://localhost:8080/priv/doc/https://example.com로 이동합니다.

    이렇게 하면 https://example.com의 콘텐츠가 포함된 SXG의 경우 http://localhost:8080에서 실행 중인 webpackager 인스턴스에 요청이 전송됩니다. /priv/doc/는 webpackager에서 사용하는 기본 API 엔드포인트입니다.

    SXG와 인증서를 보여주는 DevTools Network 탭의 스크린샷

    다음 리소스는 네트워크 탭에 나열됩니다.

    • signed-exchange 유형의 리소스 여기가 SXG예요.
    • cert-chain+cbor 유형의 리소스 SXG 인증서입니다. SXG 인증서는 application/cert-chain+cbor 형식을 사용해야 합니다.
    • document 유형의 리소스 SXG를 통해 전송된 콘텐츠입니다.

    이러한 리소스가 표시되지 않으면 브라우저 캐시를 지운 다음 http://localhost:8080/priv/doc/https://example.com를 새로고침해 보세요.

    Preview 탭을 클릭하여 서명된 교환과 서명에 대한 자세한 내용을 확인합니다.

    SXG를 보여주는 Preview 탭의 스크린샷

CanSignHttpExchanges 인증서를 사용하여 서명된 교환 제공

이 섹션의 안내에서는 CanSignHttpExchanges 인증서를 사용하여 SXG를 제공하는 방법을 설명합니다. SXG를 프로덕션에 사용하려면 CanSignHttpExchanges 인증서가 필요합니다.

이 안내에서는 자체 서명된 인증서를 사용하여 서명된 교환 설정 섹션에 설명된 개념을 이해하고 있다고 가정하고 작성되었습니다.

기본 요건

  • CanSignHttpExchanges 인증서가 있습니다. 이 페이지에서 이 유형의 인증서를 제공하는 CA를 확인할 수 있습니다.

  • 인증서가 없는 경우 CA에서 인증서를 자동으로 검색하도록 webpkgserver를 구성할 수 있습니다. 이 페이지의 webpkgserver.toml에 관한 지침을 따르면 됩니다.

  • 요구사항은 아니지만 에지 서버 뒤에서 webpkgserver를 실행하는 것이 좋습니다. 에지 서버를 사용하지 않는 경우 webpkgserver.toml에서 TLS.PEMFile 및 TLS.KeyFile 옵션을 구성해야 합니다. 기본적으로 webpkgserver는 HTTP를 통해 실행됩니다. 하지만 브라우저에서 유효한 것으로 간주하려면 SXG 인증서를 HTTPS를 통해 제공해야 합니다. TLS.PEMFile 및 TLS.KeyFile를 구성하면 webpkgserver가 HTTPS를 사용할 수 있으므로 브라우저에 직접 SXG 인증서를 제공할 수 있습니다.

안내

  1. 사이트의 SXG 인증서와 사이트의 CA 인증서를 연결하여 PEM 파일을 만듭니다. 자세한 안내는 여기를 참조하세요.

    PEM은 일반적으로 여러 인증서를 저장하기 위한 '컨테이너'로 사용되는 파일 형식입니다.

  2. 예를 복사하여 새 webpkgsever.toml 파일을 만듭니다.

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

  3. 원하는 편집기로 webpkgserver.toml를 열고 다음과 같이 변경합니다.

    • 전체 인증서 체인이 포함된 PEM 파일의 위치를 반영하도록 PEMFile = cert.pem 줄을 변경합니다.
    • PEM 파일에 해당하는 비공개 키의 위치를 반영하도록 KeyFile = 'priv.key' 줄을 변경합니다.
    • Domain = 'example.org' 줄을 변경하여 사이트를 반영합니다.
    • (선택사항) webpkgserver에서 90일마다 (Google의 경우 45일) SXG 인증서를 자동 갱신하도록 하려면 webpkgserver.toml의 [SXG.ACME] 섹션에서 옵션을 구성합니다. 이 옵션은 DigiCert 또는 Google ACME 계정이 설정된 사이트에만 적용됩니다.

  4. webpkgserver 인스턴스로 트래픽을 전달하도록 에지 서버를 구성합니다.

    webpkgserver에서 처리하는 요청에는 두 가지 기본 유형이 있습니다. 하나는 SXG 요청 (/priv/doc/ 엔드포인트에서 제공)이고 다른 하나는 SXG 인증서 요청 (/webpkg/cert/ 엔드포인트에서 제공)입니다. 이러한 각 요청 유형의 URL 재작성 규칙은 약간 다릅니다. 자세한 내용은 프런트엔드 에지 서버 뒤에서 실행을 참고하세요.

    참고:

    기본적으로 webpkgserver는 /webpkg/cert/$CERT_HASH에서 SXG 인증서를 제공합니다(예: /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY). $CERT_HASH를 생성하려면 다음 명령어를 실행합니다. shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =