نام (NAME)

pageant - کارگزار احراز هویت SSH در PuTTY

خلاصه دستور (SYNOPSIS)

pageant ( -X | -T | --permanent | --debug | --foreground ) [ [ --encrypted ] key-file... ]
pageant [ [ --encrypted ] key-file... ] --exec command [ args... ]
pageant -a [ --encrypted ] key-file...
pageant ( -d | -r | --public | --public-openssh ) key-identifier...
pageant ( -D | -R )
pageant -l [ --fptype format ]
pageant --askpass prompt

توضیحات (DESCRIPTION)

دستور pageant هم یک کارگزار احراز هویت SSH است و هم ابزاری برای ارتباط با کارگزاری که از قبل در حال اجراست.

هنگامی که به عنوان کارگزار SSH اجرا می‌شود، روی یک سوکت دامنه یونیکس (Unix-domain socket) به اتصالات فرآیندهای کلاینتی که تحت شناسه کاربری شما در حال اجرا هستند گوش می‌دهد. کلاینت‌ها می‌توانند کلیدهای خصوصی SSH را در کارگزار بارگذاری کنند یا درخواست امضای یک پیام مشخص توسط کلیدی که از قبل در کارگزار موجود است را ارسال نمایند. این امر امکان احراز هویت بدون نیاز به ورود مجدد رمزعبور را برای برنامه‌های کلاینت SSH فراهم می‌کند، به شرطی که Pageant کلیدی را در بر داشته باشد که کارساز (سرور) مقصد آن را می‌پذیرد.

همچنین pageant می‌تواند خودش به عنوان یک برنامه کلاینت عمل کند و با کارگزاری که از قبل در حال اجراست برای افزودن یا حذف کلیدها، فهرست کردن آن‌ها یا استخراج بخش عمومی (Public half) کلیدها ارتباط برقرار کند.

پروتکل کارگزار مورد استفاده توسط pageant با ابزارهای PuTTY و همچنین سایر پیاده‌سازی‌ها از قبیل کلاینت SSH نرم‌افزار OpenSSH و ssh-agent(1) سازگار است. برخی از ویژگی‌های pageant با استفاده از افزونه‌های پروتکل پیاده‌سازی شده‌اند، بنابراین تنها در صورتی کار خواهند کرد که pageant در هر دو طرف ارتباط حضور داشته باشد.

برای اجرای pageant به عنوان کارگزار، باید با استفاده از یک گزینه مشخص کنید که طول عمر آن چقدر باشد. معمولاً احتمالاً می‌خواهید Pageant به اندازه مدت زمان نشست ورود به سیستم باقی بماند، که در این صورت باید بسته به اینکه نشست ورود شما گرافیکی (GUI) است یا صرفاً مبتنی بر ترمینال، به ترتیب از -X یا -T استفاده کنید. به عنوان مثال، در اسکریپت راه‌اندازی نشست X ممکن است بنویسید:

eval $(pageant -X)

این دستور باعث می‌شود Pageant شروع به کار کند، سرور X را برای متوجه شدن پایان نشست شما زیر نظر بگیرد (و سپس خودش نیز پایان یابد)، و دستوراتی از شل را در خروجی استاندارد چاپ کند که متغیرهای محیطی مورد نیاز فرآیندهای کلاینت را برای یافتن کارگزار در حال اجرا تنظیم می‌نمایند.

در یک نشست ورود مبتنی بر ترمینال، می‌توانید تقریباً دقیقاً همین کار را با -T انجام دهید:

eval $(pageant -T)

این امر موجب می‌شود که Pageant طول عمر خود را به ترمینال کنترلی شما گره بزند: هنگامی که خارج می‌شوید و دستگاه ترمینال دیگر با نشست شما مرتبط نیست، Pageant متوجه خواهد شد که دیگر ترمینال کنترلی ندارد و به صورت خودکار پایان خواهد یافت.

در هر یک از این حالت‌ها، می‌توانید یک یا چند کلید خصوصی را نیز به عنوان آرگومان‌های خط فرمان اضافی بیاورید، برای مثال:

eval $(pageant -T ~/.ssh/key.ppk)

در این حالت، Pageant بلافاصله عبارت عبور (Passphrase) کلیدها را (در صورت وجود) درخواست می‌کند و کارگزار را در حالی راه‌اندازی می‌کند که کلیدها از قبل به صورت رمزگشایی‌شده (متن آشکار) بارگذاری شده‌اند. درخواست عبارت عبور در صورت در دسترس بودن از ترمینال کنترلی استفاده خواهد کرد، یا در غیر این صورت، در صورت موجود بودن از رابط گرافیکی (GUI) استفاده می‌کند. (روش درخواست را می‌توان با گزینه‌های --gui-prompt یا --tty-prompt تغییر داد.) در صورتی که هیچ‌کدام در دسترس نباشد، امکان درخواست عبارت عبور وجود نخواهد داشت.

روش دیگر این است که می‌توانید کارگزار را با کلیدهایی که به صورت رمزگذاری‌شده ذخیره شده‌اند راه‌اندازی کنید:

eval $(pageant -T --encrypted ~/.ssh/key.ppk)

در این حالت، Pageant در زمان راه‌اندازی عبارت عبور را درخواست نمی‌کند؛ بلکه اولین باری که کلاینتی برای استفاده از کلید تلاش کند آن را درخواست خواهد کرد. (Pageant برای نمایش پنجره درخواست عبارت عبور در هنگام نیاز، به دسترسی رابط گرافیکی نیاز دارد، مگر اینکه در حالت --debug اجرا شود.)

برای استفاده از Pageant جهت ارتباط با یک کارگزار موجود، می‌توانید با استفاده از -a کلیدهای جدید را اضافه کنید، با استفاده از -l فهرست اثرانگشت‌ها (Fingerprints) و توضیحات کلیدهای فعلی را مشاهده کنید، با --public یا --public-openssh بخش عمومی کامل هر کلید را استخراج نمایید، با -d یا -D به ترتیب یک کلید مشخص یا تمام کلیدها را حذف کنید، یا با -r یا -R به ترتیب رمزگذاری مجدد یک کلید مشخص یا تمام کلیدها را درخواست نمایید.

طول عمر (LIFETIME)

گزینه‌های زیر حالت‌های طول عمر نامیده می‌شوند. همگی از Pageant درخواست می‌کنند در حالت کارگزار عمل کند؛ هر یک روش متفاوتی را برای راه‌اندازی Pageant و آگاهی از زمان خاموش شدن آن مشخص می‌کند.

-X: برنامه Pageant اتصالی به نمایشگر X شما باز می‌کند و هنگامی که آن اتصال قطع شود، خاتمه می‌یابد. این کار طول عمری مشابه نشست ورود گرافیکی شما به آن می‌دهد، بنابراین در این حالت برای اجرا از طریق یک اسکریپت راه‌اندازی مانند .xsession مناسب است. کارگزار واقعی یک زیرفرآیند خواهد بود؛ فرآیند اصلی Pageant بلافاصله پس از چاپ دستورات تنظیم متغیرهای محیطی در خروجی استاندارد پایان می‌یابد که این متغیرها باید در هر فرآیندی که مایل به برقراری ارتباط با کارگزار است بارگذاری شوند.

رویکرد معمول اجرای دستور زیر است:

eval $(pageant -X)

در اسکریپت راه‌اندازی نشست X. با این حال، احتمالات دیگری نیز وجود دارد، مانند هدایت خروجی استاندارد `pageant -X' به فایلی که سپس توسط هر شل جدید فراخوانی (source) شود.

-T: دستور Pageant طول عمر خود را به طول عمر نشست ورود در حال اجرا روی ترمینال کنترلی‌اش گره می‌زند، با تشخیص زمانی که دیگر ترمینال کنترلی ندارد (که این اتفاق به طور خودکار به عنوان اثر جانبی خاتمه فرآیند رهبر نشست رخ می‌دهد). همانند -X، برنامه Pageant دستورات متغیرهای محیطی را در خروجی استاندارد چاپ می‌کند.
--exec command: دستور Pageant فرمان داده‌شده را به عنوان یک زیرفرآیند اجرا می‌کند، در حالی که متغیرهای محیطی مناسب برای دسترسی به کارگزاری که راه‌اندازی کرده از قبل در آن بارگذاری شده است. هنگامی که زیرفرآیند خاتمه یابد، Pageant نیز خاتمه می‌یابد.

تمام آرگومان‌های موجود در خط فرمان Pageant پس از --exec به عنوان بخشی از دستور اجرایی تلقی خواهند شد، حتی اگر شبیه به گزینه‌ها یا فایل‌های کلید معتبر دیگر Pageant به نظر برسند.

--permanent: دستور Pageant یک زیرفرآیند را منشعب (fork) می‌کند تا کارگزار باشد و دستورات متغیرهای محیطی را مشابه -X و -T در خروجی استاندارد چاپ می‌کند. با این حال، در این حالت هیچ تلاشی برای محدود کردن طول عمر خود به هیچ روشی نمی‌کند؛ بلکه تا زمانی که به صورت دستی کشته (kill) نشود، به طور دائم اجرا خواهد شد. متغیر محیطی SSH_AGENT_PID، که توسط دستورات چاپ‌شده به وسیله Pageant مقداردهی می‌شود، امکان یافتن فرآیند کارگزار را برای این منظور فراهم می‌سازد.

این گزینه توصیه نمی‌شود، زیرا هر روشی برای کشتن دستی کارگزار این خطر را به همراه دارد که نشست به طور غیرمنتظره پیش از اجرای آن خاتمه یابد.

--debug: برنامه Pageant در پیش‌زمینه (foreground) و بدون انشعاب اجرا می‌شود. دستورات راه‌اندازی متغیرهای محیطی خود را در خروجی استاندارد چاپ می‌کند و سپس تمام فعالیت‌های کارگزار را نیز در خروجی استاندارد ثبت (log) می‌کند؛ به هرگونه درخواست عبارت عبور باید در ورودی استاندارد پاسخ داده شود. این حالت برای اشکال‌زدایی کارهایی که خود Pageant انجام می‌دهد یا کارهایی که فرآیند دیگری روی آن انجام می‌دهد، مفید است.
--foreground: همانند --debug، برنامه Pageant در پیش‌زمینه و بدون انشعاب اجرا خواهد شد. دستورات راه‌اندازی متغیرهای محیطی خود را در خروجی استاندارد چاپ می‌کند. برخلاف --debug، برنامه Pageant به طور خودکار فعالیت کارگزار را در خروجی استاندارد ثبت نمی‌کند، و همچنین درخواست‌های عبارت عبور را به ورودی استاندارد تحمیل نمی‌کند. این حالت زمانی مفید است که Pageant توسط یک فرآیند والد ایجاد شود که آن را کنترل می‌کند یا به صورت برنامه‌نویسی‌شده با Pageant در تعامل است.

پس از اینکه Pageant دستورات راه‌اندازی محیطی خود را چاپ کرد، خروجی استاندارد خود را می‌بندد. بنابراین اگر فرآیند والد آن را در یک پایپ برای دریافت دستورات راه‌اندازی محیطی اجرا کرده باشد، می‌تواند به راحتی تا زمان دریافت EOF بخواند، بدون اینکه نیازی به دانستن تعداد خطوط خروجی مورد انتظار داشته باشد.

گزینه‌های کلاینت (CLIENT OPTIONS)

گزینه‌های زیر به Pageant می‌گویند که در حالت کلاینت عمل کند و از طریق متغیرهای محیطی که باید قبلاً تنظیم شده باشند، با یک کارگزار موجود تماس بگیرد.

-a key-files: فایل یا فایل‌های کلید خصوصی مشخص‌شده را بارگذاری کرده و آن‌ها را به کارگزار در حال اجرا اضافه می‌کند. مگر اینکه --encrypted نیز مشخص شده باشد، pageant در صورت لزوم با درخواست عبارت عبور آن‌ها (با همان گزینه‌های رابط کاربری موجود در حالت کارگزار)، آن‌ها را رمزگشایی خواهد کرد.

فایل‌های کلید خصوصی باید در قالب فایل .ppk نرم‌افزار PuTTY باشند.

-l: فهرست کلیدهای موجود در کارگزار در حال اجرا را نمایش می‌دهد. اثرانگشت و رشته توضیحات هر کلید نشان داده خواهد شد. (از گزینه -E برای تغییر قالب اثرانگشت استفاده کنید.)

کلیدهایی که در استفاده بعدی به عبارت عبور نیاز دارند با عنوان `encrypted' فهرست می‌شوند. کلیدهایی که می‌توانند با -r به این وضعیت بازگردند با عنوان `re-encryptable' مشخص می‌شوند.

--public key-identifiers: بخش عمومی هر کلید مشخص‌شده را در قالب استاندارد RFC 4716 (چندخطی، با شروع از `---- BEGIN SSH2 PUBLIC KEY ----') چاپ می‌کند.

هر key-identifier می‌تواند یکی از موارد زیر باشد:

•: نام فایلی که حاوی کلید است؛ خواه کلید کامل (مجدداً در قالب .ppk) یا صرفاً بخش عمومی آن.
•: رشته توضیحات کلید، همان‌طور که توسط pageant -l نمایش داده می‌شود.
•: مقدار کافی از یکی از قالب‌های اثرانگشت کلید به گونه‌ای که در میان کلیدهای بارگذاری‌شده فعلی در کارگزار یکتا باشد.

اگر Pageant بتواند با تفسیر key-identifier به هر یک از این روش‌ها یک کلید را به طور یکتا شناسایی کند، فرض می‌کند که آن کلید همان کلید مد نظر شما بوده است. اگر نتواند، باید جزئیات بیشتری را مشخص کنید.

اگر متوجه شدید که رشته key-identifier مورد نظر شما می‌تواند به درستی به عنوان بیش از یکی از انواع شناسایی فوق تفسیر شود، می‌توانید با افزودن پیشوند به شرح زیر ابهام‌زدایی کنید:

`file:': برای نشان دادن اینکه یک نام فایل است.
`comment:': برای نشان دادن اینکه یک رشته توضیحات است.
`fp:': برای نشان دادن اینکه یک اثرانگشت است؛ هر قالب اثرانگشتی تطبیق داده خواهد شد.
`sha256:' یا `md5:': برای نشان دادن اینکه اثرانگشتی با یک قالب مشخص است.
`sha256-cert:' یا `md5-cert:': برای نشان دادن اینکه اثرانگشتی با قالبی خاص است، و به طور ویژه با اثرانگشت کلید عمومی شامل گواهی (در صورت وجود) مطابقت دارد.

--public-openssh key-identifiers, -L key-identifiers: بخش عمومی هر کلید مشخص‌شده را در قالب تک‌خطی مورد استفاده OpenSSH چاپ می‌کند که برای قرار دادن در فایل‌های .ssh/authorized_keys مناسب است.
-d key-identifiers: هر کلید مشخص‌شده را از حافظه کارگزار حذف می‌کند، به طوری که کارگزار دیگر آن را به کلاینت‌ها ارائه نمی‌دهد مگر اینکه دوباره با استفاده از pageant -a بارگذاری شود.
-D: تمام کلیدها را از حافظه کارگزار حذف کرده و آن را کاملاً خالی می‌کند.
-r key-identifiers: هر کلید مشخص‌شده را در حافظه کارگزار «رمزگذاری مجدد» می‌کند - یعنی هر نسخه متن آشکار را فراموش می‌کند، به طوری که دفعه بعد که از کلید استفاده می‌شود مجدداً از کاربر عبارت عبور خواسته شود. (برای امکان‌پذیر بودن این امر، کلید باید قبلاً با گزینه --encrypted اضافه شده باشد.)

(نگهداری کلیدهای رمزگذاری‌شده یکی از قابلیت‌های اختصاصی Pageant است، بنابراین بعید است این گزینه و -R با سایر کارگزارها کار کنند.)

-R: تمام کلیدهای ممکن را در حافظه کارگزار «رمزگذاری مجدد» می‌کند. (اگر کلیدها قبلاً با گزینه --encrypted اضافه نشده باشند، ممکن است برخی کلیدها به صورت متن آشکار باقی بمانند.)
--test-sign key-identifier
--test-sign-with-flags=flags key-identifier: داده‌های دلخواه را با کلید داده‌شده امضا می‌کند. این حالت احتمالاً تنها در زمان آزمایش خود pageant مفید خواهد بود.

داده‌های مورد نظر برای امضا از ورودی استاندارد دریافت شده، توسط کارگزار با کلید شناسایی‌شده توسط key-identifier امضا می‌شوند و امضای حاصل در خروجی استاندارد منتشر می‌شود (به عنوان یک داده باینری در قالبی که مشخصات SSH تعیین کرده است).

مقدار flags عددی است که ترکیبی از بیت‌های فلگ تعریف‌شده توسط پروتکل کارگزار SSH را نشان می‌دهد.

جایگزین SSH-ASKPASS (SSH-ASKPASS REPLACEMENT)

--askpass prompt: با این گزینه، pageant به جای انجام عملکردهای کارگزار SSH، به عنوان جایگزینی برای ssh-askpass(1) عمل می‌کند. این گزینه ممکن است زمانی مفید باشد که سبک اعلان گرافیکی Pageant را ترجیح دهید، که در بازخورد بصری خود در مقایسه با سایر پیاده‌سازی‌های ssh-askpass(1)، نشت اطلاعات مربوط به طول عبارت عبور را به حداقل می‌رساند.

دستور pageant --askpass رابط استاندارد ssh-askpass(1) را پیاده‌سازی می‌کند: می‌توان یک اعلان (Prompt) را برای نمایش (به عنوان یک تک‌آرگومان) به آن ارسال کرد و در صورت موفقیت، عبارت عبور را در خروجی استاندارد چاپ کرده و وضعیت خروج صفر را بازمی‌گرداند. معمولاً از متغیر محیطی SSH_ASKPASS استفاده می‌کنید تا به سایر برنامه‌ها بگویید از pageant به این شیوه استفاده کنند.

گزینه‌ها (OPTIONS)

-v: حالت پرگو (Verbose). هنگامی که Pageant در حالت کارگزار اجرا می‌شود، این گزینه باعث می‌شود تمام فعالیت‌های کارگزار را در خطای استاندارد ثبت کند. برای مثال، ممکن است دستور زیر را اجرا کنید:

eval $(pageant -X -v 2>~/.pageant.log)

و انتظار داشته باشید که فهرستی از تمام امضاهای درخواستی کلاینت‌های کارگزار در آن فایل گزارش جمع‌آوری شود.

اطلاعات گزارش همان اطلاعات تولیدشده توسط گزینه طول عمر --debug است، اما --debug آن را به خروجی استاندارد می‌فرستد (زیرا این هدف اصلی حالت اشکال‌زدایی است)، در حالی که -v در سایر حالت‌های طول عمر، داده‌های گزارش یکسان را به خطای استاندارد ارسال می‌کند (چرا که محصول جانبی هدف اصلی برنامه است). استفاده از -v در حالت --debug هیچ تاثیری ندارد: گزارش همچنان به خروجی استاندارد ارسال می‌شود.

-s, -c: دستور Pageant را وادار می‌کند تا دستورات راه‌اندازی متغیرهای محیطی خود را به ترتیب به سبک شل‌های POSIX / Bourne (-s) یا شل‌های C (-c) خروجی دهد. اگر هیچ‌یک از گزینه‌ها داده نشود، Pageant بر اساس اینکه آیا مقدار متغیر محیطی SHELL به `csh' ختم می‌شود یا خیر، حدس خواهد زد.
--symlink fixed-path: هنگام کار در حالت کارگزار، علاوه بر ایجاد یک سوکت شنیداری با نام یکتا، pageant یک پیوند نمادین (Symbolic link) نیز در fixed-path ایجاد (یا به‌روزرسانی) می‌کند که به آن سوکت اشاره دارد.

این امر امکان دسترسی به یک نمونه از کارگزار را با تنظیم متغیر محیطی SSH_AUTH_SOCK روی fixed-path فراهم می‌کند، به جای اینکه لازم باشد از مقداری که pageant در هنگام شروع ایجاد کرده استفاده شود. انتظار می‌رود این ویژگی عمدتاً برای اشکال‌زدایی مفید باشد.

--encrypted, --no-decrypt: هنگام افزودن کلیدها به کارگزار (در زمان راه‌اندازی یا پس از آن)، آن‌ها را تا اولین تلاش برای استفاده به صورت رمزگذاری‌شده نگه می‌دارد؛ در آن زمان عبارت عبور از کاربر درخواست خواهد شد. پس از رمزگشایی، کلیدی که به این شیوه اضافه شده است را می‌توان با گزینه‌های کلاینت -r یا -R «مجدداً رمزگذاری» کرد.

گزینه --encrypted برای فایل‌های کلیدی که عبارت عبور ندارند هیچ تفاوتی ایجاد نمی‌کند.

(ذخیره کلیدها به صورت رمزگذاری‌شده یکی از قابلیت‌های اختصاصی Pageant است؛ بعید است سایر پیاده‌سازی‌های کارگزار از آن پشتیبانی کنند.)

-E fingerprint-type, --fptype fingerprint-type: قالب اثرانگشت را برای چاپ مشخص می‌کند. تنها هنگام فهرست کردن اثرانگشت‌ها با -l کاربرد دارد. قالب‌های موجود عبارتند از sha256 (پیش‌فرض) و md5.
--gui-prompt, --tty-prompt: دستور Pageant را وادار می‌کند تا با روشی خاص (رابط گرافیکی یا ترمینال) عبارت عبور کلید را درخواست کند، به جای اینکه همان‌طور که در بالا توضیح داده شد سعی در حدس زدن مناسب‌ترین روش داشته باشد. (این گزینه‌ها هر زمان که یک فایل کلید نیازمند رمزگشایی فوری به pageant مشخص شده باشد، و در حالت --askpass، مربوط می‌شوند.)
--help: خلاصه کوتاهی از گزینه‌های خط فرمان را چاپ کرده و پایان می‌یابد.
--version, -V: نسخه Pageant را چاپ می‌کند.
--: باعث می‌شود تمام آرگومان‌های بعدی به عنوان نام فایل کلید در نظر گرفته شوند، حتی اگر شبیه گزینه باشند.