PEP 740 – 디지털 증명을 위한 인덱스 지원

Author:: William Woodruff <william at yossarian.net>, Facundo Tuesca <facundo.tuesca at trailofbits.com>, Dustin Ingram <di at python.org>
Sponsor:: Donald Stufft <donald at stufft.io>
PEP-Delegate:: Donald Stufft <donald at stufft.io>
Discussions-To:: Discourse thread
Status:: Final
Type:: Standards Track
Topic:: Packaging
Created:: 08-Jan-2024
Post-History:: 02-Jan-2024, 29-Jan-2024
Resolution:: 17-Jul-2024

Table of Contents

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Important

This PEP is a historical document. The up-to-date, canonical spec, Index hosted attestations, is maintained on the PyPA specs page.

See the PyPA specification update process for how to propose changes.

Important

This PEP is a historical document. The up-to-date, canonical documentation can now be found at PyPI - Digital Attestations.

See PEP 1 for how to propose changes.

초록

이 PEP는 PyPI와 같은 Python 패키지 저장소에서 디지털 서명된 증명과 이를 검증하는 데 사용되는 메타데이터의 업로드 및 배포와 관련된 일련의 변경 사항을 제안합니다.

이러한 변경 사항은 다음 두 가지 하위 구성 요소로 이루어집니다.

현재 표준화되지 않은 PyPI 업로드 API를 변경하여 클라이언트가 디지털 증명을 증명 객체로 업로드할 수 있도록 합니다.
클라이언트가 개별 릴리스 파일의 디지털 증명과 신뢰할 수 있는 게시 메타데이터를 모두 출처 객체로 검색할 수 있도록 하는 HTML 및 JSON “simple” API 변경 사항입니다.

이 PEP는 릴리스 업로드 시 디지털 증명을 의무화하거나 pip과 같은 설치 클라이언트가 이후 이를 검증하도록 하는 정책을 권고하지 않습니다.

근거 및 동기

Python 패키지에 대한 디지털 서명의 필요성은 패키지 관리자와 다운스트림 사용자 모두에 의해 반복해서 표명되어 왔습니다.

관리자는 패키지 업로드의 무결성과 진본성을 입증하고자 합니다.
개별 다운스트림 사용자는 인덱스의 정직성에 추가적인 신뢰를 부여하지 않고 패키지의 무결성과 진본성을 검증하고자 합니다.
“대량” 다운스트림 사용자(운영 체제 배포판 등)는 유사한 검증을 수행하고, 자체 다운스트림 패키징 생태계를 위해 이를 재공개하거나 재서명하고자 합니다.

이 제안은 위의 각 사용 사례를 지원하고자 합니다.

또한 이 제안은 다음과 같은 동기를 제시합니다.

Python 패키지 배포판에 대해 검증 가능한 출처: 현재 많은 Python 패키지에는 소스 호스트의 URL과 같은 인증되지 않은 출처 메타데이터가 포함되어 있습니다. 암호학적 증명 형식을 사용하면 이러한 패키지와 소스 호스트 사이에 강력한 인증된 연결을 설정할 수 있으며, 이를 통해 인덱스와 다운스트림 사용자가 패키지가 명시된 소스 저장소에서 비롯되었는지를 암호학적으로 검증할 수 있습니다.
공격자 요구 사항의 상향: Python 패키지를 탈취하려는 공격자는 정교함(정교하지 않음에서 정교함까지) 및 표적화(기회주의적 표적화에서 특정 표적화까지) 차원으로 설명할 수 있습니다.
디지털 증명은 추가적인 정교함을 요구합니다. 공격자는 비공개 서명 자료(또는 서명 신원)에 접근할 수 있을 만큼 충분히 정교해야 합니다.
인덱스 검증 가능성: 현재 상태에서 인덱스가 제공하는 유일한 증명은 릴리스 파일마다 선택적으로 제공되는 PGP 서명입니다( PGP 서명 참조). 인덱스에는 해당 서명에 맞는 공개 키를 식별할 방법이 없으므로, 이러한 서명은 형식 준수 여부나 유효성에 대해 인덱스에서 검사되지 않으며(검사할 수도 없습니다). 이 PEP는 출처 객체에 인덱스가 증명의 유효성을 검증하는 데 필요한 모든 메타데이터가 포함되도록 보장하여 이러한 한계를 극복합니다.

이 PEP는 서명 생성을 위한 증명 문을 포함하는 일반적인 증명 형식을 제안하며, 인덱스 제공자가 Trusted Publishing과 같이 서명 검증에 적합한 신원 출처와 함께 이 형식을 채택할 것을 기대합니다.

설계 고려 사항

이 PEP는 자체적으로 제안하는 변경 사항과 Python 패키징의 동일하거나 인접한 영역에서 수행된 이전 작업을 평가할 때 다음과 같은 설계 고려 사항을 식별합니다.

인덱스 접근성: Python 패키지의 디지털 증명은 “분리된” 리소스로서 인덱스 자체에서 직접 가져올 수 있는 것이 이상적입니다.
이는 배포 형식 자체를 수정할 필요를 없애 일부 호환성 문제를 단순화하며, 잠재적인 설치 클라이언트가 스트리밍 압축 해제를 수행하지 않고도 해당 패키지보다 먼저 각 증명을 가져올 수 있도록 하여 그 동작도 단순화합니다.
색인 자체에 의한 검증: 설치 클라이언트가 검증할 수 있도록 하는 것과 더불어, 각 디지털 증명은 어떤 형태로든 색인 자체에서 이상적으로 검증할 수 있어야 합니다.
이는 인덱스에 업로드되는 증명의 전반적인 품질을 높이고(예를 들어 사용자가 잘못되었거나 유효하지 않은 증명을 실수로 업로드하는 것을 방지함) 인덱스 자체에서 UI 및 UX를 개선할 수 있도록 합니다(각 업로드 패키지에 대한 “출처” 보기 등).
일반적 적용 가능성: 디지털 증명은 형식(sdist 또는 wheel)이나 내부 내용과 관계없이 인덱스에 업로드되는 모든 패키지에 적용할 수 있어야 합니다.
메타데이터 지원: 이 PEP는 암호학적 봉투 내에 추가 메타데이터가 포함되는 것이 이상적임을 강조하기 위해 단순히 “디지털 서명”이 아니라 “디지털 증명”이라는 용어를 사용합니다.
예를 들어 배포 패키지의 이름과 콘텐츠 사이의 도메인 분리를 방지하기 위해, 이 PEP는 Statements를 in-toto 프로젝트에서 가져와 배포 패키지의 콘텐츠(SHA-256 다이제스트를 통해)를 파일 이름에 연결합니다.

이전 작업

PGP 서명

PyPI 및 기타 색인은 업로드된 배포 패키지에 대한 PGP 서명을 역사적으로 지원해 왔습니다. 이러한 서명은 업로드 중에 제공할 수 있었으며, 설치 클라이언트는 PEP 503 API의 data-gpg-sig특성, PEP 691 API의 gpg-sig키 또는 인접한 .asc 접미사 URL을 통해 이를 가져올 수 있었습니다.

PyPI에서는 May 2023부터 PGP 서명 업로드가 비활성화되었습니다. 이는 an investigation조사에서 대부분의 서명이(서명 자체도 전체 업로드에서 극히 적은 비율을 차지했지만) 공개 키와 연결될 수 없거나 다른 방식으로 의미 있게 검증될 수 없다고 밝혔기 때문입니다.

PyPI에서 이전에 지원되던 형태의 PGP 서명은 위 고려 사항 (1)과 (3)은 충족했지만, (2)는 충족하지 못했으며(외부 키 서버와 키 배포가 필요했기 때문입니다), (4)도 충족하지 못했습니다(PGP 서명은 일반적으로 연결된 서명 메타데이터 없이 입력 파일 하나에 대해서만 생성되기 때문입니다).

휠 서명

PEP 427(및 그 living PyPA counterpart에 해당하는 사양)은 wheel format을 지정합니다.

이 형식은 JWS 또는 S/MIME 형식으로 휠에 직접 삽입되는 디지털 서명을 지원합니다. 이러한 서명은 PEP 376 RECORD에 대해 지정되며, RECORD는 휠에 기록된 각 파일의 암호화 다이제스트를 포함하도록 수정됩니다.

휠 서명은 완전히 지정되어 있지만 광범위하게 사용되는 것으로 보이지는 않습니다. 2018년에 릴리스된 공식 wheel tooling은 in 0.32.0에서 서명 생성 및 검증 지원을 사용 중단했습니다.

또한 휠 서명은 위 고려 사항을 전혀 충족하지 못합니다(서명이 “첨부”되는 특성, 색인 자체에서 검증할 수 없다는 점, 휠만 지원한다는 점 때문입니다).

사양

업로드 엔드포인트 변경 사항

현재 업로드 API는 표준화되어 있지 않습니다. 그러나 다음과 같이 변경할 것을 제안합니다.

현재 최상위 수준의 content 및 gpg_signature 필드에 더하여, 색인은 추가 멀티파트 폼 필드로 attestations를 허용해야 합니다.
새로운 attestations 필드는 반드시 JSON 배열이어야 합니다.
attestations 배열은 반드시 하나 이상의 항목을 가져야 하며, 각 항목은 개별 증명을 나타내는 JSON 객체여야 합니다.
각 증명 객체는 색인에서 검증할 수 있어야 합니다. 색인이 attestations의 증명을 하나라도 검증하지 못하면 업로드를 거부해야 합니다. 어테스테이션 객체의 형식은 증명 객체에서 정의하며, 어테스테이션 검증 프로세스는 증명 검증에서 정의합니다.

색인 변경 사항

단순 색인

다음 변경 사항이 simple repository API에 적용됩니다.

업로드된 파일에 증명이 하나 이상 있으면, 색인은 특정 배포와 연결된 증명을 포함하는 provenance 파일을 제공할 수 있습니다. 출처 파일의 형식은 반드시 JSON으로 인코딩된 출처 객체이어야 하며, 이 객체에는 파일의 증명이 반드시 포함되어야 합니다.
출처 파일의 위치는 색인이 data-provenance특성을 통해 알립니다.

provenance 파일이 있으면 색인은 해당 파일 링크에 data-provenance 속성을 포함할 수 있습니다. data-provenance 속성의 값은 완전한 URL이어야 하며, 해당 URL에서 파일의 출처를 확인할 수 있음을 나타내야 합니다. 이 URL은 secure origin을 나타내야 합니다.

다음 표는 릴리스 파일 URL, data-provenance 값, 그리고 그 결과로 생성되는 provenance 파일 URL의 예시를 보여줍니다.

File URL	`data-provenance`	Provenance URL
https://example.com/sampleproject-1.2.3.tar.gz	`https://example.com/sampleproject-1.2.3.tar.gz.provenance`	https://example.com/sampleproject-1.2.3.tar.gz.provenance
https://example.com/sampleproject-1.2.3.tar.gz	`https://other.example.com/sampleproject-1.2.3.tar.gz/provenance`	https://other.example.com/sampleproject-1.2.3.tar.gz/provenance
https://example.com/sampleproject-1.2.3.tar.gz	`../relative`	(유효하지 않음: 완전한 URL이 아님)
https://example.com/sampleproject-1.2.3.tar.gz	`http://unencrypted.example.com/provenance`	(유효하지 않음: 보안 출처가 아님)

인덱스는 provenance 파일을 수정하도록 선택할 수 있습니다. 예를 들어, 색인은 제3자 감사자 또는 기타 서비스의 증명과 같은 추가 증명 및 검증 자료를 추가하도록 허용할 수 있습니다.
파일의 provenance가 변경될 수 있는 이유에 대한 추가 논의는 프로비넌스 객체의 변경 사항를 참조하십시오.

JSON 기반 Simple API

다음과 같은 변경 사항이 JSON simple API에 적용됩니다.

업로드된 파일에 증명이 하나 이상 있으면, 색인은 해당 파일의 file 딕셔너리에 provenance 키를 포함할 수 있습니다.
provenance 키의 값은 JSON 문자열이거나 null이어야 합니다. provenance가 null이 아니라면, 연결된 provenance 파일의 URL이어야 합니다.

전체 provenance object대신 SHA-256 다이제스트를 JSON API에 삽입하기로 한 기술적 결정에 대한 설명은 부록 3: 간단한 JSON API의 크기 고려 사항를 참조하십시오.

이러한 변경 사항을 적용하려면 JSON API의 버전을 변경해야 합니다.

api-version은 버전 1.3 이상을 지정해야 합니다.

증명 객체

증명 객체는 여러 필수 키를 포함하는 JSON 객체입니다. 애플리케이션 또는 서명자는 명시적으로 나열된 모든 키가 제공되는 한 추가 키를 포함할 수 있습니다. 증명 객체의 필수 레이아웃은 아래 의사 코드로 제공됩니다.

@dataclass
class Attestation:
    version: Literal[1]
    """
    The attestation object's version, which is always 1.
    """

    verification_material: VerificationMaterial
    """
    Cryptographic materials used to verify `envelope`.
    """

    envelope: Envelope
    """
    The enveloped attestation statement and signature.
    """


@dataclass
class Envelope:
    statement: bytes
    """
    The attestation statement.

    This is represented as opaque bytes on the wire (encoded as base64),
    but it MUST be an JSON in-toto v1 Statement.
    """

    signature: bytes
    """
    A signature for the above statement, encoded as base64.
    """

@dataclass
class VerificationMaterial:
    certificate: str
    """
    The signing certificate, as `base64(DER(cert))`.
    """

    transparency_entries: list[object]
    """
    One or more transparency log entries for this attestation's signature
    and certificate.
    """

transparency_entries의 각 객체에 대한 전체 데이터 모델은 부록 2: 투명성 로그 항목의 데이터 모델에 제공됩니다. 증명 객체는 하나 이상의 투명성 로그 항목을 포함하는 것이 좋으며, 서명된 시간의 다른 출처(예: RFC 3161 Time Stamping Authority 또는 Roughtime 서버)를 위한 추가 키를 포함할 수 있습니다.

증명 객체에는 버전이 지정되며, 이 PEP는 버전 1을 지정합니다. 각 버전은 불필요한 암호화 민첩성을 최소화하기 위해 하나의 암호화 스위트에 연결됩니다. 버전 1에서 스위트는 다음과 같습니다.

인증서는 X.509 인증서로 지정되며, RFC 5280의 프로파일을 준수합니다.
메시지 서명 알고리즘은 ECDSA이며, 공개 키에는 P-256 곡선을 사용하고 암호화 다이제스트 함수에는 SHA-256을 사용합니다.

이후 PEP에서는 새 버전 번호를 선택하여 이 스위트와 증명 객체의 전체 형태를 변경할 수 있습니다.

증명 명세문 및 서명 생성

증명 명세문은 증명 객체 내에서 암호학적으로 서명되는 실제 주장입니다(즉, envelope.statement입니다).

증명 명세문은 JSON 형식의 v1 in-toto Statement object로 인코딩됩니다. 명세문을 직렬화할 때는 불투명한 바이너리 블롭으로 처리하여 정규화가 필요하지 않도록 합니다. JSON으로 인코딩된 명세문의 예는 부록 4: 증명 문 예시에 제공됩니다.

증명 명세문은 v1 in-toto Statement인 것에 더하여 다음과 같은 제약을 받습니다.

in-toto subject에는 단일 subject만 포함해야 합니다.
subject[0].name은 배포판의 파일 이름이며, 반드시 유효한 source distribution 또는 wheel distribution 파일 이름이어야 합니다.
subject[0].digest에는 SHA-256 다이제스트가 포함되어야 합니다. 다른 다이제스트도 포함할 수 있습니다. 다이제스트는 16진수 문자열로 표현되어야 합니다.
다음 predicateType값이 지원됩니다:
- SLSA Provenance: https://slsa.dev/provenance/v1
- PyPI Publish Attestation: https://docs.pypi.org/attestations/publish/v1

이 명세에 대한 서명은 v1 DSSE signature protocol을 사용하여 구성하며, PAYLOAD_TYPE은 application/vnd.in-toto+json이고 PAYLOAD_BODY는 위 명세를 JSON으로 인코딩한 것입니다. 다른 PAYLOAD_TYPE은 허용되지 않습니다.

프로비넌스 객체

색인은 업로드된 증명과 함께 이를 검증하는 데 도움이 되는 메타데이터를 JSON 직렬화 객체 형태로 제공합니다.

이러한 프로비넌스 객체는 위에서 설명한 Simple Index와 JSON 기반 Simple API 모두를 통해 사용할 수 있으며, 다음과 같은 구조를 가집니다:

{
    "version": 1,
    "attestation_bundles": [
      {
        "publisher": {
          "kind": "important-ci-service",
          "claims": {},
          "vendor-property": "foo",
          "another-property": 123
        },
        "attestations": [
          { /* attestation 1 ... */ },
          { /* attestation 2 ... */ }
        ]
      }
    ]
}

또는 의사 코드로 표현하면:

@dataclass
class Publisher:
    kind: string
    """
    The kind of Trusted Publisher.
    """

    claims: object | None
    """
    Any context-specific claims retained by the index during Trusted Publisher
    authentication.
    """

    _rest: object
    """
    Each publisher object is open-ended, meaning that it MAY contain additional
    fields beyond the ones specified explicitly above. This field signals that,
    but is not itself present.
    """

@dataclass
class AttestationBundle:
    publisher: Publisher
    """
    The publisher associated with this set of attestations.
    """

    attestations: list[Attestation]
    """
    The set of attestations included in this bundle.
    """

@dataclass
class Provenance:
    version: Literal[1]
    """
    The provenance object's version, which is always 1.
    """

    attestation_bundles: list[AttestationBundle]
    """
    One or more attestation "bundles".
    """

version은 1입니다. 증명 객체와 마찬가지로 프로비넌스 객체에도 버전이 지정되며, 이 PEP에서는 1만 정의합니다.
attestation_bundles는 하나 이상의 증명 “번들”을 포함하는 필수 JSON 배열입니다. 각 번들은 서명 식별자(예: Trusted Publishing ID)에 대응하며, 하나 이상의 증명 객체를 포함합니다.
Publisher모델에 설명된 것처럼 각 AttestationBundle.publisher객체는 해당 Trusted Publisher에 따라 다르지만 최소한 다음을 포함해야 합니다:
- kind 키는 Trusted Publisher의 종류를 고유하게 식별하는 JSON 문자열이어야 합니다.
- claims 키는 인덱스가 Trusted Publisher 인증 중 보존한 컨텍스트별 클레임을 포함하는 JSON 객체여야 합니다.
게시자 객체의 나머지 모든 키는 게시자별 키입니다. 게시자 객체의 전체 예시는 부록 1: Trusted Publisher 표현 예시에 제공됩니다.

각 증명 객체 배열은 업로드 엔드포인트 변경 사항 및 프로비넌스 객체의 변경 사항에 설명된 대로 업로드 시 attestations필드를 통해 업로더가 제공한 attestations배열의 상위 집합입니다.

프로비넌스 객체의 변경 사항

프로비넌스 객체는 불변하지 않으며 시간이 지남에 따라 변경될 수 있습니다. 프로비넌스 객체가 변경되는 이유는 다음을 포함하지만 이에 국한되지 않습니다:

기존에 존재하는 서명 식별자에 대한 새 증명 추가: 색인은 기존에 존재하는 서명 식별자가 추가 증명을 제공하도록 허용할 MAY 수 있으며, 여기에는 이미 업로드된 파일에 대한 최신 증명 버전이 포함될 수 있습니다.
새 서명 식별자 및 관련 증명 추가: 색인은 파일 업로더 이외의 출처(예: 제3자 감사자 또는 색인 자체)에서 제공하는 증명을 지원할 MAY 수 있습니다. 이러한 증명은 비동기적으로 수행될 수 있으며, 이에 따라 색인은 사후에 post facto 프로비넌스 객체에 증명을 삽입해야 할 수 있습니다.

증명 검증

배포 파일에 대해 증명 객체를 검증하려면 다음 각 항목을 검증해야 합니다:

version은 1입니다. 검증자는 다른 모든 버전을 거부해야 합니다.
verification_material.certificate는 a priori 신뢰된 기관(예를 들어 검증 클라이언트에 이미 존재하는 신뢰 루트)이 발급한 유효한 서명 인증서입니다.
verification_material.certificate는 적절한 서명 주체를 식별하며, 예를 들어 패키지를 게시한 Trusted Publisher의 머신 식별자가 이에 해당합니다.
envelope.statement는 유효한 in-toto v1 Statement이며, 해당 주체와 다이제스트는 배포 파일의 파일 이름 및 내용과 반드시 일치해야 합니다. 배포 파일의 파일 이름에 대해서는 적절한 소스 배포 파일 또는 휠 파일 이름 형식을 사용해 파싱하여 일치를 반드시 확인해야 합니다. Statement의 주체는 동등하지만 정규화된 형태일 수 있기 때문입니다.
envelope.signature는 verification_material.certificate에 대응하는 envelope.statement의 유효한 서명이며, v1 DSSE signature protocol을 통해 재구성된 것입니다.

위의 필수 단계에 더하여, 검증자는 정책에 따라 verification_material.transparency_entries를 추가로 검증할 수도 있습니다. 예를 들어 하나 이상의 투명성 로그 항목 또는 항목 수의 임계값을 요구할 수 있습니다. 투명성 항목을 검증할 때 검증자는 각 항목의 포함 시간이 서명 인증서의 유효 기간 내에 있는지 반드시 확인해야 합니다.

보안 관련 영향

이 PEP는 주로 “기계적” 성격을 가지며, 증명의 유효성, 증명 간 임계값 등의 상위 수준 보안 “정책”을 명시하지 않고 검증 가능한 디지털 증명을 구조화하고 제공하기 위한 레이아웃을 제공합니다.

증명의 암호화 민첩성

알고리즘 민첩성은 암호화 체계에서 악용 가능한 취약점의 일반적인 원인입니다. 이 PEP는 알고리즘 민첩성을 두 가지 방식으로 제한합니다.

모든 알고리즘은 기하학적인 매개변수 모음이 아니라 단일 스위트로 지정됩니다. 따라서 공격자가 강력한 서명 알고리즘과 취약한 해시 함수를 선택하여 체계 전체를 손상시키는 일이 불가능합니다(예를 들어).
증명 객체에는 버전이 부여되며, 해당 버전에 지정된 알고리즘 스위트만 포함할 수 있습니다. 향후 특정 스위트가 안전하지 않은 것으로 간주되면, 클라이언트는 해당 스위트를 포함하는 증명의 검증을 일괄적으로 거부하거나 조건부로 처리할 수 있습니다.

색인 신뢰

이 PEP는 색인 자체에 대한 신뢰를 증가시키지도 감소시키지도 않습니다. 패키지 내용을 수정할 수 있는 부정직한 색인은 패키지 증명을 부정직하게 수정하거나 누락할 수도 있으므로, 색인은 여전히 수정되지 않은 패키지 배포 파일을 정직하게 제공한다고 사실상 신뢰됩니다. 따라서 이 PEP가 전제하는 색인 신뢰는 PGP 및 휠 서명과 같은 이전 메커니즘에서 명시되지 않았던 전제와 동등합니다.

이 PEP는 PEP 458 및/또는 PEP 480과 같은 향후 색인 신뢰 메커니즘을 막거나 배제하지 않습니다.

권고 사항

이 PEP는 증명 객체에 서명 인증서의 주장된 유효 기간을 뒷받침하는, 서명된 시간의 검증 가능한 출처를 하나 이상 포함하도록 권고하지만 이를 의무화하지는 않습니다. 이 PEP를 구현하는 색인은 이 요구 사항을 엄격하게 적용하도록 선택할 수 있습니다.

부록 1: Trusted Publisher 표현 예시

이 부록은 간단한 JSON API project.files[].provenance 목록 내 publisher키의 가상 예시를 제공합니다.

"publisher": {
    "kind": "GitHub",
    "claims": {
        "ref": "refs/tags/v1.0.0",
        "sha": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
    },
    "repository_name": "HolyGrail",
    "repository_owner": "octocat",
    "repository_owner_id": "1",
    "workflow_filename": "publish.yml",
    "environment": null
}

부록 2: 투명성 로그 항목의 데이터 모델

이 부록에는 증명 객체의 투명성 로그 항목을 위한 의사코드 데이터 모델이 포함되어 있습니다. 각 투명성 로그 항목은 서명된 포함 시간의 출처 역할을 하며, 온라인 또는 오프라인으로 검증할 수 있습니다.

@dataclass
class TransparencyLogEntry:
    log_index: int
    """
    The global index of the log entry, used when querying the log.
    """

    log_id: str
    """
    An opaque, unique identifier for the log.
    """

    entry_kind: str
    """
    The kind (type) of log entry.
    """

    entry_version: str
    """
    The version of the log entry's submitted format.
    """

    integrated_time: int
    """
    The UNIX timestamp from the log from when the entry was persisted.
    """

    inclusion_proof: InclusionProof
    """
    The actual inclusion proof of the log entry.
    """


@dataclass
class InclusionProof:
    log_index: int
    """
    The index of the entry in the tree it was written to.
    """

    root_hash: str
    """
    The digest stored at the root of the Merkle tree at the time of proof
    generation.
    """

    tree_size: int
    """
    The size of the Merkle tree at the time of proof generation.
    """

    hashes: list[str]
    """
    A list of hashes required to complete the inclusion proof, sorted
    in order from leaf to root. The leaf and root hashes are not themselves
    included in this list; the root is supplied via `root_hash` and the client
    must calculate the leaf hash.
    """

    checkpoint: str
    """
    The signed tree head's signature, at the time of proof generation.
    """

    cosigned_checkpoints: list[str]
    """
    Cosigned checkpoints from zero or more log witnesses.
    """

부록 3: 간단한 JSON API의 크기 고려 사항

이 PEP의 이전 초안에서는 각 provenance object를 JSON Simple API의 적절한 부분에 직접 삽입해야 했습니다.

이 PEP의 현재 버전에서는 대신 provenance 객체의 SHA-256 다이제스트를 삽입합니다. 이는 크기 및 네트워크 대역폭을 고려한 것입니다:

증명 객체의 일반적인 크기는 JSON 기준 약 5.3KB일 것으로 추정합니다.
패키지 색인이 최종적으로 배포 파일당 약 3개의 증명을 호스팅할 것으로 보수적으로 추정하며, 이는 결합된 출처 객체당 약 15.9KB의 JSON에 해당합니다.
2024년 5월 기준으로 PyPI의 평균 프로젝트에는 약 21개의 배포 파일이 있습니다. 이 평균은 시간이 지남에 따라 증가할 것으로 보수적으로 예상합니다.
이 수치를 종합하면 일반적인 프로젝트는 60~70개의 증명을 호스팅하게 될 수 있으며, “project detail” 엔드포인트에 약 339KB의 추가 JSON이 포함될 수 있음을 의미합니다.

프로젝트에 수백 또는 수천 개의 릴리스가 있거나 릴리스당 수십 개의 파일이 있는 “병적인” 경우에는 이 수치가 상당히 더 나빠집니다.

부록 4: 증명 문 예시

SHA-256 다이제스트가 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855인 소스 배포판 sampleproject-1.2.3.tar.gz이 주어졌을 때, 다음은 JSON 객체로 표현한 적절한 in-toto Statement입니다:

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "sampleproject-1.2.3.tar.gz",
      "digest": {"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}
    }
  ],
  "predicateType": "https://some-arbitrary-predicate.example.com/v1",
  "predicate": {
    "something-else": "foo"
  }
}

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.