العودة إلى التحديثات
New releaseAug 6, 2026

cosign v3.1.3

توقيع الكود والشفافية للحاويات والملفات الثنائية

مشاركة

شعار Cosign

cosign

توقيع حاويات OCI (والتحف الأخرى) باستخدام Sigstore!

Go Report Card e2e-tests CII Best Practices OpenSSF Scorecard

تهدف Cosign إلى جعل التوقيعات بنية تحتية غير مرئية.

يدعم Cosign ما يلي:

  • التوقيع بدون مفاتيح ("Keyless signing") مع هيئة شهادات Fulcio للصالح العام من Sigstore وسجل الشفافية Rekor (الافتراضي)
  • التوقيع عبر الأجهزة و KMS
  • التوقيع باستخدام زوج مفاتيح خاص/عام مشفّر مُولَّد بواسطة cosign
  • توقيع الحاويات والتحقق منها وتخزينها في سجل OCI.
  • إحضار PKI الخاص بك

معلومات

تم تطوير Cosign كجزء من مشروع sigstore. نستخدم أيضًا قناة slack! انقر هنا للحصول على رابط الدعوة.

التثبيت

لتثبيتات Homebrew و Arch و Nix و GitHub Action و Kubernetes، راجع وثائق التثبيت.

للحصول على ثنائيات Linux و macOS، راجع أصول إصدارات GitHub.

🚨 إذا كنت تقوم بتنزيل إصدارات cosign من bucket GCS الخاصة بنا - فيرجى الاطلاع على مزيد من المعلومات حول إشعار الإهمال الصادر في 31 يوليو 2023 🚨

تثبيت المطورين

إذا كان لديك Go 1.22+، يمكنك إعداد بيئة تطوير:```shell $ git clone https://github.com/sigstore/cosign $ cd cosign $ go install ./cmd/cosign $ $(go env GOPATH)/bin/cosign

## المساهمة

إذا كنت مهتمًا بالمساهمة في `cosign`، فيرجى قراءة [وثائق المساهمة](https://github.com/sigstore/cosign/blob/HEAD/CONTRIBUTING.md).

سيركز التطوير المستقبلي لـ Cosign على الإصدار الرئيسي القادم الذي سيعتمد على
[sigstore-go](https://github.com/sigstore/sigstore-go). سيركز المشرفون على تطوير الميزات داخل
sigstore-go. المساهمات في sigstore-go، خاصة فيما يتعلق بالمفاتيح التي توفرها بنفسك (bring-your-own keys) والتوقيع، محل تقدير.
يرجى الاطلاع على [متتبع المشكلات](https://github.com/sigstore/sigstore-go/issues) للحصول على قضايا أولى جيدة.

Cosign 2.x هو إصدار مستقر وسيستمر في تلقي تحديثات ميزات دورية وإصلاحات للأخطاء. طلبات السحب (PRs)
صغيرة النطاق والحجم هي الأكثر احتمالًا للحصول على مراجعة سريعة.

لن يتم قبول طلبات السحب التي تعدل أو تكسر API بشكل كبير. قد يتم قبول طلبات السحب ذات الحجم الكبير التي لا تُحدث تغييرات جذرية، لكنها ستُعتبر ذات أولوية أقل من طلبات السحب في sigstore-go.

## Dockerfile

فيما يلي كيفية تثبيت واستخدام cosign داخل Dockerfile من خلال صورة ghcr.io/sigstore/cosign/cosign:```shell
FROM ghcr.io/sigstore/cosign/cosign:v2.4.1 as cosign-bin

# Source: https://github.com/chainguard-images/static
FROM cgr.dev/chainguard/static:latest
COPY --from=cosign-bin /ko-app/cosign /usr/local/bin/cosign
ENTRYPOINT [ "cosign" ]

البدء السريع

يوضح هذا كيفية:

  • توقيع صورة حاوية باستخدام طريقة "التوقيع بدون مفتاح" الافتراضية القائمة على الهوية (انظر التوثيق لمزيد من المعلومات)
  • التحقق من صورة الحاوية
  • استكشاف تدفقات أوسع لتوقيع/التحقق من blob بدون مفتاح في Sigstore Cosign Quickstart

توقيع حاوية وتخزين التوقيع في السجل

لاحظ أنه يجب عليك دائمًا توقيع الصور بناءً على بصمتها (@sha256:...) بدلاً من وسم (:latest) لأنك بخلاف ذلك قد توقّع شيئًا لم تقصده!```shell cosign sign $IMAGE

Generating ephemeral keys... Retrieving signed certificate...

Note that there may be personally identifiable information associated with this signed artifact.
This may include the email address associated with the account with which you authenticate.
This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later.

By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs. Are you sure you would like to continue? [y/N] y Your browser will now be opened to: https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&code_challenge=OrXitVKUZm2lEWHVt1oQWR4HZvn0rSlKhLcltglYxCY&code_challenge_method=S256&nonce=2KvOWeTFxYfxyzHtssvlIXmY6Jk&redirect_uri=http%3A%2F%2Flocalhost%3A57102%2Fauth%2Fcallback&response_type=code&scope=openid+email&state=2KvOWfbQJ1caqScgjwibzK2qJmb Successfully verified SCT... tlog entry created with index: 12086900 Pushing signature to: $IMAGE

سيطالبك Cosign بالمصادقة عبر OIDC، حيث ستسجّل الدخول باستخدام بريدك الإلكتروني.
في الخلفية، سيطلب cosign شهادة توقيع تعليمات برمجية من سلطة الشهادات Fulcio.
سيتطابق موضوع الشهادة مع البريد الإلكتروني الذي سجّلت الدخول به.
بعد ذلك، سيخزّن cosign التوقيع والشهادة في سجل Rekor للشفافية، ويرفع التوقيع إلى سجل OCI بجانب الصورة التي توقّعها.


### التحقق من حاوية

للتحقق من الصورة، ستحتاج إلى تمرير هوية الشهادة المتوقعة ومُصدِر الشهادة عبر العلامتين `--certificate-identity` و `--certificate-oidc-issuer`:```
cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER

يمكنك أيضاً تمرير تعبير نمطي لهوية الشهادة وعلامات المُصدِر، --certificate-identity-regexp و --certificate-oidc-issuer-regexp.

التحقق من حاوية مقابل مفتاح عام

يُرجع هذا الأمر 0 إذا تم العثور على توقيع واحد على الأقل بتنسيق cosign للصورة يطابق المفتاح العام. انظر إلى الاستخدام المفصّل أدناه للحصول على معلومات وملاحظات حول تنسيقات التوقيع الأخرى.

تتم طباعة أي حمولات صالحة على stdout، بتنسيق json. لاحظ أن هذه الحمولات الموقّعة تتضمن ملخّص صورة الحاوية، وهو ما يسمح لنا بأن نكون متأكدين من أن هذه التوقيعات "المنفصلة" تغطي الصورة الصحيحة.```shell $ cosign verify --key cosign.pub $IMAGE_URI:1h The following checks were performed on these signatures:

  • The cosign claims were validated
  • The signatures were verified against the specified public key {"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null}
### التحقق من حاوية في بيئة معزولة عن الشبكة

**ملاحظة:** هذا القسم غير محدّث.

**ملاحظة:** تتطلب معظم سير عمل التحقق طلب مفاتيح خدمة بشكل دوري من مستودع TUF.
للتحقق المعزول عن الشبكة من التوقيعات باستخدام المثيل العام، ستحتاج إلى استرجاع ملف
[trusted root](https://github.com/sigstore/root-signing/blob/main/targets/trusted_root.json) من مستودع
TUF للإنتاج. ستتغير محتويات هذا الملف دون إشعار. بعدم استخدام TUF، ستحتاج
إلى بناء آليتك الخاصة للحفاظ على تحديث نسختك المعزولة عن الشبكة من هذا الملف.

يمكن لـ Cosign إجراء تحقق غير متصل بالإنترنت تمامًا عن طريق التحقق من [bundle](https://github.com/sigstore/cosign/blob/HEAD/specs/SIGNATURE_SPEC.md#properties) والذي يتم توزيعه عادةً كتعليق توضيحي على manifest الصورة.
طالما أن هذا التعليق التوضيحي موجود، يمكن إجراء التحقق غير المتصل.
يتم دائمًا تضمين تعليق الحزمة هذا افتراضيًا للتوقيع بدون مفتاح، لذا فإن وظيفة `cosign sign` الافتراضية ستتضمن جميع المواد اللازمة للتحقق غير المتصل.

للتحقق من صورة في بيئة معزولة عن الشبكة، يجب أن تكون الصورة والتوقيعات متاحة محليًا على نظام الملفات.

يمكن حفظ صورة محليًا باستخدام `cosign save` (لاحظ، يجب تنفيذ هذه الخطوة مع اتصال بالشبكة):```
cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir

الآن، في بيئة معزولة عن الشبكة، يمكن التحقق من هذه الصورة المحلية:```shell cosign verify
--certificate-identity $CERT_IDENTITY
--certificate-oidc-issuer $CERT_OIDC_ISSUER
--offline=true
--new-bundle-format=false \ # for artifacts signed without the new protobuf bundle format --trusted-root ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json \ # default location of trusted root --local-image ./path/to/dir

ستحتاج إلى تمرير قيم متوقعة لكل من `$CERT_IDENTITY` و`$CERT_OIDC_ISSUER` للتحقق من هذه الصورة بشكل صحيح.
إذا قمت بالتوقيع باستخدام زوج مفاتيح، فسيعمل نفس الأمر، بافتراض توفر مادة المفتاح العام محليًا:```
cosign verify --key cosign.pub --offline --local-image ./path/to/dir

التوقيع على blob والتحقق منه استنادًا إلى الهوية

استخدم توقيع blob بدون مفتاح (cosign sign-blob بدون --key) وتحقق من هوية الموقِّع المتوقعة:```shell $ cosign sign-blob artifact --bundle artifact.sigstore.json --yes $ cosign verify-blob artifact
--bundle artifact.sigstore.json
--certificate-identity "https://github.com/ORG/REPO/.github/workflows/release.yml@refs/heads/main"
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"

### استكشاف الأخطاء وإصلاحها

إذا واجهت مشكلات مع Cosign، تأكد أولاً من أنك تستخدم إصدارًا حديثًا: يدعم مشروع Cosign بنشاط أحدث إصدار بالإضافة إلى آخر إصدار في سلسلة v2.

#### المشكلات الشائعة والحلول

1. يفشل التحقق مع `failed to verify timestamps: threshold not met for verified log entry integrated timestamps: 0 < 1`: قد تكون تتحقق من توقيع يتطلب دعم طوابع RFC3161 الزمنية
   * قم بالترقية إلى أحدث إصدار من Cosign أو
   * مع Cosign 2.6.x، استخدم `--use-signed-timestamps`
1. يفشل التحقق مع `no signatures found`: قد تكون تتحقق من توقيع صورة يتطلب دعم سجل الشفافية Rekor v2
   * قم بالترقية إلى أحدث إصدار من Cosign
1. يفشل التوقيع مع أخطاء HTTP: يعتمد التوقيع باستخدام Cosign على خدمات Sigstore متعددة. قد تكون إعادة المحاولة عند الفشل حلاً بديلاً مفيدًا إذا فشلت أي من هذه الخدمات — كما أن فتح مشكلات (issues) للإخفاقات المحددة محل تقدير

#### مشكلتي شيء آخر

يرجى فتح [مشكلة](https://github.com/sigstore/cosign/issues/new/choose) أو السؤال في [قناة slack](#info).

## العمل مع المخرجات الأخرى

سجلات OCI مفيدة لتخزين أكثر من مجرد صور الحاويات!
تتضمن `Cosign` أيضًا بعض الأدوات المساعدة لنشر المخرجات العامة، بما في ذلك الملفات الثنائية والبرامج النصية وملفات التكوين باستخدام بروتوكول OCI.

يوضح هذا القسم كيفية الاستفادة من هذه الأدوات لإنشاء نظام توزيع مخرجات سهل الاستخدام ومتوافق مع الإصدارات السابقة ويتكامل جيدًا مع بقية Sigstore.

انظر [التوثيق](https://docs.sigstore.dev/cosign/signing/other_types/) لمزيد من المعلومات.

### Blobs

يمكنك نشر مخرجًا باستخدام `cosign upload blob`:```shell
$ echo "my first artifact" > artifact
$ BLOB_SUM=$(shasum -a 256 artifact | cut -d' ' -f 1) && echo "$BLOB_SUM"
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626
$ BLOB_NAME=my-artifact-$(uuidgen | head -c 8 | tr 'A-Z' 'a-z')
$ BLOB_URI=ttl.sh/$BLOB_NAME:1h

$ BLOB_URI_DIGEST=$(cosign upload blob -f artifact $BLOB_URI) && echo "$BLOB_URI_DIGEST"
Uploading file from [artifact] to [ttl.sh/my-artifact-f42c22e0:5m] with media type [text/plain]
File [artifact] is available directly at [ttl.sh/v2/my-artifact-f42c22e0/blobs/sha256:c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626]
Uploaded image to:
ttl.sh/my-artifact-f42c22e0@sha256:790d47850411e902aabebc3a684eeb78fcae853d4dd6e1cc554d70db7f05f99f

يمكن لمستخدميك تنزيله من رابط "direct" باستخدام أدوات قياسية مثل curl أو wget:```shell $ curl -L ttl.sh/v2/$BLOB_NAME/blobs/sha256:$BLOB_SUM > artifact-fetched

الخلاصة مدمجة مباشرة في الرابط، حتى يمكنهم التحقق منها أيضًا:```shell
$ cat artifact-fetched | shasum -a 256
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626  -

يمكنك توقيعه باستخدام الأمر العادي cosign sign والخيارات:```shell $ cosign sign --key cosign.key $BLOB_URI_DIGEST Enter password for private key: Pushing signature to: ttl.sh/my-artifact-f42c22e0

كالعادة، تأكد من الإشارة إلى أي صور تقوم بتوقيعها من خلال digest الخاص بها للتأكد من أنك لا توقّع الشيء الخطأ!

#### حزم Tekton

يمكن تحميل حزم [Tekton](https://tekton.dev) وإدارتها داخل سجل OCI.
المواصفات موجودة [هنا](https://tekton.dev/docs/pipelines/tekton-bundle-contracts/).
هذا يعني أنه يمكن أيضًا توقيعها والتحقق منها باستخدام `cosign`.

يمكن حاليًا تحميل حزم Tekton باستخدام [tkn cli](https://github.com/tektoncd/cli)، لكننا قد نضيف هذا الدعم إلى
`cosign` في المستقبل.```shell
$ tkn bundle push us.gcr.io/dlorenc-vmtest2/pipeline:latest -f task-output-image.yaml
Creating Tekton Bundle:
        - Added TaskRun:  to image

Pushed Tekton Bundle to us.gcr.io/dlorenc-vmtest2/pipeline@sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155
$ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/pipeline@sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155
Enter password for private key:
tlog entry created with index: 5086
Pushing signature to: us.gcr.io/dlorenc-vmtest2/demo:sha256-124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155.sig

WASM

يمكن أيضًا تخزين وحدات Web Assembly في سجل OCI، باستخدام هذه المواصفات.

يمكن لـ Cosign رفع هذه الوحدات باستخدام الأمر cosign wasm upload:```shell $ cosign upload wasm -f hello.wasm us.gcr.io/dlorenc-vmtest2/wasm $ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/wasm@sha256:9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812 Enter password for private key: tlog entry created with index: 5198 Pushing signature to: us.gcr.io/dlorenc-vmtest2/wasm:sha256-9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812.sig

#### eBPF

يمكن أيضًا تخزين وحدات [eBPF](https://ebpf.io) في سجل OCI، باستخدام هذه [المواصفة](https://github.com/solo-io/bumblebee/tree/main/spec).

تم بناء الصورة أدناه باستخدام أداة `bee`. يمكن العثور على مزيد من المعلومات [هنا](https://github.com/solo-io/bumblebee/).

يمكن لـ Cosign بعد ذلك توقيع هذه الصور كما يفعل مع أي صورة OCI أخرى.```shell
$ bee build ./examples/tcpconnect/tcpconnect.c localhost:5000/tcpconnect:test
$ bee push localhost:5000/tcpconnect:test
$ cosign sign  --key cosign.key localhost:5000/tcpconnect@sha256:7a91c50d922925f152fec96ed1d84b7bc6b2079c169d68826f6cf307f22d40e6
Enter password for private key:
Pushing signature to: localhost:5000/tcpconnect
$ cosign verify --key cosign.pub localhost:5000/tcpconnect:test

Verification for localhost:5000/tcpconnect:test --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key

[{"critical":{"identity":{"docker-reference":"localhost:5000/tcpconnect"},"image":{"docker-manifest-digest":"sha256:7a91c50d922925f152fec96ed1d84b7bc6b2079c169d68826f6cf307f22d40e6"},"type":"cosign container image signature"},"optional":null}]

شهادات In-Toto

يدعم Cosign أيضًا بشكل مدمج شهادات in-toto. يتم تعريف مواصفات هذه الشهادات هنا.

يمكنك إنشاء وتوقيع واحدة من ملف مسند محلي باستخدام الأوامر التالية:```shell $ cosign attest --predicate --key cosign.key $IMAGE_URI_DIGEST

جميع أنظمة إدارة المفاتيح القياسية مدعومة.
يتم توقيع الحمولات باستخدام مواصفة توقيع DSSE، المعرفة [هنا](https://github.com/secure-systems-lab/dsse).

للتحقق:```shell
$ cosign verify-attestation --key cosign.pub $IMAGE_URI

الاستخدام التفصيلي

راجع وثائق الاستخدام لمزيد من المعلومات.

الرموز المعتمدة على العتاد

راجع وثائق الرموز المادية للحصول على معلومات حول كيفية استخدام cosign مع العتاد.

دعم السجلات

يستخدم cosign go-containerregistry للتفاعل مع السجلات، وهو يتمتع بتوافق ممتاز بشكل عام، ولكن قد تكون لبعض السجلات خصائص خاصة.

حاليًا، تم اختبار cosign ويعمل مع السجلات التالية:

  • AWS Elastic Container Registry
  • GCP's Artifact Registry and Container Registry
  • Docker Hub
  • Azure Container Registry
  • JFrog Artifactory Container Registry
  • The CNCF distribution/distribution Registry
  • GitLab Container Registry
  • GitHub Container Registry
  • The CNCF Harbor Registry
  • Digital Ocean Container Registry
  • Sonatype Nexus Container Registry
  • Alibaba Cloud Container Registry
  • Red Hat Quay Container Registry 3.6+ / Red Hat quay.io
  • Elastic Container Registry
  • IBM Cloud Container Registry
  • Cloudsmith Container Registry
  • The CNCF zot Registry
  • OVHcloud Managed Private Registry

نهدف إلى دعم واسع للسجلات. لتوقيع الصور في السجلات التي لا تدعم بعد بشكل كامل أنواع وسائط OCI، قد يحتاج المرء إلى استخدام COSIGN_DOCKER_MEDIA_TYPES للرجوع إلى ما يعادلها القديم. على سبيل المثال:```shell COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image@$DIGEST

يرجى المساعدة في الاختبار والإبلاغ عن الأخطاء إذا رأيت مشكلات!
يمكن العثور على التعليمات في [قضية التتبع](https://github.com/sigstore/cosign/issues/40).

## تحذيرات

### ميزات مفقودة عمدًا

يولّد `cosign` مفاتيح ECDSA-P256 فقط ويستخدم تجزئات SHA256، لكل من التوقيع غير المفتاحي المؤقت (keyless signing) والتوقيع بالمفاتيح المُدارة.
تُخزَّن المفاتيح بصيغة PKCS8 بترميز PEM.
ومع ذلك، يمكنك استخدام `cosign` لتخزين واسترجاع التوقيعات بأي صيغة، ومن أي خوارزمية.

### أشياء ينبغي أن تتغير على الأرجح

#### صيغ الحمولة (Payload)

يدعم `cosign` فقط صيغة [simple signing](https://www.redhat.com/en/blog/container-image-signing) الخاصة بـ Red Hat للحمولات.
وهي تبدو كالتالي:```json
{
    "critical": {
           "identity": {
               "docker-reference": "testing/manifest"
           },
           "image": {
               "Docker-manifest-digest": "sha256:20be...fe55"
           },
           "type": "cosign container image signature"
    },
    "optional": {
           "creator": "Bob the Builder",
           "timestamp": 1458239713
    }
}

ملاحظة: يمكن توليد ذلك لمرجع صورة باستخدام cosign generate $IMAGE_URI_DIGEST.

يسعدني تبديل هذا التنسيق إلى شيء آخر إذا كان منطقيًا. انظر https://github.com/notaryproject/nv2/issues/40 لأحد الخيارات.

تفاصيل السجل

توقيعات cosign مخزنة ككائنات منفصلة في سجل OCI، مع مرجع ضعيف فقط مرتد إلى الكائن الذي "توقعه". هذا يعني أن هذه العلاقة غير مرئية للسجل، والتوقيعات لن تُحذف أو يُجمَع منها القمامة عند حذف الصورة. وبالمثل، يمكن نسخها بسهولة من بيئة إلى أخرى، لكن هذا ليس تلقائيًا.

تُخزَّن توقيعات متعددة في قائمة، وهو ما يشكل للأسف حالة سباق اليوم. لإضافة توقيع، ينسق العملاء عملية "قراءة-إلحاق-كتابة"، لذا فإن آخر كتابة ستفوز في حالة التنافس.

تحديد السجل

سيعمل cosign افتراضيًا على تخزين التوقيعات في نفس المستودع الذي توجد به الصورة التي يوقّعها. لتحديد مستودع مختلف للتوقيعات، يمكنك تعيين متغير البيئة COSIGN_REPOSITORY.

سيؤدي ذلك إلى استبدال المستودع في الصورة المقدمة كما يلي:```shell $ export COSIGN_REPOSITORY=gcr.io/my-new-repo $ cosign sign --key cosign.key $IMAGE_URI_DIGEST

إذًا سيتم تخزين التوقيع الخاص بـ `gcr.io/dlorenc-vmtest2/demo` في `gcr.io/my-new-repo/demo:sha256-DIGEST.sig`.

ملاحظة: قد تتوقع السجلات المختلفة تنسيقات مختلفة لـ "المستودع."

* لاستخدام [GCR](https://cloud.google.com/container-registry)، يكفي اسم سجل
  مثل `gcr.io/$REPO`، كما في المثال أعلاه.
* لاستخدام [Artifact Registry](https://cloud.google.com/artifact-registry)،
  حدد اسم صورة كاملًا مثل
  `$LOCATION-docker.pkg.dev/$PROJECT/$REPO/$STORAGE_IMAGE`، وليس مجرد
  مستودع. على سبيل المثال،  ```shell
  $ export COSIGN_REPOSITORY=us-docker.pkg.dev/my-new-repo/demo
  $ cosign sign --key cosign.key $IMAGE_URI_DIGEST

حيث سيتطابق sha256-DIGEST مع الملخّص الخاص بـ gcr.io/dlorenc-vmtest2/demo. تحديد مستودع فقط مثل $LOCATION-docker.pkg.dev/$PROJECT/$REPO لن يعمل في Artifact Registry.

مواصفات التوقيع

cosign مستوحى من أدوات مثل minisign و signify.

تُخزَّن المفاتيح الخاصة المولَّدة في صيغة PEM. تُشفَّر المفاتيح باستخدام كلمة مرور عبر scrypt كـ KDF و nacl/secretbox للتشفير.

تحتوي على ترويسة PEM بصيغة ENCRYPTED SIGSTORE PRIVATE KEY:```shell -----BEGIN ENCRYPTED SIGSTORE PRIVATE KEY----- ... -----END ENCRYPTED SIGSTORE PRIVATE KEY-----

تُخزَّن المفاتيح العامة على القرص بتنسيق PKIX القياسي المُرمَّز بـ PEM مع ترويسة `PUBLIC KEY`.```
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99
QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw==
-----END PUBLIC KEY-----

مواصفات التخزين

يخزّن cosign التوقيعات في سجل OCI، ويستخدم اصطلاح تسمية (وسم يعتمد على sha256 لما نوقّعه) لتحديد موقع فهرس التوقيع.

reg.example.com/ubuntu@sha256:703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715 له توقيعات موجودة في reg.example.com/ubuntu:sha256-703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715.sig

بشكل تقريبي (مع تجاهل المنافذ في اسم المضيف): استخدم s/:/-/g و s/@/:/g للعثور على فهرس التوقيع.

انظر شروط السباق لبعض الملاحظات حول هذه الاستراتيجية.

يمكن للتنفيذات البديلة استخدام سجلات الشفافية، أو نظام الملفات المحلي، أو مستودعًا منفصلاً، أو مرجعًا صريحًا إلى فهرس توقيع، أو واجهة برمجة تطبيقات جديدة للسجل، أو grafeas، وما إلى ذلك.

مواضيع التوقيع

cosign يعمل حاليًا فقط مع القطع الأثرية المخزَّنة كـ "manifests" في السجل. الآلية المقترحة مرنة بما يكفي لدعم توقيع أي شيء.

دعم KMS

يدعم cosign استخدام مزوّد KMS لإنشاء المفاتيح وتوقيعها. حاليًا يدعم cosign كلاً من Hashicorp Vault و AWS KMS و GCP KMS و Azure Key Vault، ونأمل في دعم المزيد مستقبلًا!

تتوفر مزوّدات KMS إضافية كمكوّنات إضافية خارجية، مثل OVHcloud KMS.

راجع وثائق KMS لمزيد من التفاصيل.

القطع الأثرية في OCI

ادفع قطعة أثرية إلى سجل باستخدام oras (في هذه الحالة، cosign نفسه!):```shell $ oras push us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact ./cosign Uploading f53604826795 cosign Pushed us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact Digest: sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef

الآن قم بتوقيعه! باستخدام `cosign` بالطبع:```shell
$ cosign sign --key cosign.key us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef
Enter password for private key:
Pushing signature to: us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact:sha256-551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef.sig

أخيرًا، تحقق من cosign باستخدام cosign مرة أخرى:```shell $ cosign verify --key cosign.pub us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef The following checks were performed on each of these signatures:

  • The cosign claims were validated
  • The claims were present in the transparency log
  • The signatures were integrated into the transparency log when the certificate was valid
  • The signatures were verified against the specified public key
  • The code-signing certificate was verified using trusted certificate authority certificates

{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null}

## الأسئلة الشائعة

### لماذا لا نستخدم Notary v2

من الصعب الإجابة على هذا بإيجاز.
يحتوي هذا المنشور على بعض المقارنات:

[Notary V2 و Cosign](https://medium.com/@dlorenc/notary-v2-and-cosign-b816658f044d)

إذا وجدت منشورات مقارنة أخرى، فيرجى إرسال طلب سحب (PR) هنا وسنقوم بربطها جميعًا.

### لماذا لا نستخدم توقيع containers/image

توقيع `containers/image` قريب من `cosign`، ونعيد استخدام تنسيقات الحمولة.
يختلف `cosign` في أنه يوقّع بمفاتيح ECDSA-P256 بدلاً من PGP، ويخزّن
التوقيعات في السجل (registry).

### لماذا لا نستخدم TUF؟

أعتقد أن هذه الأداة مكمّلة لـ TUF، ويمكن استخدامهما معًا.
لم أجرب ذلك بعد، لكن أعتقد أنه يمكننا أيضًا إعادة استخدام سجل لتخزين TUF.

## متطلبات التصميم

* لا خدمات خارجية لتخزين التوقيعات أو الاستعلام عنها أو استرجاعها
* نهدف إلى تحقيق أكبر قدر ممكن من دعم السجلات
* يجب أن يعمل كل شيء عبر واجهة برمجة تطبيقات السجل (Registry API)
* يجب ألا تكون PGP مطلوبة على الإطلاق.
* يجب أن يكون المستخدمون قادرين على العثور على جميع التوقيعات لصورة معينة
* يمكن للموقّعين توقيع صورة بعد الدفع (push)
* يمكن لكيانات متعددة توقيع صورة
* توقيع صورة لا يغيّر الصورة
* تنفيذ نقي بلغة Go

## أفكار مستقبلية

### تغييرات على واجهة برمجة تطبيقات السجل

إن اصطلاح التسمية وأنماط التحديث من نوع قراءة-تعديل-كتابة التي نستخدمها لتخزين الأشياء في
سجل هي، دعنا نقول، "ملتوية" بعض الشيء.
أعتقد أنها الخيار الحقيقي الأفضل (الوحيد) المتاح اليوم، لكن إذا تغيّرت واجهة برمجة تطبيقات السجل
يمكننا تحسين هذه الأمور.

### أنواع أخرى

يمكن لـ `cosign` توقيع أي شيء في سجل.
توضح هذه الأمثلة توقيع صورة واحدة، لكن يمكنك أيضًا توقيع `Index` متعدد المنصات،
أو أي نوع آخر من القطع الأثرية.
يتضمن ذلك Helm Charts و Tekton Pipelines وأي شيء آخر يستخدم حاليًا سجلات OCI
للتوزيع.

هذا يعني أيضًا أنه يمكن تحميل أنواع جديدة من القطع الأثرية إلى سجل وتوقيعها.
من الأنواع المثيرة للاهتمام التي يمكن تخزينها وتوقيعها مستودعات TUF.
لم أجرب ذلك بعد، لكنني متأكد إلى حد ما من أنه يمكن تنفيذ TUF فوق هذا.

### توقيع العلامات (Tag Signing)

توقيعات `cosign` تحمي ملخصات (digests) الكائنات المخزنة في سجل.
يمكن استخدام دعم `annotations` الاختياري (عبر العلم `-a` مع `cosign sign`) لإضافة بيانات
إضافية إلى الحمولة التي يتم توقيعها وحمايتها بالتوقيع.
إحدى حالات الاستخدام لهذا قد تكون توقيع تعيين علامة->ملخص (tag->digest mapping).

إذا كنت تريد الإقرار بأن علامة معينة (أو مجموعة علامات) يجب أن تشير إلى ملخص معين، يمكنك
تشغيل شيء مثل:```shell
$ docker push $IMAGE_URI
The push refers to repository [dlorenc/demo]
994393dc58e7: Pushed
5m: digest: sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870 size: 528
$ TAG=sign-me
$ cosign sign --key cosign.key -a tag=$TAG $IMAGE_URI_DIGEST
Enter password for private key:
Pushing signature to: dlorenc/demo:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870.sig

ثم يمكنك التحقق من أن تعيين tag->digest مشمول أيضًا في التوقيع، باستخدام الخيار -a مع cosign verify. يتحقق هذا المثال من أن الملخص $TAG الذي يشير إلى (sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870) قد تم توقيعه، وأيضًا أن التعليق التوضيحي tag يحمل القيمة sign-me:```shell $ cosign verify --key cosign.pub -a tag=$TAG $IMAGE_URI | jq . { "Critical": { "Identity": { "docker-reference": "" }, "Image": { "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36" }, "Type": "cosign container image signature" }, "Optional": { "tag": "sign-me" } }

يمكن أيضًا إضافة الطوابع الزمنية هنا، لتنفيذ منع هجمات التجميد بأسلوب TUF.

### توقيع الصورة الأساسية/الطبقة

مرة أخرى، يمكن لـ `cosign` توقيع أي شيء في سجل.
يمكنك استخدام `cosign` لتوقيع صورة يُقصد استخدامها كصورة أساسية،
وتضمين تلك البيانات الوصفية للمصدر في الصور المشتقة الناتجة.
يمكن استخدام هذا لفرض أن الصورة مبنية من صورة أساسية مرخّصة.

فكرة تقريبية:
* تحتوي OCI manifests على قائمة مرتبة من `layer` `Descriptors`، والتي يمكن أن تحتوي على تعليقات توضيحية.
  انظر [هنا](https://github.com/opencontainers/image-spec/blob/master/manifest.md) للحصول على
  المواصفات.
* الصورة الأساسية هي قائمة مرتبة من الطبقات التي تُلحق بها طبقات أخرى، بالإضافة إلى
  كائن إعداد أولي يتم تعديله.
  * الصورة المشتقة حرة في حذف/إتلاف/إعادة إنشاء الإعداد بالكامل من صورتها الأساسية،
    لذا فإن توقيع الإعداد سيوفر قيمة محدودة.
* يمكننا توقيع المجموعة الكاملة من الطبقات الأساسية المرتبة، وإرفاق هذا التوقيع كتعليق توضيحي على
  الطبقة **الأخيرة** في الصورة الفرعية الناتجة.

هذا المثال manifest manifest يمثل صورة تم بناؤها من صورة أساسية بطبقتين.
تمت إضافة طبقة إضافية واحدة، لتكوين الصورة النهائية.```json
{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 7023,
    "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 32654,
      "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0"
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 16724,
      "digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b",
      "annotations": {
        "dev.cosign.signature.baseimage": "Ejy6ipGJjUzMDoQFePWixqPBYF0iSnIvpMWps3mlcYNSEcRRZelL7GzimKXaMjxfhy5bshNGvDT5QoUJ0tqUAg=="
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 73109,
      "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736"
    }
  ],
}

لاحظ أن هذا يمكن تطبيقه بشكل تكراري، لعدة صور أساسية وسيطة.

التوقيع المضاد

تُخزَّن توقيعات Cosign (والحمولات المحمية الخاصة بها) كقطع أثرية في السجل. يمكن أيضًا توقيع كائنات التوقيع هذه، مما ينتج عنه قطعة أثرية جديدة، "بتوقيع مضاد". هذا "التوقيع المضاد" يحمي التوقيع (أو مجموعة التوقيعات) و القطعة الأثرية المشار إليها، مما يسمح له بالعمل كإثبات على التوقيعات نفسها.

قبل أن نوقّع قطعة أثرية التوقيع، نمنحها أولاً اسمًا سهل التذكر حتى نتمكن من العثور عليها لاحقًا.```shell $ cosign sign --key cosign.key -a sig=original $IMAGE_URI_DIGEST Enter password for private key: Pushing signature to: dlorenc/demo:sha256-97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36.sig $ cosign verify --key cosign.pub dlorenc/demo | jq . { "Critical": { "Identity": { "docker-reference": "" }, "Image": { "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36" }, "Type": "cosign container image signature" }, "Optional": { "sig": "original" } }

<!-- TODO: https://github.com/sigstore/cosign/issues/2333 -->

الآن أعطِ هذا التوقيع اسمًا لا يُنسى، ثم وقّع عليه:```shell
$ crane tag $(cosign triangulate $IMAGE_URI) mysignature
2021/02/15 20:22:55 dlorenc/demo:mysignature: digest: sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e size: 556
$ cosign sign --key cosign.key -a sig=counter dlorenc/demo:mysignature
Enter password for private key:
Pushing signature to: dlorenc/demo:sha256-71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e.sig
$ cosign verify --key cosign.pub dlorenc/demo:mysignature
{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e"},"Type":"cosign container image signature"},"Optional":{"sig":"counter"}}

أخيرًا، تحقق من التوقيع الأصلي:```shell $ crane manifest dlorenc/demo@sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e { "schemaVersion": 2, "config": { "mediaType": "application/vnd.oci.image.config.v1+json", "size": 233, "digest": "sha256:3b25a088710d03f39be26629d22eb68cd277a01673b9cb461c4c24fbf8c81c89" }, "layers": [ { "mediaType": "application/vnd.oci.descriptor.v1+json", "size": 217, "digest": "sha256:0e79a356609f038089088ec46fd95f4649d04de989487220b1a0adbcc63fadae", "annotations": { "dev.sigstore.cosign/signature": "5uNZKEP9rm8zxAL0VVX7McMmyArzLqtxMTNPjPO2ns+5GJpBeXg+i9ILU+WjmGAKBCqiexTxzLC1/nkOzD4cDA==" } } ] }

## إيقاع الإصدارات

نُصدر الإصدارات حسب الحاجة. تُصدَر إصدارات التصحيح لإصلاح الأخطاء الصغيرة. وتُصدَر الإصدارات الثانوية
بشكل دوري عند إصلاح عدة أخطاء أو إضافة ميزات. كما ستُصدَر الإصدارات الرئيسية
عند وجود ميزات تتضمن تغييرات جذرية.

## الأمان

إذا اكتشفت أي مشكلات أمنية، فيُرجى الرجوع إلى [عملية
الأمان](https://github.com/sigstore/.github/blob/main/SECURITY.md) الخاصة بـ sigstore

## ملفات الحزمة في أصول إصدارات GitHub

تحتوي أصول إصدارات GitHub الخاصة بـ `cosign` على ملفات حزمة Sigstore التي ينتجها [GoReleaser](https://github.com/sigstore/cosign/blob/ac999344eb381ae91455b0a9c5c267e747608d76/.goreleaser.yml#L166) أثناء توقيع blob الخاص بـ cosign المستخدم للتحقق من سلامة الملفات الثنائية للإصدار.
لا يستخدم cosign هذا الملف بنفسه، لكنه يُوفَّر للمستخدمين الذين يرغبون في [التحقق من سلامة الملفات الثنائية للإصدار](https://docs.sigstore.dev/cosign/system_config/installation/#verifying-cosign-with-artifact-key).

الفئات