InfoGrab DocsInfoGrab Docs

자체 호스팅 Sigstore로 아티팩트와 컨테이너 이미지 서명

요약

GitLab Self-Managed를 실행하는 경우 공개 Sigstore 서비스로 CI/CD 아티팩트와 컨테이너 이미지에 서명할 수 없습니다. GitLab OpenID Connect(OIDC) 공급자가 사용자의 ID를 증명하고, Cosign은 서명 키를 사용한 직후 폐기하며, Rekor는 모든 서명 이벤트를 투명성 로그에 기록합니다.

GitLab Self-Managed를 실행하는 경우 공개 Sigstore 서비스로 CI/CD 아티팩트와 컨테이너 이미지에 서명할 수 없습니다. 이 서비스는 GitLab.com 파이프라인만 신뢰하며 사용자 인스턴스의 파이프라인은 신뢰하지 않습니다. 대신 자체 Sigstore 인프라(Fulcio, Rekor, Certificate Transparency 로그)를 GitLab 인스턴스에 연결하면, GitLab.com이나 인터넷에 의존하지 않고 Cosign으로 아티팩트에 서명하고 검증할 수 있습니다.

GitLab OpenID Connect(OIDC) 공급자가 사용자의 ID를 증명하고, Cosign은 서명 키를 사용한 직후 폐기하며, Rekor는 모든 서명 이벤트를 투명성 로그에 기록합니다.

Fulcio가 발급하는 인증서는 서명에 포함되며, 서명을 만든 파이프라인에 대한 세부 정보도 함께 담깁니다. 여기에는 프로젝트 경로, 커밋 SHA, 파이프라인 소스, 러너 환경, job URL이 포함됩니다.

사전 요구 사항:

  • Sigstore 인프라(Fulcio, Rekor)와 GitLab CI/CD 러너를 구성할 수 있는 액세스 권한이 있어야 합니다.
  • Fulcio, Rekor, Certificate Transparency 로그를 포함해 네트워크 내에서 실행되는 자체 호스팅 Sigstore 스택이 있어야 합니다. Certificate Transparency 로그는 필수입니다. Cosign은 검증 중에 서명된 인증서 타임스탬프를 확인하므로, Certificate Transparency 로그 없이 배포한 Fulcio가 발급하는 인증서는 Cosign이 검증할 수 없습니다. 배포 지침은 다음을 참고합니다.
  • GitLab 인스턴스가 사설 인증 기관의 인증서로 HTTPS를 사용한다면, 해당 인증 기관을 Fulcio와 CI/CD 러너가 모두 신뢰해야 합니다.
    • Fulcio 컨테이너에 마운트한 인증 기관 인증서이며, SSL_CERT_FILE을 그 경로로 설정합니다.
    • 각 러너의 운영 체제 신뢰 저장소에 설치한 인증 기관 인증서
  • CI/CD 러너에 Cosign v2.x 이상이 설치되어 있어야 합니다.
  • Sigstore 스택의 신뢰 자료 파일을 /etc/sigstore/ 같은 공유 위치에서 러너에 배치해야 합니다.
    • Fulcio 루트 CA 인증서(fulcio-root.pem)
    • Rekor 투명성 로그 공개 키(rekor-pub.pem)
    • Certificate Transparency 로그 공개 키(ctfe-pub.pem)

GitLab 인스턴스를 신뢰하도록 Fulcio 구성#

키 없는 서명 중에 GitLab CI/CD job의 OIDC 토큰을 검증할 수 있도록 GitLab 인스턴스를 신뢰하게 Fulcio를 구성합니다. Fulcio는 토큰의 클레임을 서명 인증서의 필드에 매핑합니다. 구성 파일에는 oidc-issuers 섹션과 ci-issuer-metadata 섹션이 모두 필요합니다.

Fulcio를 구성하려면 다음을 수행합니다.

  1. 다음 명령으로 정확한 OIDC 발급자 URL을 가져옵니다. https://gitlab.example.com을 GitLab 인스턴스의 URL로 바꿉니다. Fulcio는 정확히 일치해야 합니다. 스킴과 끝의 슬래시 유무가 모두 중요합니다.

    curl --silent "https://gitlab.example.com/.well-known/openid-configuration" | jq --raw-output .issuer
    
  2. GitLab 인스턴스에 대한 oidc-issuers 항목이 있는 Fulcio OIDC 구성 파일을 만듭니다. <gitlab_issuer_url>을 이전 단계의 출력으로 바꿉니다.

    oidc-issuers:
      <gitlab_issuer_url>:
        issuer-url: <gitlab_issuer_url>
        client-id: sigstore
        type: ci-provider
        ci-provider: gitlab-pipeline
        contact: admin@example.com
        description: "GitLab Self-Managed OIDC"
    
  3. 같은 파일에 업스트림 Fulcio 구성에서 복사한 GitLab 클레임 템플릿으로 ci-issuer-metadata 섹션을 추가합니다. <gitlab_issuer_url>을 이전 단계에서 사용한 값과 같은 값으로 바꿉니다.

    각 클레임이 무엇에 매핑되는지는 OIDC 토큰 클레임을 Fulcio OID에 매핑의 GitLab 열을 참고합니다.

    ci-issuer-metadata:
      gitlab-pipeline:
        default-template-values:
          url: "<gitlab_issuer_url>"
          environment: ""
        extension-templates:
          build-signer-uri: "https://{}"
          build-signer-digest: "ci_config_sha"
          runner-environment: "runner_environment"
          source-repository-uri: "{}/{}"
          source-repository-digest: "sha"
          source-repository-ref: >-
            refs/{{if eq .ref_type "branch"}}heads/{{ else }}tags/{{end}}{}
          source-repository-identifier: "project_id"
          source-repository-owner-uri: "{}/{}"
          source-repository-owner-identifier: "namespace_id"
          build-config-uri: "https://{}"
          build-config-digest: "ci_config_sha"
          build-trigger: "pipeline_source"
          run-invocation-uri: >-
            {}/{}/-/jobs/{}
          source-repository-visibility-at-signing: "project_visibility"
          deployment-environment: "environment"
        subject-alternative-name-template: "https://{}"
    

    [!note] 이 섹션은 GitLab이 아니라 Sigstore 프로젝트가 관리합니다. 업스트림 파일에 변경 사항이 있는지 주기적으로 확인하고, 사본을 그에 맞게 업데이트합니다.

재시작 후에도 키와 로그를 유지하도록 Rekor 구성#

기본적으로 Rekor는 시작할 때마다 새 서명 키를 생성하고 비어 있는 새 로그 트리를 만듭니다. 재시작 후에도 둘을 유지하려면 영구 서명자와 고정 트리 ID로 Rekor를 구성합니다.

Rekor를 구성하려면 다음을 수행합니다.

  1. Rekor가 실행되는 동안 현재 로그의 트리 ID를 가져옵니다.

    curl --silent "http://<sigstore-host>:3000/api/v1/log" | jq --raw-output .treeID
    
  2. Rekor를 시작하는 rekor-server serve 명령에 다음 플래그를 추가한 다음 Rekor를 재시작합니다.

    --rekor_server.signer=<signer>
    --trillian_log_server.tlog_id=<tree_id>
    

    다음과 같이 바꿉니다.

    • <signer>를 HashiCorp Vault 트랜짓 키의 hashivault://<key_name>처럼 키 관리 서비스 URI로 바꿉니다. Vault의 경우 Rekor에 VAULT_ADDR 및 VAULT_TOKEN 환경 변수도 설정합니다. Rekor는 PEM으로 인코딩된 개인 키 파일의 경로도 받습니다. Rekor 명령 도움말은 파일 기반 서명자를 테스트용으로만 사용해야 한다고 안내합니다.
    • <tree_id>를 이전 단계의 트리 ID로 바꿉니다.
  3. 서명자를 변경했다면 새 Rekor 공개 키로 신뢰 자료를 다시 만듭니다. 명령은 오류: not enough verified log entries from transparency log를 참고합니다.

Warning

영구 서명자가 있고 트리 ID가 없으면 재시작 후에도 서명은 계속 동작합니다. 그러나 Rekor는 재시작 전에 기록된 항목을 더 이상 반환하지 않으며, 새 항목은 로그 인덱스 0부터 다시 시작합니다.

아티팩트와 컨테이너 이미지 서명#

id_tokens 키워드를 사용해 job용 OIDC 토큰을 생성합니다. Cosign은 이 토큰을 Fulcio에 제시하고, Fulcio는 임시 서명 인증서를 발급합니다.

Cosign v3는 서명 구성 파일로 Sigstore 서비스 엔드포인트와 신뢰 자료를 지정합니다. 이 파일을 한 번 생성해 러너에 배포하거나, 다음 예시처럼 각 job에서 생성합니다.

sign-artifact:
  stage: sign
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  variables:
    COSIGN_YES: "true"
  script:
    - cosign signing-config create
        --fulcio="url=http://<sigstore-host>:5555,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org"
        --rekor="url=http://<sigstore-host>:3000,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org"
        --rekor-config="ANY"
        --oidc-provider="url=https://gitlab.example.com,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org"
        --out signing-config.json
    - cosign trusted-root create
        --fulcio="url=http://<sigstore-host>:5555,certificate-chain=/etc/sigstore/fulcio-root.pem,start-time=2024-01-01T00:00:00Z"
        --rekor="url=http://<sigstore-host>:3000,public-key=/etc/sigstore/rekor-pub.pem,start-time=2024-01-01T00:00:00Z"
        --ctfe="url=http://<sigstore-host>:6962,public-key=/etc/sigstore/ctfe-pub.pem,start-time=2024-01-01T00:00:00Z"
        --out trusted-root.json
    - cosign sign-blob
        --signing-config=signing-config.json
        --trusted-root=trusted-root.json
        --oidc-client-id=sigstore
        --identity-token=$SIGSTORE_ID_TOKEN
        --bundle=artifact.bundle
        artifact.txt

start-time 값은 Sigstore protobuf 사양에 정의된 대로 서비스 엔드포인트가 유효한 것으로 간주되는 가장 이른 시각입니다. Sigstore 스택을 배포한 날짜를 사용합니다.

--oidc-client-id의 sigstore를 Fulcio OIDC 발급자 항목에 구성한 클라이언트 ID로 바꿉니다.

--oidc-provider에는 Fulcio oidc-issuers 구성에 등록한 것과 같은 발급자 URL을 사용합니다.

컨테이너 이미지 서명#

컨테이너 이미지에 서명하려면 파일 경로 대신 이미지 참조와 함께 cosign sign을 사용합니다. 서명 구성은 같습니다.

컨테이너 레지스트리는 확인 가능한 호스트 이름으로 HTTPS를 통해 접근할 수 있어야 합니다. 레지스트리는 자체 외부 URL에 인증 영역(realm)을 알립니다. Cosign은 호스트가 사설 주소 또는 링크 로컬 주소 그대로인 영역을 거부합니다. registry_external_url이 IP 주소만으로 된 인스턴스는 파일에는 서명할 수 있지만 컨테이너 이미지에는 서명할 수 없습니다.

Cosign v2.x의 경우#

Cosign v2.x를 사용한다면 구성 파일 대신 URL 플래그와 환경 변수를 사용합니다.

sign-artifact:
  stage: sign
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  variables:
    COSIGN_YES: "true"
    SIGSTORE_ROOT_FILE: /etc/sigstore/fulcio-root.pem
    SIGSTORE_REKOR_PUBLIC_KEY: /etc/sigstore/rekor-pub.pem
    SIGSTORE_CT_LOG_PUBLIC_KEY_FILE: /etc/sigstore/ctfe-pub.pem
  script:
    - cosign sign-blob
        --fulcio-url=http://<sigstore-host>:5555
        --rekor-url=http://<sigstore-host>:3000
        --oidc-issuer=https://gitlab.example.com
        --identity-token=$SIGSTORE_ID_TOKEN
        --output-signature=artifact.sig
        --output-certificate=artifact.crt
        artifact.txt

컨테이너 이미지에는 컨테이너 이미지 서명에 설명된 대로 Cosign v3를 사용합니다.

Cosign v2는 인증서를 base64로 인코딩된 PEM으로 기록합니다. 다른 도구에 전달하기 전에 디코딩합니다.

--oidc-issuer에는 Fulcio oidc-issuers 구성에 등록한 것과 같은 발급자 URL을 사용합니다.

서명 검증#

Cosign v3 번들을 사용한 검증에는 신뢰 자료와 예상 서명자 ID가 사용됩니다.

cosign verify-blob \
  --trusted-root=trusted-root.json \
  --bundle=artifact.bundle \
  --certificate-oidc-issuer=https://gitlab.example.com \
  --certificate-identity=https://gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main \
  artifact.txt

--certificate-identity 값은 서명 인증서의 주체 대체 이름(Subject Alternative Name)이며, CI/CD 구성 경로로 만들어집니다.

https://///.gitlab-ci.yml@<full ref>

이 패턴에서 중요한 세부 사항은 세 가지입니다.

  • Fulcio 구성의 subject-alternative-name-template이 설정하므로 스킴은 항상 https://입니다. 인스턴스에 HTTP로 접근할 수 있는 경우에도 마찬가지입니다.
  • .gitlab-ci.yml 앞의 이중 슬래시는 올바른 형식입니다. 그 앞의 경로 세그먼트는 프로젝트이고, 뒤따르는 빈 세그먼트는 기본 CI/CD 구성 위치를 나타냅니다.
  • 전체 ref는 브랜치 파이프라인에서는 refs/heads/<branch>, 태그 파이프라인에서는 refs/tags/<tag>입니다.

Cosign v2로 서명한 아티팩트를 검증하려면 분리된 서명과 인증서를 전달합니다.

cosign verify-blob \
  --signature=artifact.sig \
  --certificate=artifact.crt \
  --certificate-oidc-issuer=https://gitlab.example.com \
  --certificate-identity=https://gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main \
  artifact.txt

관련 주제#

문제 해결#

자체 호스팅 Sigstore 인프라로 아티팩트에 서명할 때 다음 문제가 발생할 수 있습니다.

오류: metadata not found for ci provider gitlab-pipeline#

이 오류는 Fulcio 구성에 ci-issuer-metadata 섹션이 없을 때 발생합니다.

이 문제를 해결하려면 GitLab 인스턴스를 신뢰하도록 Fulcio 구성에 설명된 대로 전체 ci-issuer-metadata 블록을 추가합니다.

오류: ctfe public key not found for payload#

이 오류는 Cosign이 자체 호스팅 스택의 Certificate Transparency 로그 공개 키를 찾을 수 없을 때 발생합니다.

이 문제를 해결하려면 Cosign v3에서는 cosign trusted-root create 명령에 --ctfe를 포함하고, Cosign v2에서는 SIGSTORE_CT_LOG_PUBLIC_KEY_FILE 환경 변수를 설정합니다.

오류: not enough verified log entries from transparency log#

이 오류는 trusted-root.json의 Rekor 공개 키가 Rekor 인스턴스가 사용하는 키와 더 이상 일치하지 않을 때 발생합니다. 기본 인메모리 서명자를 사용하면 Rekor는 시작할 때마다 새 키를 생성합니다. 따라서 재시작하면 신뢰 자료가 무효화되고, 신뢰 자료를 다시 만들 때까지 모든 job에서 서명이 실패합니다.

이 문제를 해결하려면 실행 중인 인스턴스에서 현재 키를 읽고 신뢰 루트를 다시 생성합니다.

curl --silent --fail "http://<sigstore-host>:3000/api/v1/log/publicKey" --output /etc/sigstore/rekor-pub.pem
cosign trusted-root create \
  --fulcio="url=http://<sigstore-host>:5555,certificate-chain=/etc/sigstore/fulcio-root.pem,start-time=2024-01-01T00:00:00Z" \
  --rekor="url=http://<sigstore-host>:3000,public-key=/etc/sigstore/rekor-pub.pem,start-time=2024-01-01T00:00:00Z" \
  --ctfe="url=http://<sigstore-host>:6962,public-key=/etc/sigstore/ctfe-pub.pem,start-time=2024-01-01T00:00:00Z" \
  --out trusted-root.json

다시 생성한 trusted-root.json을 모든 러너에 배포합니다.

이 문제를 방지하려면 재시작 후에도 키와 로그를 유지하도록 Rekor 구성에 설명된 대로 영구 서명자로 Rekor를 구성합니다.

오류: failed to verify signed certificate timestamp#

이 오류는 인증서에 서명된 인증서 타임스탬프가 없을 때 발생하며, Fulcio가 Certificate Transparency 로그 없이 실행될 때 이런 일이 생깁니다. 이 구성에서도 서명은 성공하고 검증만 실패합니다.

이 문제를 해결하려면 --ct-log-url이 Certificate Transparency 로그를 가리키도록 Fulcio를 구성하고, 신뢰 루트를 만들 때 --ctfe를 포함합니다.

오류: x509: certificate signed by unknown authority#

이 오류는 Fulcio가 GitLab 인스턴스가 제시하는 TLS 인증서를 검증할 수 없을 때 발생합니다.

이 문제를 해결하려면 사설 인증 기관 인증서를 Fulcio 컨테이너에 마운트하고 SSL_CERT_FILE을 그 경로로 설정합니다.

Fulcio /healthz 엔드포인트는 OIDC 공급자 초기화가 실패한 경우에도 SERVING을 보고합니다. 컨테이너 로그로 공급자가 로드되었는지 확인합니다.

자체 호스팅 Sigstore로 아티팩트와 컨테이너 이미지 서명

GitLab v19.6
Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

GitLab Self-Managed를 실행하는 경우 공개 Sigstore 서비스로 CI/CD 아티팩트와 컨테이너 이미지에 서명할 수 없습니다. GitLab OpenID Connect(OIDC) 공급자가 사용자의 ID를 증명하고, Cosign은 서명 키를 사용한 직후 폐기하며, Rekor는 모든 서명 이벤트를 투명성 로그에 기록합니다.

GitLab Self-Managed를 실행하는 경우 공개 Sigstore 서비스로 CI/CD 아티팩트와 컨테이너 이미지에 서명할 수 없습니다. 이 서비스는 GitLab.com 파이프라인만 신뢰하며 사용자 인스턴스의 파이프라인은 신뢰하지 않습니다. 대신 자체 Sigstore 인프라(Fulcio, Rekor, Certificate Transparency 로그)를 GitLab 인스턴스에 연결하면, GitLab.com이나 인터넷에 의존하지 않고 Cosign으로 아티팩트에 서명하고 검증할 수 있습니다.

GitLab OpenID Connect(OIDC) 공급자가 사용자의 ID를 증명하고, Cosign은 서명 키를 사용한 직후 폐기하며, Rekor는 모든 서명 이벤트를 투명성 로그에 기록합니다.

Fulcio가 발급하는 인증서는 서명에 포함되며, 서명을 만든 파이프라인에 대한 세부 정보도 함께 담깁니다. 여기에는 프로젝트 경로, 커밋 SHA, 파이프라인 소스, 러너 환경, job URL이 포함됩니다.

사전 요구 사항:

  • Sigstore 인프라(Fulcio, Rekor)와 GitLab CI/CD 러너를 구성할 수 있는 액세스 권한이 있어야 합니다.
  • Fulcio, Rekor, Certificate Transparency 로그를 포함해 네트워크 내에서 실행되는 자체 호스팅 Sigstore 스택이 있어야 합니다. Certificate Transparency 로그는 필수입니다. Cosign은 검증 중에 서명된 인증서 타임스탬프를 확인하므로, Certificate Transparency 로그 없이 배포한 Fulcio가 발급하는 인증서는 Cosign이 검증할 수 없습니다. 배포 지침은 다음을 참고합니다.
  • GitLab 인스턴스가 사설 인증 기관의 인증서로 HTTPS를 사용한다면, 해당 인증 기관을 Fulcio와 CI/CD 러너가 모두 신뢰해야 합니다.
    • Fulcio 컨테이너에 마운트한 인증 기관 인증서이며, SSL_CERT_FILE을 그 경로로 설정합니다.
    • 각 러너의 운영 체제 신뢰 저장소에 설치한 인증 기관 인증서
  • CI/CD 러너에 Cosign v2.x 이상이 설치되어 있어야 합니다.
  • Sigstore 스택의 신뢰 자료 파일을 /etc/sigstore/ 같은 공유 위치에서 러너에 배치해야 합니다.
    • Fulcio 루트 CA 인증서(fulcio-root.pem)
    • Rekor 투명성 로그 공개 키(rekor-pub.pem)
    • Certificate Transparency 로그 공개 키(ctfe-pub.pem)

GitLab 인스턴스를 신뢰하도록 Fulcio 구성#

키 없는 서명 중에 GitLab CI/CD job의 OIDC 토큰을 검증할 수 있도록 GitLab 인스턴스를 신뢰하게 Fulcio를 구성합니다. Fulcio는 토큰의 클레임을 서명 인증서의 필드에 매핑합니다. 구성 파일에는 oidc-issuers 섹션과 ci-issuer-metadata 섹션이 모두 필요합니다.

Fulcio를 구성하려면 다음을 수행합니다.

  1. 다음 명령으로 정확한 OIDC 발급자 URL을 가져옵니다. https://gitlab.example.com을 GitLab 인스턴스의 URL로 바꿉니다. Fulcio는 정확히 일치해야 합니다. 스킴과 끝의 슬래시 유무가 모두 중요합니다.

    curl --silent "https://gitlab.example.com/.well-known/openid-configuration" | jq --raw-output .issuer
    
  2. GitLab 인스턴스에 대한 oidc-issuers 항목이 있는 Fulcio OIDC 구성 파일을 만듭니다. <gitlab_issuer_url>을 이전 단계의 출력으로 바꿉니다.

    oidc-issuers:
      <gitlab_issuer_url>:
        issuer-url: <gitlab_issuer_url>
        client-id: sigstore
        type: ci-provider
        ci-provider: gitlab-pipeline
        contact: admin@example.com
        description: "GitLab Self-Managed OIDC"
    
  3. 같은 파일에 업스트림 Fulcio 구성에서 복사한 GitLab 클레임 템플릿으로 ci-issuer-metadata 섹션을 추가합니다. <gitlab_issuer_url>을 이전 단계에서 사용한 값과 같은 값으로 바꿉니다.

    각 클레임이 무엇에 매핑되는지는 OIDC 토큰 클레임을 Fulcio OID에 매핑의 GitLab 열을 참고합니다.

    ci-issuer-metadata:
      gitlab-pipeline:
        default-template-values:
          url: "<gitlab_issuer_url>"
          environment: ""
        extension-templates:
          build-signer-uri: "https://{}"
          build-signer-digest: "ci_config_sha"
          runner-environment: "runner_environment"
          source-repository-uri: "{}/{}"
          source-repository-digest: "sha"
          source-repository-ref: >-
            refs/{{if eq .ref_type "branch"}}heads/{{ else }}tags/{{end}}{}
          source-repository-identifier: "project_id"
          source-repository-owner-uri: "{}/{}"
          source-repository-owner-identifier: "namespace_id"
          build-config-uri: "https://{}"
          build-config-digest: "ci_config_sha"
          build-trigger: "pipeline_source"
          run-invocation-uri: >-
            {}/{}/-/jobs/{}
          source-repository-visibility-at-signing: "project_visibility"
          deployment-environment: "environment"
        subject-alternative-name-template: "https://{}"
    

    [!note] 이 섹션은 GitLab이 아니라 Sigstore 프로젝트가 관리합니다. 업스트림 파일에 변경 사항이 있는지 주기적으로 확인하고, 사본을 그에 맞게 업데이트합니다.

재시작 후에도 키와 로그를 유지하도록 Rekor 구성#

기본적으로 Rekor는 시작할 때마다 새 서명 키를 생성하고 비어 있는 새 로그 트리를 만듭니다. 재시작 후에도 둘을 유지하려면 영구 서명자와 고정 트리 ID로 Rekor를 구성합니다.

Rekor를 구성하려면 다음을 수행합니다.

  1. Rekor가 실행되는 동안 현재 로그의 트리 ID를 가져옵니다.

    curl --silent "http://<sigstore-host>:3000/api/v1/log" | jq --raw-output .treeID
    
  2. Rekor를 시작하는 rekor-server serve 명령에 다음 플래그를 추가한 다음 Rekor를 재시작합니다.

    --rekor_server.signer=<signer>
    --trillian_log_server.tlog_id=<tree_id>
    

    다음과 같이 바꿉니다.

    • <signer>를 HashiCorp Vault 트랜짓 키의 hashivault://<key_name>처럼 키 관리 서비스 URI로 바꿉니다. Vault의 경우 Rekor에 VAULT_ADDR 및 VAULT_TOKEN 환경 변수도 설정합니다. Rekor는 PEM으로 인코딩된 개인 키 파일의 경로도 받습니다. Rekor 명령 도움말은 파일 기반 서명자를 테스트용으로만 사용해야 한다고 안내합니다.
    • <tree_id>를 이전 단계의 트리 ID로 바꿉니다.
  3. 서명자를 변경했다면 새 Rekor 공개 키로 신뢰 자료를 다시 만듭니다. 명령은 오류: not enough verified log entries from transparency log를 참고합니다.

Warning

영구 서명자가 있고 트리 ID가 없으면 재시작 후에도 서명은 계속 동작합니다. 그러나 Rekor는 재시작 전에 기록된 항목을 더 이상 반환하지 않으며, 새 항목은 로그 인덱스 0부터 다시 시작합니다.

아티팩트와 컨테이너 이미지 서명#

id_tokens 키워드를 사용해 job용 OIDC 토큰을 생성합니다. Cosign은 이 토큰을 Fulcio에 제시하고, Fulcio는 임시 서명 인증서를 발급합니다.

Cosign v3는 서명 구성 파일로 Sigstore 서비스 엔드포인트와 신뢰 자료를 지정합니다. 이 파일을 한 번 생성해 러너에 배포하거나, 다음 예시처럼 각 job에서 생성합니다.

sign-artifact:
  stage: sign
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  variables:
    COSIGN_YES: "true"
  script:
    - cosign signing-config create
        --fulcio="url=http://<sigstore-host>:5555,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org"
        --rekor="url=http://<sigstore-host>:3000,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org"
        --rekor-config="ANY"
        --oidc-provider="url=https://gitlab.example.com,api-version=1,start-time=2024-01-01T00:00:00Z,operator=my-org"
        --out signing-config.json
    - cosign trusted-root create
        --fulcio="url=http://<sigstore-host>:5555,certificate-chain=/etc/sigstore/fulcio-root.pem,start-time=2024-01-01T00:00:00Z"
        --rekor="url=http://<sigstore-host>:3000,public-key=/etc/sigstore/rekor-pub.pem,start-time=2024-01-01T00:00:00Z"
        --ctfe="url=http://<sigstore-host>:6962,public-key=/etc/sigstore/ctfe-pub.pem,start-time=2024-01-01T00:00:00Z"
        --out trusted-root.json
    - cosign sign-blob
        --signing-config=signing-config.json
        --trusted-root=trusted-root.json
        --oidc-client-id=sigstore
        --identity-token=$SIGSTORE_ID_TOKEN
        --bundle=artifact.bundle
        artifact.txt

start-time 값은 Sigstore protobuf 사양에 정의된 대로 서비스 엔드포인트가 유효한 것으로 간주되는 가장 이른 시각입니다. Sigstore 스택을 배포한 날짜를 사용합니다.

--oidc-client-id의 sigstore를 Fulcio OIDC 발급자 항목에 구성한 클라이언트 ID로 바꿉니다.

--oidc-provider에는 Fulcio oidc-issuers 구성에 등록한 것과 같은 발급자 URL을 사용합니다.

컨테이너 이미지 서명#

컨테이너 이미지에 서명하려면 파일 경로 대신 이미지 참조와 함께 cosign sign을 사용합니다. 서명 구성은 같습니다.

컨테이너 레지스트리는 확인 가능한 호스트 이름으로 HTTPS를 통해 접근할 수 있어야 합니다. 레지스트리는 자체 외부 URL에 인증 영역(realm)을 알립니다. Cosign은 호스트가 사설 주소 또는 링크 로컬 주소 그대로인 영역을 거부합니다. registry_external_url이 IP 주소만으로 된 인스턴스는 파일에는 서명할 수 있지만 컨테이너 이미지에는 서명할 수 없습니다.

Cosign v2.x의 경우#

Cosign v2.x를 사용한다면 구성 파일 대신 URL 플래그와 환경 변수를 사용합니다.

sign-artifact:
  stage: sign
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  variables:
    COSIGN_YES: "true"
    SIGSTORE_ROOT_FILE: /etc/sigstore/fulcio-root.pem
    SIGSTORE_REKOR_PUBLIC_KEY: /etc/sigstore/rekor-pub.pem
    SIGSTORE_CT_LOG_PUBLIC_KEY_FILE: /etc/sigstore/ctfe-pub.pem
  script:
    - cosign sign-blob
        --fulcio-url=http://<sigstore-host>:5555
        --rekor-url=http://<sigstore-host>:3000
        --oidc-issuer=https://gitlab.example.com
        --identity-token=$SIGSTORE_ID_TOKEN
        --output-signature=artifact.sig
        --output-certificate=artifact.crt
        artifact.txt

컨테이너 이미지에는 컨테이너 이미지 서명에 설명된 대로 Cosign v3를 사용합니다.

Cosign v2는 인증서를 base64로 인코딩된 PEM으로 기록합니다. 다른 도구에 전달하기 전에 디코딩합니다.

--oidc-issuer에는 Fulcio oidc-issuers 구성에 등록한 것과 같은 발급자 URL을 사용합니다.

서명 검증#

Cosign v3 번들을 사용한 검증에는 신뢰 자료와 예상 서명자 ID가 사용됩니다.

cosign verify-blob \
  --trusted-root=trusted-root.json \
  --bundle=artifact.bundle \
  --certificate-oidc-issuer=https://gitlab.example.com \
  --certificate-identity=https://gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main \
  artifact.txt

--certificate-identity 값은 서명 인증서의 주체 대체 이름(Subject Alternative Name)이며, CI/CD 구성 경로로 만들어집니다.

https://///.gitlab-ci.yml@<full ref>

이 패턴에서 중요한 세부 사항은 세 가지입니다.

  • Fulcio 구성의 subject-alternative-name-template이 설정하므로 스킴은 항상 https://입니다. 인스턴스에 HTTP로 접근할 수 있는 경우에도 마찬가지입니다.
  • .gitlab-ci.yml 앞의 이중 슬래시는 올바른 형식입니다. 그 앞의 경로 세그먼트는 프로젝트이고, 뒤따르는 빈 세그먼트는 기본 CI/CD 구성 위치를 나타냅니다.
  • 전체 ref는 브랜치 파이프라인에서는 refs/heads/<branch>, 태그 파이프라인에서는 refs/tags/<tag>입니다.

Cosign v2로 서명한 아티팩트를 검증하려면 분리된 서명과 인증서를 전달합니다.

cosign verify-blob \
  --signature=artifact.sig \
  --certificate=artifact.crt \
  --certificate-oidc-issuer=https://gitlab.example.com \
  --certificate-identity=https://gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main \
  artifact.txt

관련 주제#

문제 해결#

자체 호스팅 Sigstore 인프라로 아티팩트에 서명할 때 다음 문제가 발생할 수 있습니다.

오류: metadata not found for ci provider gitlab-pipeline#

이 오류는 Fulcio 구성에 ci-issuer-metadata 섹션이 없을 때 발생합니다.

이 문제를 해결하려면 GitLab 인스턴스를 신뢰하도록 Fulcio 구성에 설명된 대로 전체 ci-issuer-metadata 블록을 추가합니다.

오류: ctfe public key not found for payload#

이 오류는 Cosign이 자체 호스팅 스택의 Certificate Transparency 로그 공개 키를 찾을 수 없을 때 발생합니다.

이 문제를 해결하려면 Cosign v3에서는 cosign trusted-root create 명령에 --ctfe를 포함하고, Cosign v2에서는 SIGSTORE_CT_LOG_PUBLIC_KEY_FILE 환경 변수를 설정합니다.

오류: not enough verified log entries from transparency log#

이 오류는 trusted-root.json의 Rekor 공개 키가 Rekor 인스턴스가 사용하는 키와 더 이상 일치하지 않을 때 발생합니다. 기본 인메모리 서명자를 사용하면 Rekor는 시작할 때마다 새 키를 생성합니다. 따라서 재시작하면 신뢰 자료가 무효화되고, 신뢰 자료를 다시 만들 때까지 모든 job에서 서명이 실패합니다.

이 문제를 해결하려면 실행 중인 인스턴스에서 현재 키를 읽고 신뢰 루트를 다시 생성합니다.

curl --silent --fail "http://<sigstore-host>:3000/api/v1/log/publicKey" --output /etc/sigstore/rekor-pub.pem
cosign trusted-root create \
  --fulcio="url=http://<sigstore-host>:5555,certificate-chain=/etc/sigstore/fulcio-root.pem,start-time=2024-01-01T00:00:00Z" \
  --rekor="url=http://<sigstore-host>:3000,public-key=/etc/sigstore/rekor-pub.pem,start-time=2024-01-01T00:00:00Z" \
  --ctfe="url=http://<sigstore-host>:6962,public-key=/etc/sigstore/ctfe-pub.pem,start-time=2024-01-01T00:00:00Z" \
  --out trusted-root.json

다시 생성한 trusted-root.json을 모든 러너에 배포합니다.

이 문제를 방지하려면 재시작 후에도 키와 로그를 유지하도록 Rekor 구성에 설명된 대로 영구 서명자로 Rekor를 구성합니다.

오류: failed to verify signed certificate timestamp#

이 오류는 인증서에 서명된 인증서 타임스탬프가 없을 때 발생하며, Fulcio가 Certificate Transparency 로그 없이 실행될 때 이런 일이 생깁니다. 이 구성에서도 서명은 성공하고 검증만 실패합니다.

이 문제를 해결하려면 --ct-log-url이 Certificate Transparency 로그를 가리키도록 Fulcio를 구성하고, 신뢰 루트를 만들 때 --ctfe를 포함합니다.

오류: x509: certificate signed by unknown authority#

이 오류는 Fulcio가 GitLab 인스턴스가 제시하는 TLS 인증서를 검증할 수 없을 때 발생합니다.

이 문제를 해결하려면 사설 인증 기관 인증서를 Fulcio 컨테이너에 마운트하고 SSL_CERT_FILE을 그 경로로 설정합니다.

Fulcio /healthz 엔드포인트는 OIDC 공급자 초기화가 실패한 경우에도 SERVING을 보고합니다. 컨테이너 로그로 공급자가 로드되었는지 확인합니다.