.nh
.TH "signature-protocols" 1 "" "" "دستورات کاربر"
.SH "نام (NAME)"
signature\-protocols \- پروتکل‌های دسترسی به امضا برای تصاویر کانتینری
.SH "توضیحات (DESCRIPTION)"
کتابخانه \fBgo.podman.io/image/v5\fR از امضاهایی که به صورت داده‌های دودویی (blobs) «پیوست‌شده به» یک تصویر پیاده‌سازی شده‌اند، پشتیبانی می‌کند. برخی روش‌های انتقال تصویر (قالب‌های ذخیره‌سازی محلی و پروتکل‌های راه دور) این امضاها را به صورت محلی یا به سادگی پیاده‌سازی می‌کنند؛ برای موارد دیگر، افزونه‌های پروتکل که در ادامه شرح داده شده‌اند ضروری هستند.

.SH "مخازن docker/distribution — ذخیره‌سازی جداگانه (docker/distribution registries—separate storage)"
.SS "نحوه استفاده (Usage)"
هر مخزن docker/distribution موجود، چه به صورت پیش‌فرض از امضاها پشتیبانی کند یا خیر، می‌تواند با پیکربندی نشانی اینترنتی (URL) ذخیره‌سازی امضا در
\[la]containers\-registries.d.md\[ra]\&
به یک محل ذخیره امضای جداگانه مجهز شود.
می‌توان \fBregistries.d\fR را طوری پیکربندی کرد که از یک آدرس ذخیره‌سازی برای کل سرور docker/distribution استفاده کند، یا نشانی‌های اینترنتی جداگانه‌ای را برای فضاهای نام کوچکتری یا مخازن منفرد درون سرور به کار گیرد (این امر برای مثال به سازندگان تصویر اجازه می‌دهد ذخیره‌سازی امضای خود را مدیریت کنند در حالی که تصاویر را در سرور عمومی \fBdocker.io\fR منتشر می‌نمایند).

.PP
نشانی اینترنتی ذخیره‌سازی امضا، ریشه سلسله‌مراتب مسیر را تعریف می‌کند. این آدرس می‌تواند یک نشانی اینترنتی \fBfile:///…\fR باشد که به ساختار دایرکتوری محلی اشاره دارد، یا یک آدرس \fBhttp\fR/\fBhttps\fR باشد که به یک سرور راه دور اشاره می‌کند. محل ذخیره امضای \fBfile:///\fR هم قابل خواندن و هم قابل نوشتن است، اما \fBhttp\fR/\fBhttps\fR تنها از خواندن پشتیبانی می‌کند.

.PP
در هر دو حالت از یک ساختار مسیر مشابه استفاده می‌شود، بنابراین سرور HTTP/HTTPS می‌تواند یک وب‌سرور ایستای ساده باشد که ساختار دایرکتوری ایجادشده از طریق نوشتن در ذخیره‌ساز \fBfile:///\fR را ارائه می‌دهد. (این موضوع البته مانع از پیاده‌سازی‌های دیگر سرور، مانند سرور HTTP که امضاها را از یک پایگاه داده می‌خواند، نخواهد بود).

.PP
گردش کار معمول برای تولید و توزیع تصاویر با استفاده از سازوکار ذخیره‌سازی جداگانه این است که مخزن در \fBregistries.d\fR با یک نشانی \fBlookaside-staging\fR که به یک ناحیه واسط خصوصی \fBfile:///\fR اشاره دارد و یک نشانی \fBlookaside\fR که به یک سرور وب عمومی اشاره می‌کند، پیکربندی شود. برای انتشار یک تصویر، تولیدکننده تصویر، آن را در صورت نیاز امضا می‌کند (مثلاً با استفاده از \fBskopeo copy\fR) و سپس ساختار دایرکتوری ایجادشده را از ناحیه واسط \fBfile:///\fR به یک زیرشاخه از ریشه وب سرور عمومی کپی می‌کند تا با استفاده از نشانی عمومی \fBlookaside\fR در دسترس باشند. سازنده همچنین به مصرف‌کنندگان تصویر دستورالعمل می‌دهد یا یک فایل پیکربندی \fBregistries.d\fR در اختیارشان می‌گذارد تا یک آدرس \fBlookaside\fR که به سرور وب عمومی اشاره دارد تنظیم کنند.

.SS "ساختار مسیر (Path structure)"
با فرض یک نشانی ذخیره‌سازی امضای \fIbase\fP پیکربندی‌شده در \fBregistries.d\fR همان‌طور که در بالا ذکر شد، و یک تصویر کانتینر ذخیره‌شده در مخزن docker/distribution با استفاده از نام کامل
\fIhostname\fP\fB/\fR\fInamespaces\fP\fB/\fR\fIname\fP{\fB@\fR\fIdigest\fP,\fB:\fR\fItag\fP}
(مثلاً برای \fBdocker.io/library/busybox:latest\fR، مقدار \fInamespaces\fR برابر با \fBlibrary\fR است، حتی اگر کاربر با نحو کوتاه‌تر \fBbusybox:latest\fR به تصویر ارجاع دهد)، امضاها با استفاده از آدرس‌هایی به شکل زیر قابل دسترسی هستند:
> \fIbase\fP\fB/\fR\fInamespaces\fP\fB/\fR\fIname\fP\fB@\fR\fIdigest-algo\fP\fB=\fR\fIdigest-value\fP\fB/signature-\fR\fIindex\fP

.PP
که در آن \fIdigest-algo\fP\fB:\fR\fIdigest-value\fP یک خلاصه (digest) مانیفست است که برای ارجاع به مانیفست تصویر مربوطه قابل استفاده است (یعنی حتی اگر کاربر با استفاده از تگ به تصویر ارجاع داده باشد، محل ذخیره امضا همیشه با استفاده از مراجع خلاصه تفکیک می‌شود). توجه داشته باشید که در نشانی‌های اینترنتی استفاده‌شده برای امضاها، \fIdigest-algo\fP و \fIdigest-value\fP با نویسه \fB=\fR از هم جدا می‌شوند، نه با \fB:\fR مانند زمانی که از طریق API مخزن docker/distribution به مانیفست دسترسی پیدا می‌کنید.

.PP
درون نشانی اینترنتی، \fIindex\fP یک عدد صحیح ده‌دهی (در قالب استاندارد) است که از ۱ شروع می‌شود. امضاها در نشانی‌هایی با مقادیر متوالی \fIindex\fP ذخیره می‌شوند؛ برای خواندن همه آن‌ها، از \fIindex\fP=1 شروع کنید و خواندن امضاها و افزایش \fIindex\fP را تا زمانی که امضاهایی با این مقادیر وجود دارند ادامه دهید. به همین ترتیب، برای افزودن یک امضای دیگر به تصویر، اولین \fIindex\fP را که وجود ندارد پیدا کنید و سپس امضای جدید را با استفاده از آن مقدار ذخیره نمایید.

.PP
هیچ روشی برای فهرست کردن امضاهای موجود به جز پیمایش در مقادیر متوالی \fIindex\fP وجود ندارد، و هیچ راهی برای بارگیری همه امضاها به صورت یکجا نیست.

.SS "مثال‌ها (Examples)"
برای یک تصویر docker/distribution که به صورت
\fBbusybox@sha256:817a12c32a39bbe394944ba49de563e085f1d3c5266eb8e9723256bc4448680e\fR
در دسترس است (یا به عنوان \fBbusybox:latest\fR در صورتی که برچسب \fBlatest\fR به مانیفستی با همین خلاصه اشاره داشته باشد)، و با پیکربندی \fBregistries.d\fR که نشانی \fBlookaside\fR را برابر با \fBhttps://example.com/lookaside\fR برای همان تصویر تعیین کرده است، برای دانلود تمام امضاها به نشانی‌های اینترنتی زیر دسترسی خواهد شد:
> - \fBhttps://example.com/lookaside/library/busybox@sha256=817a12c32a39bbe394944ba49de563e085f1d3c5266eb8e9723256bc4448680e/signature-1\fR
> - \fBhttps://example.com/lookaside/library/busybox@sha256=817a12c32a39bbe394944ba49de563e085f1d3c5266eb8e9723256bc4448680e/signature-2\fR
> - …

.PP
برای تصویر موجود به عنوان \fBexample.com/ns1/ns2/ns3/repo@somedigest:digestvalue\fR و همان نشانی \fBlookaside\fR، امضاها در نشانی زیر در دسترس خواهند بود:
> \fBhttps://example.com/lookaside/ns1/ns2/ns3/repo@somedigest=digestvalue/signature-1\fR

.PP
و به همین ترتیب.

.SH "افزونه API مخزن docker/distribution در اوپن‌شیفت ((OpenShift) docker/distribution API extension)"
مطابق با https://github.com/openshift/origin/pull/12504 ، رجیستری تعبیه‌شده در OpenShift همچنین یک افزونه برای API مخزن docker/distribution ارائه می‌دهد که امکان دسترسی ساده‌تر به امضاها را با استفاده از نقطه پایانی همان API فراهم می‌کند.

.PP
این API ذاتاً مختص OpenShift نیست (به عنوان مثال کلاینت نیازی به دانستن نقطه پایانی API در OpenShift ندارد و اطلاعات هویتی کافی برای دسترسی به سرور API مخزن docker/distribution برای دسترسی به امضاها نیز کفایت می‌کند)، و روش ارجح برای پیاده‌سازی ذخیره‌سازی امضا در رجیستری‌ها است.

.PP
برای مستندات اصلی بالادستی این API، به آدرس https://github.com/openshift/openshift-docs/pull/3556 مراجعه کنید.

.PP
برای خواندن امضا، هر کاربری که به تصویر دسترسی دارد می‌تواند از مسیر \fB/extensions/v2/…/signatures/…\fR برای خواندن آرایه‌ای از امضاها استفاده کند. فقط از اشیاء امضایی استفاده کنید که مقدار \fBversion\fR آن‌ها برابر با \fB2\fR و مقدار \fBtype\fR آن‌ها برابر با \fBatomic\fR باشد، و امضا را از فیلد \fBcontent\fR بخوانید؛ سایر فیلدهای شیء امضا را نادیده بگیرید.

.PP
برای افزودن یک امضای منفرد، یک شیء جدید با \fBversion\fR برابر با \fB2\fR، \fBtype\fR برابر با \fBatomic\fR و \fBcontent\fR تنظیم‌شده روی امضا را از طریق متد \fBPUT\fR ارسال کنید. همچنین \fBname\fR را روی یک نام منحصر‌به‌فرد به شکل
\fIdigest\fP\fB@\fR\fIper-image-name\fP
تنظیم نمایید، که در آن \fIdigest\fP خلاصه مانیفست تصویر (استفاده‌شده در آدرس اینترنتی) و \fIper-image-name\fP هر شناسه یکتایی است.

.PP
برای افزودن بیش از یک امضا، آن‌ها را یک به یک بیفزایید. این API اجازه حذف امضاها را نمی‌دهد.

.PP
توجه داشته باشید از آنجا که امضاها درون اشیاء تصویری سطح کلاستر ذخیره می‌شوند (یعنی فضاهای نام مختلف نمی‌توانند مجموعه‌های متفاوتی از امضاها را به همان تصویر مرتبط کنند)، به‌روزرسانی امضاها نیازمند دسترسی در سطح کلاستر به منبع \fBimagesignatures\fR است (که به‌طور پیش‌فرض در اختیار نقش \fBsystem:image-signer\fR قرار دارد).

.SH "مخازن تعبیه‌شده در اوپن‌شیفت (OpenShift-embedded registries)"
رجیستری تعبیه‌شده در OpenShift رابط معمول docker/distribution API را پیاده‌سازی می‌کند و همچنین تصاویر را از طریق REST API اوپن‌شیفت (موجود در سرورهای «API master») ارائه می‌دهد.

.PP
توجه: نسخه‌های ۱.۵ و جدیدتر OpenShift از افزونه API مخزن docker/distribution که در بالا توضیح داده شد پشتیبانی می‌کنند، که راه‌اندازی آن آسان‌تر است و معمولاً باید ترجیح داده شود. برای جزئیات در خصوص استفاده از نسخه‌های قدیمی‌تر OpenShift به خواندن ادامه دهید.

.PP
مطابق با https://github.com/openshift/origin/pull/9181 ، امضاها از طریق API اوپن‌شیفت ارائه می‌شوند (یعنی برای دسترسی به تصویر کامل، استفاده از هر دو API لازم است، به ویژه دانستن آدرس‌ها برای هر دو نقطه پایانی docker/distribution و OpenShift API master).

.PP
برای خواندن امضا، هر کاربری که به تصویر دسترسی دارد می‌تواند از منبع دارای فضای نام \fBimagestreamimages\fR برای خواندن شیء \fBImage\fR و آرایه \fBSignatures\fR آن استفاده کند. فقط از اشیاء \fBImageSignature\fR که مقدار \fBType\fR آن‌ها برابر با \fBatomic\fR است استفاده کرده و امضا را از \fBContent\fR بخوانید؛ سایر فیلدهای شیء \fBImageSignature\fR را نادیده بگیرید.

.PP
برای افزودن یا حذف امضاها، از منبع سراسری کلاستر (بدون فضای نام) \fBimagesignatures\fR استفاده کنید، با \fBType\fR تنظیم‌شده روی \fBatomic\fR و \fBContent\fR تنظیم‌شده روی امضا. نام‌های امضا باید قالبی به شکل
\fIdigest\fP\fB@\fR\fIper-image-name\fP
داشته باشند که در آن \fIdigest\fP خلاصه مانیفست تصویر (در نام‌گذاری OpenShift به عنوان «image name») و \fIper-image-name\fP هر شناسه یکتا است.

.PP
توجه داشته باشید از آنجا که امضاها درون اشیاء تصویری سطح کلاستر ذخیره می‌شوند (یعنی فضاهای نام مختلف نمی‌توانند مجموعه‌های متفاوتی از امضاها را به همان تصویر مرتبط کنند)، به‌روزرسانی امضاها نیازمند دسترسی در سطح کلاستر به منبع \fBimagesignatures\fR است (که به‌طور پیش‌فرض در اختیار نقش \fBsystem:image-signer\fR قرار دارد)، و حذف امضاها به شدت نهی شده است (زیرا امضا را از تمامی فضاهای نامی که شامل همان تصویر هستند حذف می‌کند).