İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

aggrega sign

aggrega sign, daha önce yayımlanmış bir veya daha fazla katalog yapıtını imzalar ve her imzayı bir OCI referrer’ı olarak ekler. aggrega push --sign komutunun yayımlama sonrası karşılığıdır: imzasız yayımlanmış bir yapıtı imzalamak veya tek bir çağrıda bütün bir yapıt grubunu imzalamak için kullanılır. Kayıt defterinin güven ilkesinin doğruladığı bir imzayı zaten taşıyan bir yapıta ikinci bir imza eklemez.

Ne yapar

aggrega sign, her <reference> için kayıt defterinin halihazırda tuttuğu özeti (digest) çözümler, bu özeti imzalar ve imza paketini bir referrer olarak ekler. Yayımlanmış baytları asla yeniden göndermez, yeniden etiketlemez veya başka bir şekilde değiştirmez; yapıt değişmezdir ve imza, ona geri işaret eden kardeş bir manifesttir. Bu nedenle bir yapıt, sürüm artırılmadan sonradan imzalanabilir.

İmzalamadan önce, referansın halihazırda taşıdığı imzaları okur ve bunları bu çalışma alanının referansın kayıt defteri için tuttuğu güven politikasına, yani aggrega pull komutunun doğrulama yaptığı politikaya göre değerlendirir. Bunlardan biri doğrulanıyorsa, onu kim imzalamış olursa olsun, referans zaten imzalıdır: komut referansla birlikte Already signed: ifadesini, referansın özetini, imzalayan kimliği ve şeffaflık günlüğü imzayı kaydetmişse ne zaman kaydedildiğini (birden fazla varsa bu tür imzaların en erkenini) yazdırır, hiçbir şey eklemez ve referansı imzalı olarak sayar. Anahtarsız imzaları doğrulayan bir okuyucu, aggrega registry update bölümünde açıklandığı gibi, bir sürümü doğrulanan imzalarının en erkenine göre tarihlendirir ve o imzanın imzalayanını belirtir; dolayısıyla başka bir imza, bir referrer ve bir şeffaflık günlüğü kaydı ekler ama böyle bir okuyucunun sürümden edindiği hiçbir şeyi değiştirmez.

Politikası hiçbir ortak anahtar ve hiçbir güvenilir kimlik sabitlemeyen bir kayıt defteri, bir imzanın değerlendirileceği hiçbir ölçüt sunmaz; bu yüzden oradaki bir referans, halihazırda ne taşırsa taşısın imzalanır. Yalnızca politikanın kabul etmediği imzaları taşıyan bir referans imzalanır, çünkü bunların hiçbiri o politika altında doğrulama yapan bir okuyucu için geçerli sayılmaz.

İmza, aggrega push --sign komutunun eklediği ve aggrega pull komutunun doğruladığı biçimle aynı olan bir Sigstore (cosign uyumlu) paketidir. Referrer, paketi signature.json olarak adlandırır; böylece referrer’ı özetiyle çeken genel bir OCI istemcisi paketi bu dosyaya yazar.

Toplu imzalama

Birden çok referansı tek bir çağrıda imzalamak için hepsini birlikte verin:

aggrega sign \
hub.example.com/component/core/api-server:1.0.0 \
hub.example.com/component/core/worker:1.0.0 \
hub.example.com/feature/core/telemetry:2.1.0

Anahtarsız imzalama, kimliği tüm toplu iş için bir kez çözer (tek bir etkileşimli kimlik doğrulamasıyla ya da GitHub Actions üzerinde çalıştırıcının ortam OIDC uç noktasıyla) ve bu kimliği her yapıtta yeniden kullanır; her yapıt için yeni, kısa ömürlü bir Fulcio sertifikası düzenlenir. Etkileşimli olarak edinilen ya da sağlanan bir belirteç her imza için yeniden kullanılır; ortam uç noktası ise her imza için yeni bir belirteç üretir. Referanslar farklı kayıt defterlerini hedefleyebilir: her biri bu tek kimlikle, kendi kayıt defteri için yapılandırılmış Fulcio ve Rekor uç noktalarına karşı imzalanır. Anahtarlı yol (--key) toplu işi hiçbir kimlik doğrulaması yapmadan imzalar.

İmzalama devam et ve raporla biçiminde çalışır: imzalanabilen her referans imzalanır, çözümlenemeyen, imzalanamayan ya da eklenemeyen bir referans kaydedilir ve toplu iş ilk hatada durmak yerine sonraki referansa geçer. Doğrulanan bir imzayı zaten taşıyan bir referans zaten imzalı olarak raporlanır ve imzalanmış sayılır. Mevcut imzaları okunamayan bir referans (kayıt defteri listelemeyi tamamlamıyorsa ya da hiçbiri doğrulanmazken bir imza getirilemiyor veya değerlendirilemiyorsa) başarısız olarak kaydedilir ve imzalanmaz: yanıtlanmamış bir soru hiçbir zaman imzasız bir yapıt olarak okunmaz. Toplu işten sonra herhangi bir referans başarısız olduysa, başarısız referansları listeleyen bir özet stderr’e yazdırılır ve komut sıfır olmayan bir kodla çıkar. Başarılı olan referanslar, diğerlerinin hatalarından bağımsız olarak imzalanmış olur.

Birkaç başvuruyu aynı anda imzalamak

Varsayılan olarak toplu iş başvuruları birbiri ardına imzalar. --jobs N en fazla N başvuruyu aynı anda imzalar, asla N’den fazlasını değil. Her biri yine de tek başına imzalanacağı şekilde imzalanır: yayımlanmış özeti çözümlenir, doğrulanan bir imzayı zaten taşıyorsa olduğu gibi bırakılır, aksi halde kendi imzasını alır — anahtarsız modda kendi geçici anahtarı, kendi kısa ömürlü sertifikası ve kendi şeffaflık günlüğü girdisiyle. Kimlik yine, herhangi bir başvuru okunmadan önce, tüm toplu iş için bir kez çözümlenir. 1’den küçük bir değer reddedilir ve hiçbir şey imzalanmaz.

Başvurular hangi sırayla biterse bitsin, çıktı verildikleri sırayı korur: her başvurunun satırları, kendisinden önce adlandırılan her başvuru bittiğinde bütün olarak yazdırılır; böylece iki başvurunun satırları asla iç içe geçmez ve başarısız başvuruların özeti de onları bu sırayla listeler. Her başvuruyu tek başınaymış gibi imzalamanın bir sonucu vardır: aynı yapıtı iki kez adlandıran bir toplu iş, ikisi aynı anda imzalandığında iki imza alır, çünkü imza oluşturulurken hiçbiri diğerinin imzasını görmez; birbiri ardına imzalandığında ise ikincisi birincinin imzasını bulur ve kayıt defterinin güven ilkesi onu doğruluyorsa hiçbir şey eklemez.

Varsayılan değer 1’dir, çünkü yapılandırmanız başkalarını adlandırmadıkça anahtarsız imzalama kamu yararına sunulan sertifika yetkilisine ve şeffaflık günlüğüne erişir ve bu hizmetler kabul ettikleri istek sayısını sınırlar.

Toplu iş başına tek kimlik bilgisi

Tek bir çağrıdaki her referans aynı kimlik bilgisiyle imzalanır: tek bir tutulan anahtar ya da tek bir anahtarsız kimlik. Bir referansın hangisine ihtiyaç duyduğuna, kayıt defteri için yapılandırma karar verir: o kayıt defterine uygulanan bir signing.key_path, adlandırdığı anahtarı seçer; hiçbiri uygulanmıyorsa referans anahtarsız imzalanır. Referanslar farklı kimlik bilgileri gerektirecekse (yapılandırma bir kayıt defteri için bir anahtar adlandırıp diğeri için adlandırmıyorsa ya da iki farklı anahtar adlandırıyorsa) komut hiçbir şey imzalamaz ve her iki taraftaki kayıt defterlerini adlandırır. Bunu herhangi bir kimlik istenmeden ve herhangi bir kayıt defteri okunmadan önce yapar; böylece gerçekleşmeyecek bir çalıştırma için hiçbir şey eklenmez ve kimseye istem gösterilmez.

Bunun yerine her kimlik bilgisi için ayrı bir çağrı çalıştırın: biri anahtarla imzalanan kayıt defterlerindeki referansları, diğeri geri kalanları adlandırsın. --key ile verilen bir anahtar, yapılandırma her kayıt defteri için ne derse desin adlandırılan her referansa uygulanır; bu nedenle --key içeren bir çağrı bu sebeple hiçbir zaman reddedilmez.

Toplu iş, referanslarından birinin ihtiyaç duyduğu kimlik bilgisiyle imzalanmak yerine reddedilir, çünkü bir imza, onu getirmiş olan hiç kimseden geri alınamaz. Yukarıda açıklanan referans başına hatalardan farklı olarak bu, tek bir referansın değil toplu işin reddidir: hiçbir referans imzalanmaz. Toplu işteki bir kayıt defteri imza gerektiriyorsa mesaj onu adlandırır; böylece ret, referansların imzalanamayacağına dair bir ifade olarak değil, referansların birleştirilmesiyle ilgili bir ret olarak okunur. Mesaj ve her bölümünün neyi adlandırdığı References signed together need different signing credentials (Birlikte imzalanan referanslar farklı imzalama kimlik bilgileri gerektiriyor) bölümündedir.

Toplu iş ortasında kimlik belirtecinin süresinin dolması

Uzun bir toplu iş, kısa ömürlü bir kimlik belirtecinden daha uzun sürebilir. GitHub Actions üzerinde bu bir sorun değildir: ortam uç noktası her imza için yeni bir belirteç üretir, dolayısıyla bir toplu iş kimliğinden hiçbir zaman uzun sürmez. Etkileşimli olarak edinilen ya da operatör tarafından sağlanan bir belirteçte (--identity-token, AGGREGA_IDENTITY_TOKEN veya SIGSTORE_ID_TOKEN) tek bir belirteç tüm toplu işe hizmet eder; süresi toplu işin ortasında dolarsa etkilenen referans devam et ve raporla ilkesiyle kaydedilir ve toplu iş devam eder. Raporlanan referansları imzalamak için komutu yeniden çalıştırın ya da uzun, betikli bir toplu iş için baştan yeni bir belirteç edinin.

Betikli toplu işler için belirteci baştan bir kez edinip dışa aktarın; böylece her referans tarayıcıya gidip gelmeden imzalanır:

export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)
aggrega sign hub.example.com/component/core/api-server:1.0.0
aggrega sign hub.example.com/component/core/worker:1.0.0

aggrega auth token için ./aggrega-auth.md sayfasına bakın.

Bir adım geçici olarak başarısız olduğunda

Her referans üç adımda imzalanır: yayımlanmış özeti (digest) çözümlenir, özet imzalanır ve imza eklenir. Bunlardan ikisi, sonraki bir denemenin başarılı olabileceği bir şekilde başarısız olduklarında yeniden denenir:

  • İmzalama çağrısı — bir kayıt defteri (registry) yazma işleminin yeniden denendiği herhangi bir hatada ve anahtarsız sertifika yetkilisinin kimlik belirtecini işleyemediğini bildirmesi durumunda.
  • İmza paketini ve referrer manifest’i kayıt defterine yazan ekleme adımı — bir sunucu hatasında, zaman aşımında veya sıfırlanan bir bağlantıda; bu hataları aggrega push listeler. Her deneme, başarısız olan isteğin yeniden gönderilmesi değil, aynı baytların yeni bir yüklemesidir ve tekrarlanan bir ekleme iki değil, tek bir imza bırakır.

Her biri en fazla üç kez, önce yarım saniye, ardından bir saniye arayla denenir. Özetin çözümlenmesi bir okuma işlemidir ve yeniden denenmez. Yavaşlamayı isteyen bir kayıt defteri farklı bir durumdur: özetin çözümlenmesi ve iliştirme de dahil olmak üzere ona yapılan her istek, Yavaşlamayı isteyen bir kayıt defteri bölümünde açıklandığı gibi, onun istediği kadar bekler.

Anahtarsız bir imzalama çağrısı en fazla üç hizmete sorar — sertifika için sertifika yetkilisine, girdi için şeffaflık günlüğüne ve yapılandırılmışsa zaman damgası için zaman damgası yetkilisine — ve her istek çağrının içinde ayrı ayrı yeniden denenir. Bunlardan birinin 429 Too Many Requests ya da bir sunucu hatasıyla (şeffaflık günlüğü için 501 Not Implemented dışındaki herhangi biri) yanıtladığı bir istek o hizmete yeniden gönderilir; böylece en fazla üç kez, önce bir saniye, ardından iki saniye arayla denenir; yalnızca o istek yinelenir, bu yüzden yeniden istenen bir şeffaflık günlüğü girdisi ikinci bir sertifika istemez. Şeffaflık günlüğüne olan bağlantı başarısız olduğunda da ona yeniden sorulur ve bir 429 ya da 503 ile gönderdiği Retry-After, istediği süre boyunca beklenir. Bu denemelerden sonra hâlâ hız sınırı ya da sunucu hatası yanıtı dönüyorsa imzalama çağrısı başarısız olur ve ardından bir bütün olarak yeniden denenmez.

Son denemesinden sonra hâlâ başarısız olan bir adım, continue-and-report kapsamında hatasıyla birlikte o referansa karşı kaydedilir ve toplu işlem devam eder — başarısız bir ekleme, eklenemeyen imza olarak bildirilir; diğer tüm hatalar hemen kaydedilir.

İmzalama kipleri

  • Anahtarsız (varsayılan) — kısa ömürlü bir Fulcio sertifikasıyla bir OIDC kimliğine bağlanan ve Rekor şeffaflık günlüğüne kaydedilen geçici bir anahtar. Fulcio ve Rekor varsayılan olarak kamu yararına işletilen Sigstore örneklerini (https://fulcio.sigstore.dev, https://rekor.sigstore.dev) kullanır. Anahtarsız güvenilir zaman damgası, Rekor şeffaflık günlüğüne dahil edilmeden gelir; ayrı bir RFC3161 zaman damgası yetkilisi isteğe bağlıdır — etkinleştirmek için --timestamp-url bayrağına tam bir uç nokta verin. Etkileşimli bir terminalde anahtarsız imzalama hiçbir bayrak gerektirmez: CLI, kısa ömürlü bir OIDC kimlik belirteci edinmek için bir tarayıcı açar. GitHub Actions üzerinde de hiçbir bayrak gerekmez: CLI, iş akışının OIDC belirtecini çalıştırıcının ortamdaki uç noktasından otomatik olarak üretir. Diğer etkileşimsiz / CI kullanımlarında AGGREGA_IDENTITY_TOKEN (veya SIGSTORE_ID_TOKEN) değişkenini dışa aktarın ya da --identity-token bayrağını geçin; verilmiş bir belirteç, ortamda bir uç nokta ve bir terminal yoksa komut reddedilir.
  • Anahtarlı (--key): çevrimdışı tutulan bir ECDSA P-256 anahtarı (cosign uyumlu PEM). Hiçbir kimlik sağlayıcısına, sertifika yetkilisine ya da şeffaflık günlüğüne bağlanılmaz; kayıt defterine ise her özeti çözümlemek ve imzasını eklemek için yine bağlanılır.

Anahtarsız URL’ler ve anahtarlı imzalamanın anahtar yolu, .aggrega-config.yaml dosyasındaki signing: bloğundan da (genel ve kayıt defteri başına) gelebilir; bir bayrak yapılandırmayı, yapılandırma da kamu yararına işletilen varsayılanı geçersiz kılar. Bu dosyada her URL mutlak bir https URL’si olarak yazılır — https://, bir ana makine ve isteğe bağlı olarak bir bağlantı noktası ile bir yol; örneğin https://fulcio.sigstore.dev — ve başka biçimdeki bir değer, yani şeması olmayan ya da http:// ile başlayan bir değer, dosya yüklenirken dosya ve anahtar adı belirtilerek reddedilir. OIDC kimlik belirteci hiçbir zaman bir yapılandırma alanı değildir ve özel anahtar hiçbir zaman satır içinde yazılmaz — yalnızca ona giden bir yol verilir.

Yapı ve imzalayıp ekleme davranışı aggrega push ile ortaktır; bu nedenle her iki komut da aynı şekilde imzalar.

Ortam değişkenleri

İmzalama girdileri ortam üzerinden sağlanabilir; bu girdiler .aggrega-config.yaml dosyasındaki signing: bloğunu geçersiz kılar, ancak bir bayrak yine de önceliklidir:

  • AGGREGA_IDENTITY_TOKEN — anahtarsız OIDC kimlik belirteci (--identity-token bayrağının ortam değişkeni karşılığı). SIGSTORE_ID_TOKEN, sigstore ekosistemiyle birlikte çalışabilirlik için bir takma ad olarak kabul edilir ve önceliği AGGREGA_IDENTITY_TOKEN ile ortamdaki GitHub Actions uç noktasının altındadır. Belirteç hiçbir zaman bir yapılandırma alanı değildir.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — anahtarsız hizmet URL’leri.
  • AGGREGA_SIGNING_KEY_PATH — anahtarlı imzalama için bir PEM anahtarını gösteren yol işaretçisi (hiçbir zaman anahtar materyalinin kendisi değildir).

aggrega sign, imzalama yapılandırmasını ve bu değişkenleri, aggrega push ile aynı şekilde yapıtın kayıt defteri ana bilgisayarı için çözümler. Öncelik sırası bayrak > ortam > yapılandırma > varsayılan şeklindedir. Tam liste için environment-variables.md sayfasına bakın.

Bu değişkenlerden biri ya da --fulcio-url, --rekor-url veya --timestamp-url aracılığıyla sağlanan bir URL yazıldığı gibi alınır. Yapılandırma dosyası, bunlardan herhangi biri üzerine uygulanmadan önce denetlenir; bu nedenle dosyanın değerlerinin uyması gereken https biçimi bunlara uygulanmaz ve hatalı biçimlendirilmiş bir URL ancak imzalama o hizmetle iletişim kurduğunda başarısız olur.

Ayrıca bakınız

  • ./aggrega-auth.md — bir grup anahtarsız imzalama için OIDC kimlik belirtecini bir kez edinir.
  • ./aggrega-push.md — yayımlar; isteğe bağlı olarak gönderim sırasında imzalar (göndermeden önce imzalama).
  • ./aggrega-pull.md — imzaları kayıt defteri başına güven politikasına göre doğrulayan tüketen taraf.
  • ./aggrega-serve.md — arka plan hizmeti aynı toplu işlemi aggrega/signArtifacts üzerinden yürütür; kimliğini istekten veya ortamdan çözümler ve kullanıcıya sormak yerine reddeder; oradaki bir istek hiçbir anahtar belirtmez, bu nedenle anahtarlı imzalama çalışma alanının kendi signing: bloğunu okur.
  • ./aggrega-mcp.md — bir asistanın çağırabileceği ve key_path kabul eden sign-artifacts aracı olarak aynı yetenek. Buna izin vermeden önce o sayfanın bu konuda söylediklerini okuyun.

Kullanım

aggrega sign <reference>... [flags]

Açıklama

Sign amends already-published artifacts by attaching a signature to each as an OCI referrer. It does not re-push, re-tag, or otherwise mutate the published bytes — the artifacts are immutable; each signature is a sibling manifest pointing back at its artifact. With --key signatures are produced offline from a held ECDSA P-256 key; without --key the keyless flow is used, which requires a live identity provider, Fulcio, and Rekor. Multiple references are signed in one invocation: the keyless identity is acquired once and reused across every artifact, and a fresh short-lived certificate is issued per artifact. Every reference in one invocation is signed with one credential: where the configuration names a held key (signing.key_path) for one reference's registry and none for another's, or two different keys, nothing is signed and the command says to run one invocation per credential; --key applies its key to every reference. A reference that already carries a signature its registry's trust policy verifies is reported as already signed, naming who signed it and when, and nothing is attached to it; a registry whose policy pins no public key or trusted identity gives nothing to judge a signature against, so a reference there is signed. Every other signable reference is signed; failures are collected and reported at the end, and the command exits non-zero if any reference failed — including one whose existing signatures could not be read, which is not signed. With --jobs N up to N references are signed at once; each is still signed exactly as it would be alone — when keyless, with its own certificate and its own transparency-log entry — and the output lists the references in the order they were given. The default, 1, signs one reference after another, because keyless signing reaches the public certificate authority and transparency log by default, and those limit how many requests they accept.

Bayraklar

BayrakVarsayılanAçıklama
--fulcio-url—Anahtarsız imzalama için Fulcio sertifika yetkilisi URL’si. Belirtilmediğinde kamuya açık Fulcio örneği kullanılır.
--identity-token—Anahtarsız imzalama için OIDC kimlik belirteci. Etkileşimli bir terminalde (bir tarayıcı akışı belirteci edinir) ve GitHub Actions üzerinde (iş akışının OIDC belirteci otomatik olarak üretilir) isteğe bağlıdır; diğer etkileşimsiz/CI kullanımlarında zorunludur ve bu durumlarda bunun yerine AGGREGA_IDENTITY_TOKEN veya SIGSTORE_ID_TOKEN olarak dışa aktarılabilir.
--jobs1Aynı anda imzalanan başvuru sayısı. Her biri yine de tek başına imzalanacağı şekilde imzalanır ve çıktı, başvuruların verildiği sırayı korur. En az 1.
--key—Çevrimdışı anahtarlı imzalama için elde tutulan ECDSA P-256 özel anahtar PEM dosyasının yolu. Belirtilmediğinde anahtarsız imzalama kullanılır.
--rekor-url—Anahtarsız imzalama için Rekor şeffaflık günlüğü URL’si. Belirtilmediğinde kamuya açık Rekor örneği kullanılır.
--timestamp-url—Anahtarsız imzalama için isteğe bağlı RFC3161 zaman damgası yetkilisi URL’si.