cosign

<p align="center">
  <img style="max-width: 100%;width: 300px;" src="https://raw.githubusercontent.com/sigstore/community/main/artwork/cosign/horizontal/color/sigstore_cosign-horizontal-color.svg" alt="Cosign logo"/>
</p>

# cosign

توقيع حاويات OCI (وغيرها من المخرجات) باستخدام [Sigstore](https://sigstore.dev/)!

[![Go Report Card](https://goreportcard.com/badge/github.com/sigstore/cosign)](https://goreportcard.com/report/github.com/sigstore/cosign)
[![e2e-tests](https://github.com/sigstore/cosign/actions/workflows/e2e-tests.yml/badge.svg)](https://github.com/sigstore/cosign/actions/workflows/e2e-tests.yml)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5715/badge)](https://bestpractices.coreinfrastructure.org/projects/5715)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/sigstore/cosign/badge)](https://securityscorecards.dev/viewer/?uri=github.com/sigstore/cosign)

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

يدعم Cosign:

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

## معلومات

تم تطوير `Cosign` كجزء من مشروع [`sigstore`](https://sigstore.dev).
نستخدم أيضًا [قناة slack](https://sigstore.slack.com)!
انقر [هنا](https://join.slack.com/t/sigstore/shared_invite/zt-47srvpyn6-j8Ek5hGBwKN32IjLw8BvYA) للحصول على رابط الدعوة.

## التثبيت

لعمليات التثبيت عبر Homebrew و Arch و Nix و GitHub Action و Kubernetes، راجع [وثائق التثبيت](https://docs.sigstore.dev/cosign/system_config/installation/).

لثنائيات Linux و macOS و Windows، راجع [أصول إصدار GitHub](https://github.com/sigstore/cosign/releases/latest).

:rotating_light: إذا كنت تقوم بتنزيل إصدارات cosign من حاوية GCS الخاصة بنا - يرجى الاطلاع على مزيد من المعلومات حول [إشعار الإهمال](https://blog.sigstore.dev/cosign-releases-bucket-deprecation/) بتاريخ 31 يوليو 2023 :rotating_light:

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

إذا كان لديك 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/main/CONTRIBUTING.md).

سيركز تطوير Cosign المستقبلي على الإصدار الرئيسي التالي الذي سيكون مبنيًا على
[sigstore-go](https://github.com/sigstore/sigstore-go). سيركز المشرفون على تطوير الميزات داخل
sigstore-go. نقدّر المساهمات في sigstore-go، خاصةً فيما يتعلق بمفاتيح bring-your-own والتوقيع.
يرجى الاطلاع على [متتبع المشكلات](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/images/tree/main/images/static
FROM cgr.dev/chainguard/static:latest
COPY --from=cosign-bin /ko-app/cosign /usr/local/bin/cosign
ENTRYPOINT [ "cosign" ]
```

## بدء سريع

يوضح هذا كيفية:
* توقيع صورة حاوية باستخدام طريقة "التوقيع بدون مفتاح" الافتراضية القائمة على الهوية (راجع [الوثائق لمزيد من المعلومات](https://docs.sigstore.dev/cosign/signing/overview/))
* التحقق من صورة الحاوية
* استكشاف تدفقات توقيع/تحقق blob بدون مفتاح الأوسع في [Sigstore Cosign Quickstart](https://docs.sigstore.dev/quickstart/quickstart-cosign/)

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

لاحظ أنه يجب عليك دائمًا توقيع الصور بناءً على digest الخاص بها (`@sha256:...`)
بدلاً من tag (`: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
```

يمكنك أيضًا تمرير تعبير نمطي (regex) لعلامات هوية الشهادة والمُصدر، `--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.
للتحقق المعزول من التوقيعات باستخدام نسخة المصلحة العامة، ستحتاج إلى استرداد
ملف [الجذر الموثوق](https://github.com/sigstore/root-signing/blob/main/targets/trusted_root.json) من مستودع TUF
الإنتاجي. سيتغير محتوى هذا الملف دون إشعار. بعدم استخدام TUF، ستحتاج
إلى بناء آليتك الخاصة للحفاظ على نسختك المعزولة من هذا الملف محدثة.

يمكن لـ Cosign إجراء تحقق غير متصل بالكامل من خلال التحقق من [حزمة](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md#properties) والتي عادةً ما تُوزَّع كتعليق توضيحي على بيان الصورة.
طالما أن هذا التعليق التوضيحي موجود، يمكن إجراء التحقق غير المتصل.
يُضمَّن تعليق الحزمة هذا دائمًا بشكل افتراضي للتوقيع بدون مفتاح، لذا ستتضمن وظيفة `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. قد تكون إعادة المحاولة عند الفشل حلاً مفيدًا إذا فشلت أي من هذه الخدمات -- كما نقدّر تقديم تقارير بالمشكلات المتعلقة بأعطال محددة

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

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

## العمل مع Artifacts أخرى

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

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

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

### Blobs

يمكنك نشر artifact باستخدام `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
```

يمكن لمستخدميك تنزيله من عنوان URL "المباشر" باستخدام أدوات قياسية مثل 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، باستخدام هذه [المواصفات](https://github.com/solo-io/wasm/tree/master/spec).

يمكن لـ 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](https://in-toto.io) بشكل مدمج.
تم تعريف مواصفات هذه الإثباتات [هنا](https://github.com/in-toto/attestation).

يمكنك إنشاء واحد وتوقيعه من ملف predicate محلي باستخدام الأوامر التالية:

```shell
$ cosign attest --predicate <file> --key cosign.key $IMAGE_URI_DIGEST
```

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

للتحقق:

```shell
$ cosign verify-attestation --key cosign.pub $IMAGE_URI
```

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

راجع [وثائق الاستخدام](https://docs.sigstore.dev/cosign/signing/overview/) لمزيد من المعلومات.

## الرموز المميزة المعتمدة على الأجهزة

راجع [وثائق الرموز المميزة المعتمدة على الأجهزة](https://docs.sigstore.dev/cosign/key_management/hardware-based-tokens/) للحصول على معلومات حول كيفية استخدام `cosign` مع الأجهزة.

## دعم السجلات

يستخدم `cosign` مكتبة [go-containerregistry](https://github.com/google/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

نهدف إلى دعم واسع للسجلات. لتوقيع `sign` الصور في السجلات التي لا تدعم بعد بشكل كامل [أنواع وسائط OCI](https://github.com/sigstore/cosign/blob/main/specs/SIGNATURE_SPEC.md)، قد يحتاج المرء إلى استخدام `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، لكل من التوقيع المؤقت بدون مفتاح والتوقيع بمفتاح مُدار.
تُخزَّن المفاتيح بصيغة PKCS8 المُرمَّزة بـ PEM.
ومع ذلك، يمكنك استخدام `cosign` لتخزين واسترجاع التوقيعات بأي صيغة، من أي خوارزمية.

### أشياء يُحتمل أن تتغير

#### صيغ الحمولة

`cosign` يدعم فقط صيغة [التوقيع البسيط](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/notation/issues/40 لأحد الخيارات.

#### تفاصيل السجل

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

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

##### تحديد السجل

سيقوم `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](https://jedisct1.github.io/minisign/) و
[signify](https://www.openbsd.org/papers/bsdcan-signify.html).

يتم تخزين المفاتيح الخاصة المُنشأة بصيغة 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 لما نقوم بتوقيعه) لتحديد موقع فهرس التوقيع.

<p align="center">
  <img src="https://raw.githubusercontent.com/sigstore/cosign/HEAD/images/signatures.dot.svg" />
</p>

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

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

راجع [حالات التسابق](#registry-details) لبعض التحذيرات المتعلقة بهذه الاستراتيجية.

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

### كيانات التوقيع

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

### دعم KMS

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

تتوفر مزوّدات KMS إضافية كإضافات خارجية، مثل [OVHcloud KMS](https://github.com/ovh/sigstore-kms-ovhcloud).

راجع [وثائق KMS](https://docs.sigstore.dev/cosign/key_management/overview/) لمزيد من التفاصيل.

### عناصر OCI

ادفع عنصرًا إلى سجل باستخدام [oras](https://github.com/deislabs/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 and Cosign](https://medium.com/@dlorenc/notary-v2-and-cosign-b816658f044d)

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

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

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

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

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

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

* لا توجد خدمات خارجية لتخزين التوقيعات أو الاستعلام عنها أو استرجاعها
* نهدف إلى أكبر قدر ممكن من دعم السجلات
* يجب أن يعمل كل شيء عبر واجهة برمجة تطبيقات السجل
* لا ينبغي أن يكون PGP مطلوبًا على الإطلاق.
* يجب أن يكون المستخدمون قادرين على العثور على جميع التوقيعات الخاصة بصورة ما
* يمكن للموقّعين توقيع صورة بعد الدفع

---

[Read more](https://github.com/sigstore/cosign)