atomic:

روش انتقال منسوخ‌شده atomic: به تصاویری در یک Atomic Registry اشاره دارد.

دامنه‌های پشتیبانی‌شده از فرمت hostname[:port][/namespace[/imagestream [:tag]]] استفاده می‌کنند، یعنی یا تعیین نام کامل یک تصویر دارای برچسب (tag)، یا پیشوندی که یک میزبان/فضای‌نام/جریان تصویر (image stream) را نشان می‌دهد، یا عبارتی دارای نویسه عام (wildcard) که با *. شروع می‌شود تا با تمام زیردامنه‌ها مطابقت پیدا کند. برای تطبیق با زیردامنه دارای نویسه عام، *.example.com معتبر است، اما example*.*.com معتبر نیست.

نکته: مقادیر hostname و port به میزبان و درگاه رجیستری کانتینر (که برای مثال در docker pull استفاده می‌شود) اشاره دارند، نه به میزبان و درگاه API در OpenShift.

containers-storage:

دامنه‌های پشتیبانی‌شده دارای قالب [storage-specifier]image-scope هستند.

مقدار [storage-specifier] معمولاً به صورت [graph-driver-name@graph-root] است، مانند [overlay@/var/lib/containers/storage].

مقدار image-scope که با تصویر تکی مطابقت دارد عبارت است از: - یک مرجع نام‌گذاری‌شده Docker به صورت کاملاً بسط‌یافته (fully expanded)، با استفاده از برچسب (tag) یا دایجست (digest). به عنوان مثال، docker.io/library/busybox:latest (نه busybox:latest) - و/یا (بسته به آنچه ورودی کاربر ارائه می‌دهد) @image-id

دامنه‌های عمومی‌تر، پیشوندهای دامنه‌های تصویر تکی هستند و تصویری با دقت کمتر، یا یک مخزن (با حذف شناسه تصویر در ابتدا در صورت وجود؛ سپس دایجست در صورت وجود؛ و در نهایت برچسب در صورت وجود)، یک فضای نام مخزن، یا یک میزبان رجیستری (صرفاً با مشخص کردن نام میزبان و احتمالاً شماره پورت) را تعیین می‌کنند.

در نهایت، دو مشخص‌کننده کامل فضای ذخیره‌سازی که با تمام تصاویر موجود در آن فضا مطابقت دارند، دامنه‌های معتبری هستند: - [graph-driver-name@graph-root] و - [graph-root]

توجه داشته باشید که برخی از ابزارها مانند Podman و Buildah بازنویسی‌های درون‌برنامه‌ای (hard-coded) برای خط‌مشی اعتبارسنجی امضا در عملیات "push" دارند که اجازه انجام این عملیات را صرف‌نظر از پیکربندی policy.json می‌دهد.

dir:

روش انتقال dir: به تصاویری اشاره دارد که در دایرکتوری‌های محلی ذخیره شده‌اند.

دامنه‌های پشتیبانی‌شده، مسیرهای دایرکتوری‌ها هستند (یا شامل یک تصویر تکی، یا زیردایرکتوری‌هایی که احتمالاً شامل تصاویری هستند).

نکته: - مسیرها باید مطلق بوده و فاقد پیوند نمادین (symlink) باشند. مسیرهایی که این الزامات را نقض کنند ممکن است بدون هشدار نادیده گرفته شوند. - دامنه سطح بالا "/" ممنوع است؛ جهت سازگاری با سایر روش‌های انتقال، از دامنه پیش‌فرض "" استفاده کنید.

docker:

روش انتقال docker: به تصاویری در یک رجیستری اشاره دارد که "Docker Registry HTTP API V2" را پیاده‌سازی کرده است.

دامنه‌های منطبق با تصاویر تکی، مراجع نام‌گذاری‌شده Docker به صورت کاملاً بسط‌یافته هستند که از برچسب یا دایجست استفاده می‌کنند. برای مثال، docker.io/library/busybox:latest (نه busybox:latest).

دامنه‌های عمومی‌تر پیشوندهای دامنه‌های تصویر تکی هستند و یک مخزن (با حذف برچسب یا دایجست)، یک فضای نام مخزن، یا یک میزبان رجیستری (فقط با مشخص کردن نام میزبان و احتمالاً شماره پورت) یا یک عبارت دارای نویسه عام که با *. شروع می‌شود برای تطبیق با تمام زیردامنه‌ها (بدون شماره پورت) را مشخص می‌کنند. برای تطبیق با زیردامنه دارای نویسه عام، *.example.com معتبر است، اما example*.*.com معتبر نیست.

docker-archive:

تنها دامنه پیش‌فرض "" پشتیبانی می‌شود.

docker-daemon:

برای مراجعی که از قالب algo:digest استفاده می‌کنند (که به شناسه تصویر اشاره دارد)، فقط دامنه پیش‌فرض "" استفاده می‌شود.

برای تصاویری که از مرجع نام‌گذاری‌شده استفاده می‌کنند، دامنه‌های منطبق با تصاویر تکی به صورت کاملاً بسط‌یافته هستند که از برچسب یا دایجست استفاده می‌کنند. برای مثال، docker.io/library/busybox:latest (نه busybox:latest).

دامنه‌های نام‌گذاری‌شده عمومی‌تر، پیشوندهای دامنه‌های تصویر تکی هستند و یک مخزن (با حذف برچسب یا دایجست)، یک فضای نام مخزن، یا یک میزبان رجیستری (با تعیین نام میزبان و در صورت وجود شماره پورت) یا یک عبارت دارای نویسه عام شروع‌شده با *. برای تطبیق با همه زیردامنه‌ها (بدون شماره پورت) را مشخص می‌کنند. برای تطبیق زیردامنه‌ها، *.example.com معتبر است اما example*.*.com معتبر نیست.

oci:

روش انتقال oci: به تصاویری در دایرکتوری‌های مطابق با "Open Container Image Layout Specification" اشاره دارد.

دامنه‌های پشتیبانی‌شده، مسیرهای دایرکتوری‌ها هستند (یا شامل یک ساختار OCI یا زیردایرکتوری‌هایی که احتمالاً شامل دایرکتوری‌های ساختار OCI هستند). مقدار یادداشت (annotation) مرجع (reference)، در صورت وجود، استفاده نمی‌شود.

نکته: - مسیرها باید مطلق و فاقد پیوند نمادین باشند. مسیرهای ناقض این شرایط ممکن است بدون هشدار نادیده گرفته شوند. - دامنه سطح بالا "/" ممنوع است؛ جهت سازگاری با سایر روش‌های انتقال از دامنه پیش‌فرض "" استفاده کنید.

oci-archive:

دامنه‌های پشتیبانی‌شده، مسیرهای فایل‌های آرشیو OCI و دایرکتوری‌های والد آن‌ها هستند (یا شامل یک آرشیو تکی یا زیردایرکتوری‌هایی که احتمالاً شامل آرشیو هستند). مقدار یادداشت reference، در صورت وجود، استفاده نمی‌شود.

نکته: - مسیرها باید مطلق و فاقد پیوند نمادین باشند. مسیرهای ناقض این شرایط ممکن است بدون هشدار نادیده گرفته شوند. - دامنه سطح بالا "/" ممنوع است؛ از دامنه پیش‌فرض انتقال "" استفاده کنید.

sif:

دامنه‌های پشتیبانی‌شده مسیرهای تصاویر Singularity و دایرکتوری‌های والد آن‌ها هستند (یا شامل تصاویر یا زیردایرکتوری‌هایی که احتمالاً شامل تصویر هستند).

نکته: - مسیرها باید مطلق و بدون پیوند نمادین باشند. مسیرهای ناقض این شرایط ممکن است بدون هشدار نادیده گرفته شوند. - دامنه سطح بالا "/" ممنوع است؛ از دامنه پیش‌فرض "" استفاده کنید.

tarball:

روش انتقال tarball: یک جزئیات پیاده‌سازی از برخی فرآیندهای واردسازی (import) است. تنها دامنه پیش‌فرض "" پشتیبانی می‌شود.

insecureAcceptAnything

یک الزام ساده با نحو زیر:

{"type":"insecureAcceptAnything"}

این الزام هر تصویری را می‌پذیرد (اما توجه داشته باشید که سایر الزامات موجود در آرایه همچنان اعمال می‌شوند).

هنگام تصمیم‌گیری برای پذیرش یک امضای منفرد، این الزام هیچ تأثیری ندارد؛ و باعث پذیرش امضا نیز نمی‌شود.

این گزینه عمدتاً برای دامنه‌هایی کاربرد دارد که نیازی به اعتبارسنجی امضا ندارند؛ از آنجا که آرایه الزامات خط‌مشی نباید خالی باشد، از این الزام برای نشان دادن صریح عدم وجود الزامات استفاده می‌شود.

reject

یک الزام ساده با نحو زیر:

{"type":"reject"}

این الزام هر تصویر و هر امضایی را رد می‌کند.

signedBy

این الزام مستلزم آن است که یک تصویر با استفاده از "امضای ساده (simple signing)" و با یک هویت مورد انتظار امضا شده باشد، یا در صورتی که امضا با هویت و کلید مورد انتظار انجام شده باشد آن را می‌پذیرد.

{
    "type":    "signedBy",
    "keyType": "GPGKeys", /* تنها مقدار پشتیبانی‌شده در حال حاضر */
    "keyPath": "/path/to/local/keyring/file",
    "keyPaths": ["/path/to/local/keyring/file1","/path/to/local/keyring/file2"…],
    "keyData": "base64-encoded-keyring-data",
    "signedIdentity": identity_requirement
}

دقیقاً باید یکی از گزینه‌های keyPath، keyPaths و keyData وجود داشته باشد که شامل یک جاکلیدی (keyring) حاوی یک یا چند کلید عمومی GPG است. تنها امضاهای ایجادشده توسط این کلیدها پذیرفته می‌شوند.

فیلد signedIdentity، که یک شیء JSON است، مشخص می‌کند که امضا چه هویت تصویری را ادعا می‌کند. یکی از گزینه‌های زیر پشتیبانی می‌شود:

• هویت موجود در امضا باید دقیقاً با هویت تصویر مطابقت داشته باشد. توجه داشته باشید که با این حالت، ارجاع به تصویر از طریق دایجست (با امضایی که هویت repository:tag را ادعا می‌کند) با شکست مواجه خواهد شد.

  {"type":"matchExact"}

• اگر هویت تصویر دارای برچسب (tag) باشد، هویت موجود در امضا باید دقیقاً مطابقت داشته باشد؛ اگر هویت تصویر از ارجاع با دایجست استفاده کند، هویت در امضا باید در همان مخزن تصویر باشد (با هر برچسبی).

(توجه داشته باشید که در تصاویر شناسایی‌شده با دایجست، دایجستِ ارجاع حتی قبل از شروع اعتبارسنجی امضا تأیید اعتبار می‌شود.)

{"type":"matchRepoDigestOrExact"}

• هویت در امضا باید در همان مخزن هویت تصویر باشد. این مورد مثلاً برای کشیدن تصویری با برچسب :latest مفید است وقتی که تصویر با برچسبی که نسخه دقیق تصویر را مشخص می‌کند امضا شده باشد.

  {"type":"matchRepository"}

• هویت در امضا باید دقیقاً با یک هویت مشخص‌شده مطابقت داشته باشد. این مورد مثلاً هنگام آینه‌سازی محلی (local mirroring) تصاویری که با هویت عمومی‌شان امضا شده‌اند کاربرد دارد.

  {
      "type": "exactReference",
      "dockerReference": docker_reference_value
  }

• هویت در امضا باید در همان مخزن یک هویت مشخص‌شده باشد. این حالت ویژگی‌های matchRepository و exactReference را با هم ترکیب می‌کند.

  {
      "type": "exactRepository",
      "dockerRepository": docker_repository_value
  }

• نگاشت مجدد پیشوند (Prefix remapping):

اگر هویت تصویر با پیشوند مشخص‌شده مطابقت داشته باشد، آن پیشوند با "پیشوند امضاشده (signed prefix)" جایگزین می‌شود (در غیر این صورت بدون تغییر استفاده می‌شود و نگاشت مجددی رخ نمی‌دهد)؛ سپس تطبیق از معناشناسی matchRepoDigestOrExact که در بالا توضیح داده شد پیروی می‌کند (یعنی اگر هویت تصویر دارای برچسب باشد، هویت در امضا باید دقیقاً مطابقت کند، و اگر از دایجست استفاده کند، مخزن باید مطابقت داشته باشد).

مقادیر prefix و signedPrefix می‌توانند مقادیر host[:port] باشند (که دقیقاً با همان رشته host[:port] مطابقت دارند)، یا فضاهای نام مخزن، یا مخازن (یعنی نباید شامل tag/digest باشند)، و به عنوان پیشوندهای فرم کاملاً بسط‌یافته مطابقت داده می‌شوند. به عنوان مثال، docker.io/library/busybox (نه busybox) برای تعیین آن مخزن تکی، یا docker.io/library (نه یک رشته خالی) برای تعیین فضای نام والدِ docker.io/library/busybox==busybox.

مقدار prefix معمولاً همان دامنه‌ای است که شامل الزام والد signedBy است.

{
    "type": "remapIdentity",
    "prefix": prefix,
    "signedPrefix": prefix,
}

اگر فیلد signedIdentity وجود نداشته باشد، با آن مانند matchRepoDigestOrExact رفتار می‌شود.

نکته: مقادیر matchExact، matchRepoDigestOrExact و matchRepository تنها در صورتی قابل استفاده هستند که هویتی شبیه به هویت داکر توسط روش انتقال ارائه شود. به‌ویژه، روش‌های انتقال dir: و oci: فقط با exactReference یا exactRepository قابل استفاده هستند.

sigstoreSigned

این الزام مستلزم آن است که یک تصویر با استفاده از امضای sigstore با هویت و کلید مورد انتظار امضا شده باشد.

{
    "type":    "sigstoreSigned",
    "keyPath": "/path/to/local/public/key/file",
    "keyPaths": ["/path/to/first/public/key/one", "/path/to/first/public/key/two"],
    "keyData": "base64-encoded-public-key-data",
    "keyDatas": ["base64-encoded-public-key-one-data", "base64-encoded-public-key-two-data"]
    "fulcio": {
        "caPath": "/path/to/local/CA/file",
        "caData": "base64-encoded-CA-data",
        "oidcIssuer": "https://expected.OIDC.issuer/",
        "subjectEmail", "expected-signing-user@example.com",
    },
    "pki": {
        "caRootsPath": "/path/to/local/CARoots/file",
        "caRootsData": "base64-encoded-CARoots-data",
        "caIntermediatesPath": "/path/to/local/CAIntermediates/file",
        "caIntermediatesData": "base64-encoded-CAIntermediates-data",
        "subjectHostname": "expected-signing-hostname.example.com",
        "subjectEmail": "expected-signing-user@example.com"
    },
    "rekorPublicKeyPath": "/path/to/local/public/key/file",
    "rekorPublicKeyPaths": ["/path/to/local/public/key/one","/path/to/local/public/key/two"],
    "rekorPublicKeyData": "base64-encoded-public-key-data",
    "rekorPublicKeyDatas": ["base64-encoded-public-key-one-data","base64-encoded-public-key-two-data"],
    "signedIdentity": identity_requirement
}

دقیقاً باید یکی از فیلدهای keyPath، keyPaths، keyData، keyDatas، fulcio و pki وجود داشته باشد.

اگر keyPath یا keyData وجود داشته باشد، حاوی یک کلید عمومی sigstore است. تنها امضاهای ایجادشده توسط این کلید پذیرفته می‌شوند.

اگر keyPaths یا keyDatas وجود داشته باشد، حاوی کلیدهای عمومی sigstore است. تنها امضاهای ایجادشده توسط هر یک از کلیدهای موجود در لیست پذیرفته می‌شوند.

اگر fulcio وجود داشته باشد، امضا باید مبتنی بر گواهی صادرشده توسط Fulcio باشد. باید یکی از گزینه‌های caPath و caData مشخص شود که شامل کلید عمومی نمونه Fulcio است. هر دو فیلد oidcIssuer و subjectEmail اجباری هستند و دقیقاً ارائه‌دهنده هویت مورد انتظار و هویت کاربری که گواهی Fulcio را دریافت کرده است را مشخص می‌کنند.

اگر pki وجود داشته باشد، امضا باید مبتنی بر یک گواهی X.509 غیر Fulcio باشد. باید یکی از گزینه‌های caRootsPath و caRootsData مشخص شود که شامل گواهی‌های مرجع صدور گواهی (CA) است. تنها یکی از گزینه‌های caIntermediatesPath و caIntermediatesData می‌تواند وجود داشته باشد که شامل گواهی‌های CA میانی است. باید یکی از گزینه‌های subjectEmail و subjectHostname مشخص شود که دقیقاً هویت مورد انتظاری که گواهی برای آن صادر شده را تعیین می‌کند.

حداکثر یکی از rekorPublicKeyPath، rekorPublicKeyPaths، rekorPublicKeyData و rekorPublicKeyDatas می‌تواند وجود داشته باشد؛ در صورت مشخص شدن fulcio، وجود این مورد اجباری است. اگر کلید عمومی Rekor مشخص شده باشد، امضا باید روی یک سرور Rekor بارگذاری شده باشد و امضا باید شامل یک "برچسب زمانی ورودی امضاشده (signed entry timestamp)" (قابل تأیید به‌صورت آفلاین) باشد که وجود رکورد لاگ Rekor را با امضای یکی از کلیدهای عمومی ارائه‌شده اثبات کند.

فیلد signedIdentity همان معناشناسی الزام signedBy توضیح داده شده در بالا را دارد. توجه داشته باشید که امضاهای ایجادشده توسط cosign فقط شامل یک مخزن هستند، بنابراین تنها matchRepository و exactRepository می‌توانند برای پذیرش آن‌ها استفاده شوند (و این کار در برابر جایگزینی یک تصویر امضاشده با یک برچسب غیرمنتظره محافظت نمی‌کند).

برای استفاده از این ویژگی با تصاویری که در رجیستری‌های تصویر میزبانی می‌شوند، گزینه use-sigstore-attachments باید برای رجیستری یا مخزن مربوطه در containers-registries.d(5) کلاینت فعال باشد.

یک سیستم با امنیت معقول و محدودشده

(توجه داشته باشید که کامنت‌های /*…*/ در JSON معتبر نیستند و نباید در خط‌مشی‌های واقعی استفاده شوند.)

{
    "default": [{"type": "reject"}], /* رد کردن هر چیزی که صراحتاً مجاز نشده است */
    "transports": {
        "docker": {
            /* اجازه نصب تصاویر از یک فضای نام مخزن خاص، بدون اعتبارسنجی رمزنگاری.
               این فضای نام شامل تصاویری مانند openshift/hello-openshift و openshift/origin است. */
            "docker.io/openshift": [{"type": "insecureAcceptAnything"}],
            /* به همین ترتیب، اجازه نصب تصاویر "رسمی" busybox. توجه کنید که چگونه
               فرم کاملاً بسط‌یافته، با /library/ صریح، باید استفاده شود. */
            "docker.io/library/busybox": [{"type": "insecureAcceptAnything"}],
            /* اجازه نصب تصاویر از تمام زیردامنه‌ها */
            "*.temporary-project.example.com": [{"type": "insecureAcceptAnything"}],
            /* یک مخزن امضاشده با sigstore */
            "hostname:5000/myns/sigstore-signed-with-full-references": [
                {
                    "type": "sigstoreSigned",
                    "keyPath": "/path/to/sigstore-pubkey.pub"
                }
            ],
            /* یک مخزن امضاشده با sigstore با استفاده از سرورهای عمومی Fulcio+Rekor.
               کلیدهای عمومی سرورهای عمومی را می‌توان از آدرس زیر دریافت کرد:
               https://github.com/sigstore/sigstore/tree/main/pkg/tuf/repository/targets . */
            "hostname:5000/myns/sigstore-signed-fulcio-rekor": [
                {
                    "type": "sigstoreSigned",
                    "fulcio": {
                        "caPath": "/path/to/fulcio_v1.crt.pem",
                        "oidcIssuer": "https://github.com/login/oauth",
                        "subjectEmail": "test-user@example.com"
                    },
                    "rekorPublicKeyPath": "/path/to/rekor.pub",
                }
            ],
            /* یک مخزن امضاشده با Sigstore با استفاده از گواهی تولیدشده توسط یک زیرساخت کلید عمومی سفارشی. */
            "hostname:5000/myns/sigstore-signed-byopki": [
                {
                    "type": "sigstoreSigned",
                    "pki": {
                        "caRootsPath": "/path/to/pki_root_crts.pem",
                        "caIntermediatesPath": "/path/to/pki_intermediate_crts.pem",
                        "subjectHostname": "test-user.example.com"
                        "subjectEmail": "test-user@example.com"
                    }
                }
            ],
            /* یک مخزن امضاشده با sigstore، امضاهای ایجادشده توسط /usr/bin/cosign را می‌پذیرد */
            "hostname:5000/myns/sigstore-signed-allows-malicious-tag-substitution": [
                {
                    "type": "sigstoreSigned",
                    "keyPath": "/path/to/sigstore-pubkey.pub",
                    "signedIdentity": {"type": "matchRepository"}
                }
            ],
            /* یک مخزن امضاشده با sigstore با استفاده از سرورهای عمومی Fulcio+Rekor،
               امضاهای ایجادشده توسط /usr/bin/cosign را می‌پذیرد.
               کلیدهای عمومی سرورهای عمومی را می‌توان از آدرس زیر دریافت کرد:
               https://github.com/sigstore/sigstore/tree/main/pkg/tuf/repository/targets . */
            "hostname:5000/myns/sigstore-signed-fulcio-rekor- allows-malicious-tag-substitution": [
                {
                    "type": "sigstoreSigned",
                    "fulcio": {
                        "caPath": "/path/to/fulcio_v1.crt.pem",
                        "oidcIssuer": "https://github.com/login/oauth",
                        "subjectEmail": "test-user@example.com"
                    },
                    "rekorPublicKeyPath": "/path/to/rekor.pub",
                    "signedIdentity": { "type": "matchRepository" }
                }
            ]
              /* سایر تصاویر :docker از خط‌مشی پیش‌فرض سراسری استفاده کرده و رد می‌شوند */
        },
        "dir": {
            "": [{"type": "insecureAcceptAnything"}] /* اجازه به هر تصویری که مبدأ آن در دایرکتوری‌های محلی است */
        },
        "atomic": {
            /* حالت رایج: استفاده از یک کلید شناخته‌شده برای یک مخزن یا مجموعه‌ای از مخازن */
            "hostname:5000/myns/official": [
                {
                    "type": "signedBy",
                    "keyType": "GPGKeys",
                    "keyPath": "/path/to/official-pubkey.gpg"
                }
            ],
            /* یک مثال پیچیده‌تر، برای مخزنی که شامل آینه یک محصول شخص ثالث است
               و باید توسط واحد IT محلی تأیید شود */
            "hostname:5000/vendor/product": [
                { /* الزام به اینکه تصویر توسط ارائه‌دهنده اصلی و با استفاده از مکان مخزن ارائه‌دهنده امضا شده باشد. */
                    "type": "signedBy",
                    "keyType": "GPGKeys",
                    "keyPath": "/path/to/vendor-pubkey.gpg",
                    "signedIdentity": {
                        "type": "exactRepository",
                        "dockerRepository": "vendor-hostname/product/repository"
                    }
                },
                { /* الزام به اینکه تصویر _همچنین_ توسط یک بازبین محلی امضا شود. */
                    "type": "signedBy",
                    "keyType": "GPGKeys",
                    "keyPath": "/path/to/reviewer-pubkey.gpg"
                }
            ],
            /* روشی برای آینه‌سازی چندین مخزن از یک ارائه‌دهنده منفرد */
            "private-mirror:5000/vendor-mirror": [
                { /* الزام به اینکه تصویر توسط ارائه‌دهنده اصلی و با استفاده از مکان مخزن ارائه‌دهنده امضا شده باشد.
                     برای مثال، private-mirror:5000/vendor-mirror/productA/image1:latest باید به عنوان
                     vendor.example/productA/image1:latest امضا شده باشد. */
                    "type": "signedBy",
                    "keyType": "GPGKeys",
                    "keyPath": "/path/to/vendor-pubkey.gpg",
                    "signedIdentity": {
                        "type": "remapIdentity",
                        "prefix": "private-mirror:5000/vendor-mirror",
                        "signedPrefix": "vendor.example.com"
                    }
                }
            ]
        }
    }
}

غیرفعال کردن کامل امنیت، اجازه به تمام تصاویر و عدم اعتماد به هرگونه امضا

{
    "default": [{"type": "insecureAcceptAnything"}]
}