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

웹 패키지 도구를 사용하여 서명된 교환(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 오류 메시지가 표시됩니다.

    선택사항

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

    • webpkgserver가 스타일시트 및 스크립트 하위 리소스를 SXG로 미리 로드하기 위한 디렉티브를 삽입하도록 하려면 #PreloadCSS = false 줄을 PreloadCSS = true로 변경합니다. 또한 #PreloadJS = false 줄을 PreloadJS = true로 변경합니다.

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

    • 기본적으로 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

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

    SXG 및 인증서를 보여주는 DevTools 네트워크 탭의 스크린샷

    네트워크 탭에는 다음 리소스가 표시됩니다.

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

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

    미리보기 탭을 클릭하여 서명된 교환 및 서명에 관한 자세한 정보를 확인합니다.

    SXG를 보여주는 미리보기 탭의 스크린샷

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(예: /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY)에서 SXG 인증서를 제공합니다. $CERT_HASH를 생성하려면 다음 명령어를 실행합니다. shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =