aggrega sign
aggrega sign ký một hoặc nhiều artifact catalog đã được xuất bản và gắn mỗi chữ ký dưới dạng một OCI referrer. Đây là lệnh tương ứng sau khi xuất bản của aggrega push --sign: dùng lệnh này để ký một artifact đã được xuất bản mà chưa ký, hoặc để ký cả một loạt artifact trong một lần gọi. Lệnh không thêm chữ ký thứ hai cho một artifact đã mang một chữ ký mà chính sách tin cậy của registry của nó xác minh được.
Chức năng
aggrega sign phân giải digest mà registry đang giữ cho mỗi <reference>, ký digest đó và đính kèm gói chữ ký dưới dạng một referrer. Lệnh không bao giờ đẩy lại, gắn lại tag hay thay đổi theo bất kỳ cách nào các byte đã được phát hành — artifact là bất biến, còn chữ ký là một manifest anh em trỏ ngược về nó. Vì vậy, một artifact có thể được ký sau khi đã phát hành mà không cần tăng phiên bản.
Trước khi ký, lệnh đọc các chữ ký mà tham chiếu đã mang và đánh giá chúng theo chính sách tin cậy mà workspace này giữ cho registry của tham chiếu — chính sách mà aggrega pull dùng để xác minh. Khi có một chữ ký được xác minh, bất kể ai đã ký, tham chiếu đó coi như đã được ký: lệnh in Already signed: kèm tham chiếu, digest của nó, danh tính ký và, nếu transparency log đã ghi nhận chữ ký, thời điểm ký — là chữ ký sớm nhất như vậy nếu có nhiều chữ ký — không đính kèm gì và tính tham chiếu là đã ký. Một trình đọc xác minh chữ ký keyless sẽ xác định ngày của một phiên bản theo chữ ký sớm nhất được xác minh và nêu tên người ký của chữ ký đó, như aggrega registry update mô tả, nên thêm một chữ ký nữa chỉ thêm một referrer và một mục transparency log mà không thay đổi điều gì trình đọc như vậy lấy từ phiên bản.
Một registry có chính sách không ghim khóa công khai nào và không có danh tính tin cậy nào thì không cung cấp gì để đánh giá chữ ký, nên một tham chiếu ở đó sẽ được ký bất kể nó đã mang những gì. Một tham chiếu chỉ mang các chữ ký mà chính sách không chấp nhận sẽ được ký, vì không chữ ký nào trong số đó có giá trị với một trình đọc xác minh theo chính sách đó.
Chữ ký là một gói Sigstore (tương thích cosign), cùng định dạng mà aggrega push --sign đính kèm và aggrega pull xác minh. Referrer đặt tên gói là signature.json, nên một OCI client thông thường khi kéo referrer theo digest của nó sẽ ghi gói vào tệp đó.
Ký theo lô
Truyền nhiều tham chiếu để ký chúng trong một lần gọi:
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.0Ký không khóa (keyless) xác định danh tính một lần cho cả lô — một lần xác thực tương tác, hoặc trên GitHub Actions là endpoint OIDC sẵn có của runner — và dùng lại danh tính đó cho mọi artifact, cấp một chứng chỉ Fulcio ngắn hạn mới cho mỗi artifact. Một token lấy qua tương tác hoặc được cung cấp sẽ được dùng lại cho mọi chữ ký; endpoint sẵn có thì tạo một token mới cho mỗi chữ ký. Các tham chiếu có thể nhắm tới các registry khác nhau: mỗi tham chiếu được ký bằng danh tính duy nhất đó, với các endpoint Fulcio và Rekor được cấu hình cho chính registry của nó. Cách ký có khóa (--key) ký cả lô mà không cần xác thực gì.
Việc ký theo kiểu tiếp tục và báo cáo: mọi tham chiếu ký được đều được ký, một tham chiếu không xác định, ký hoặc đính kèm được sẽ được ghi lại, và lô chuyển sang tham chiếu tiếp theo thay vì dừng ở lỗi đầu tiên. Một tham chiếu đã mang một chữ ký xác minh được sẽ được báo là đã ký và được tính là đã ký. Một tham chiếu mà các chữ ký hiện có không đọc được — registry không hoàn tất việc liệt kê, hoặc một chữ ký không tải về hay đánh giá được trong khi không chữ ký nào xác minh được — sẽ được ghi là thất bại và không được ký: một câu hỏi chưa có lời đáp không bao giờ được hiểu là một artifact chưa ký. Sau lô, nếu có tham chiếu nào thất bại, một bản tóm tắt liệt kê các tham chiếu thất bại được in ra stderr và lệnh thoát với mã khác không. Các tham chiếu thành công vẫn được ký bất kể các tham chiếu khác thất bại.
Ký nhiều tham chiếu cùng lúc
Theo mặc định, lô ký các tham chiếu lần lượt từng cái. --jobs N ký tối đa N tham chiếu cùng lúc, và không bao giờ nhiều hơn N. Mỗi tham chiếu vẫn được ký đúng như khi được ký riêng lẻ: digest đã phát hành của nó được phân giải, nó được giữ nguyên nếu đã mang một chữ ký xác minh được, và nếu không thì nhận một chữ ký riêng — ở chế độ keyless là khóa tạm thời riêng, chứng chỉ ngắn hạn riêng và mục nhật ký minh bạch riêng. Danh tính vẫn được phân giải một lần, cho cả lô, trước khi bất kỳ tham chiếu nào được đọc. Một giá trị nhỏ hơn 1 bị từ chối và không gì được ký.
Dù các tham chiếu hoàn tất theo thứ tự nào, đầu ra vẫn giữ thứ tự mà chúng được đưa ra: các dòng của mỗi tham chiếu được in trọn vẹn khi mọi tham chiếu được nêu trước nó đã hoàn tất, nên các dòng của hai tham chiếu không bao giờ xen kẽ nhau, và bản tóm tắt các tham chiếu thất bại cũng liệt kê chúng theo thứ tự đó. Một hệ quả của việc ký mỗi tham chiếu như thể nó đứng riêng: một lô nêu cùng một artifact hai lần sẽ nhận hai chữ ký khi cả hai được ký cùng lúc, vì không cái nào thấy chữ ký của cái kia khi chữ ký đó đang được tạo, trong khi nếu ký lần lượt, lần thứ hai sẽ tìm thấy chữ ký của lần thứ nhất và, khi chính sách tin cậy của registry xác minh được chữ ký đó, sẽ không đính kèm gì.
Mặc định là 1 vì ký keyless truy cập cơ quan cấp chứng chỉ và nhật ký minh bạch công cộng trừ khi cấu hình của bạn chỉ định các dịch vụ khác, và các dịch vụ đó giới hạn số yêu cầu mà chúng chấp nhận.
Một thông tin xác thực cho mỗi lô
Mọi tham chiếu trong một lần gọi được ký bằng cùng một thông tin xác thực: một khóa duy nhất đang giữ, hoặc một danh tính keyless duy nhất. Tham chiếu cần loại nào do cấu hình cho registry của nó quyết định — một signing.key_path áp dụng cho registry đó chọn khóa mà nó chỉ định, và nếu không có cái nào áp dụng thì tham chiếu được ký keyless. Khi các tham chiếu cần những thông tin xác thực khác nhau — cấu hình chỉ định một khóa cho một registry và không có khóa cho registry khác, hoặc hai khóa khác nhau — lệnh không ký gì và nêu tên các registry ở mỗi bên. Lệnh làm điều này trước khi yêu cầu bất kỳ danh tính nào và trước khi đọc bất kỳ registry nào, nên không có gì được đính kèm và không ai bị nhắc nhập cho một lần chạy sẽ không tiếp tục.
Thay vào đó, hãy chạy một lần gọi cho mỗi thông tin xác thực: một lần nêu các tham chiếu trên các registry được ký bằng khóa, một lần khác nêu phần còn lại. Một khóa truyền bằng --key áp dụng cho mọi tham chiếu được nêu, bất kể cấu hình nói gì cho từng registry, nên một lần gọi có --key không bao giờ bị từ chối vì lý do này.
Lô bị từ chối thay vì được ký bằng thông tin xác thực mà một trong các tham chiếu của nó cần, vì một chữ ký không thể thu hồi từ bất kỳ ai đã tải nó về. Khác với các lỗi theo từng tham chiếu mô tả ở trên, đây là sự từ chối của cả lô chứ không phải của một tham chiếu: không tham chiếu nào được ký. Nếu một registry trong lô yêu cầu chữ ký, thông báo sẽ nêu tên registry đó, để sự từ chối được hiểu là về việc kết hợp các tham chiếu chứ không phải là tuyên bố rằng chúng không thể được ký. Thông báo, và những gì mỗi phần của nó nêu, có trong References signed together need different signing credentials (Các tham chiếu được ký cùng nhau cần các thông tin xác thực ký khác nhau).
Token danh tính hết hạn giữa lô
Một lô dài có thể kéo dài hơn thời hạn của một token danh tính ngắn hạn. Trên GitHub Actions đây không phải vấn đề: endpoint sẵn có tạo một token mới cho mỗi chữ ký, nên một lô không bao giờ kéo dài hơn danh tính của nó. Với một token lấy qua tương tác hoặc do người vận hành cung cấp (--identity-token, AGGREGA_IDENTITY_TOKEN, hoặc SIGSTORE_ID_TOKEN), một token phục vụ cả lô; nếu nó hết hạn giữa lô, tham chiếu bị ảnh hưởng được ghi lại theo kiểu tiếp tục và báo cáo, và lô tiếp tục. Chạy lại lệnh để ký các tham chiếu đã được báo cáo — hoặc, với một lô dài chạy bằng script, hãy lấy một token mới ngay từ đầu.
Với các lô chạy bằng script, hãy lấy token một lần ngay từ đầu và export nó, để ký từng tham chiếu mà không phải qua trình duyệt:
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)aggrega sign hub.example.com/component/core/api-server:1.0.0aggrega sign hub.example.com/component/core/worker:1.0.0Xem ./aggrega-auth.md về aggrega auth token.
Khi một bước thất bại tạm thời
Mỗi tham chiếu được ký qua ba bước: digest đã công bố của nó được phân giải, digest được ký, và chữ ký được đính kèm. Hai trong số các bước này được thử lại khi chúng thất bại theo cách mà một lần thử sau có thể thành công:
- Lệnh gọi ký — khi gặp bất kỳ lỗi nào mà một thao tác ghi vào registry được thử lại, và khi cơ quan cấp chứng chỉ keyless báo rằng nó không thể xử lý identity token.
- Bước đính kèm, bước ghi gói chữ ký và manifest referrer vào registry — khi gặp lỗi máy chủ, hết thời gian chờ hoặc kết nối bị đặt lại;
aggrega pushliệt kê các lỗi đó. Mỗi lần thử là một lần tải lên mới của cùng các byte chứ không phải gửi lại yêu cầu đã thất bại, và một lần đính kèm lặp lại chỉ để lại một chữ ký, không phải hai.
Mỗi bước được thử tối đa ba lần, cách nhau nửa giây rồi một giây. Việc phân giải digest là một thao tác đọc và không được thử lại. Registry yêu cầu giảm tốc độ là một trường hợp khác: mọi yêu cầu tới nó, kể cả việc phân giải digest và việc đính kèm, đều chờ đúng khoảng thời gian nó yêu cầu, như Registry yêu cầu giảm tốc độ mô tả.
Một lệnh gọi ký keyless hỏi tối đa ba dịch vụ — cơ quan cấp chứng chỉ để lấy chứng chỉ, nhật ký minh bạch để lấy một mục và, khi có cấu hình, cơ quan cấp dấu thời gian để lấy dấu thời gian — và mỗi yêu cầu được thử lại riêng bên trong lệnh gọi. Một yêu cầu mà một trong số chúng trả lời bằng 429 Too Many Requests hoặc một lỗi máy chủ (với nhật ký minh bạch là bất kỳ lỗi nào trừ 501 Not Implemented) sẽ được gửi lại cho dịch vụ đó, nên nó được thử tối đa ba lần, cách nhau một giây rồi hai giây; chỉ yêu cầu đó được lặp lại, nên một mục nhật ký minh bạch được yêu cầu lại không yêu cầu chứng chỉ thứ hai. Nhật ký minh bạch cũng được hỏi lại khi kết nối tới nó thất bại, và một Retry-After mà nó gửi kèm 429 hoặc 503 sẽ được chờ đúng thời gian nó yêu cầu. Một câu trả lời giới hạn tốc độ hoặc lỗi máy chủ vẫn quay lại sau các lần thử đó sẽ làm lệnh gọi ký thất bại, và khi đó cả lệnh gọi không được thử lại.
Một bước vẫn thất bại sau lần thử cuối cùng sẽ được ghi nhận cho tham chiếu đó theo cơ chế continue-and-report, kèm theo lỗi của nó, và lô tiếp tục — một lần đính kèm thất bại được báo cáo là chữ ký không thể đính kèm; mọi lỗi khác được ghi nhận ngay lập tức.
Các chế độ ký
- Keyless (mặc định) — một khóa tạm thời được gắn với một danh tính OIDC bằng một chứng chỉ Fulcio có thời hạn ngắn, được ghi vào nhật ký minh bạch Rekor. Fulcio và Rekor mặc định dùng các phiên bản Sigstore công cộng (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). Dấu thời gian tin cậy của chế độ keyless đến từ việc được đưa vào nhật ký minh bạch của Rekor; một cơ quan cấp dấu thời gian RFC3161 riêng là tùy chọn — cung cấp--timestamp-urlvới một endpoint đầy đủ để bật nó. Tại một terminal tương tác, ký keyless không cần cờ nào: CLI mở trình duyệt để lấy một token danh tính OIDC có thời hạn ngắn. Trên GitHub Actions cũng không cần cờ nào: CLI tự động tạo token OIDC của workflow từ endpoint sẵn có của runner. Đối với cách dùng không tương tác / CI khác, hãy exportAGGREGA_IDENTITY_TOKEN(hoặcSIGSTORE_ID_TOKEN), hoặc truyền--identity-token; khi không có token được cung cấp, không có endpoint sẵn có và không có terminal, lệnh sẽ bị từ chối. - Keyed (
--key) — một khóa ECDSA P-256 được giữ ngoại tuyến (PEM tương thích cosign). Không liên hệ nhà cung cấp danh tính, cơ quan cấp chứng chỉ hay nhật ký minh bạch nào; registry thì vẫn được liên hệ, để phân giải từng digest và đính kèm chữ ký của nó.
Các URL keyless và đường dẫn khóa keyed cũng có thể lấy từ khối signing: của .aggrega-config.yaml (toàn cục và theo từng registry); cờ ghi đè cấu hình, và cấu hình ghi đè giá trị mặc định công cộng. Trong tệp đó, mỗi URL được viết dưới dạng một URL https tuyệt đối — https://, một host, và tùy chọn một cổng và một đường dẫn, chẳng hạn https://fulcio.sigstore.dev — và một giá trị có dạng khác, không có scheme hoặc bắt đầu bằng http://, sẽ bị từ chối khi tệp được nạp, kèm tên tệp và tên khóa. Token danh tính OIDC không bao giờ là một trường cấu hình, và khóa riêng không bao giờ được viết trực tiếp — chỉ có đường dẫn tới nó.
Cách dựng và hành vi ký-và-gắn được dùng chung với aggrega push, nên cả hai lệnh đều ký giống hệt nhau.
Biến môi trường
Các đầu vào ký có thể được cung cấp qua môi trường, ghi đè khối signing: của .aggrega-config.yaml, trong khi cờ vẫn được ưu tiên hơn:
AGGREGA_IDENTITY_TOKEN— token định danh OIDC không dùng khóa (biến môi trường tương ứng với--identity-token).SIGSTORE_ID_TOKENđược chấp nhận như một bí danh tương thích với hệ sinh thái sigstore, xếp hạng thấp hơnAGGREGA_IDENTITY_TOKENvà endpoint GitHub Actions có sẵn trong môi trường. Token không bao giờ là một trường cấu hình.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— các URL dịch vụ ký không dùng khóa.AGGREGA_SIGNING_KEY_PATH— một đường dẫn trỏ tới tệp PEM của khóa dùng cho chế độ ký có khóa (không bao giờ là bản thân dữ liệu khóa).
aggrega sign phân giải cấu hình ký và các biến này cho host registry của artifact, giống cách aggrega push thực hiện. Thứ tự ưu tiên là cờ > môi trường > cấu hình > mặc định. Xem environment-variables.md để biết danh sách đầy đủ.
Một URL được cung cấp qua một trong các biến này, hoặc qua --fulcio-url, --rekor-url hay --timestamp-url, được dùng đúng như đã viết. Tệp cấu hình được kiểm tra trước khi một trong hai được áp dụng đè lên nó, nên yêu cầu về dạng https mà các giá trị của tệp phải tuân theo không áp dụng cho chúng, và một URL sai định dạng chỉ thất bại khi quá trình ký liên hệ với dịch vụ đó.
Xem thêm
- ./aggrega-auth.md — lấy một token định danh OIDC một lần cho một lô các lần ký không cần khóa.
- ./aggrega-push.md — xuất bản, có thể tùy chọn ký tại thời điểm push (ký trước khi push).
- ./aggrega-pull.md — phía sử dụng, nơi xác minh chữ ký theo chính sách tin cậy của từng registry.
- ./aggrega-serve.md — daemon thực hiện cùng lô này tại
aggrega/signArtifacts, xác định danh tính từ yêu cầu hoặc từ môi trường và từ chối thay vì hỏi người dùng; một yêu cầu ở đó không chỉ định khóa nào, nên việc ký có khóa đọc khốisigning:của chính workspace. - ./aggrega-mcp.md — cùng khả năng này dưới dạng công cụ
sign-artifacts, mà một trợ lý có thể gọi, và công cụ này chấp nhậnkey_path. Hãy đọc những gì trang đó nói về việc cho phép nó trước khi bạn làm vậy.
Cú pháp
aggrega sign <reference>... [flags]Mô tả
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.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--fulcio-url | — | URL của cơ quan cấp chứng chỉ Fulcio để ký không cần khóa. Khi bỏ qua, phiên bản Fulcio công cộng sẽ được sử dụng. |
--identity-token | — | Token định danh OIDC để ký không cần khóa. Tùy chọn khi ở terminal tương tác (một luồng trình duyệt sẽ lấy token) và trên GitHub Actions (token OIDC của workflow được tạo tự động); bắt buộc cho các trường hợp không tương tác/CI khác, khi đó có thể export nó dưới dạng AGGREGA_IDENTITY_TOKEN hoặc SIGSTORE_ID_TOKEN. |
--jobs | 1 | Số tham chiếu được ký cùng lúc. Mỗi tham chiếu vẫn được ký đúng như khi được ký riêng lẻ, và đầu ra giữ thứ tự mà các tham chiếu được đưa ra. Tối thiểu là 1. |
--key | — | Đường dẫn tới tệp PEM khóa riêng ECDSA P-256 đang giữ để ký có khóa ngoại tuyến. Khi bỏ qua, phương thức ký không cần khóa sẽ được sử dụng. |
--rekor-url | — | URL của nhật ký minh bạch Rekor để ký không cần khóa. Khi bỏ qua, phiên bản Rekor công cộng sẽ được sử dụng. |
--timestamp-url | — | URL tùy chọn của cơ quan cấp dấu thời gian RFC3161 để ký không cần khóa. |