نام (NAME)

gpg-agent - دیمن مدیریت کلیدهای مخفی و احراز هویت برای GnuPG

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

gpg-agent [--homedir dir] [--options file] [options]
gpg-agent [--homedir dir] [--options file] [options] --server
gpg-agent [--homedir dir] [--options file] [options] --daemon [command_line]

توضیحات (DESCRIPTION)

gpg-agent یک دیمن برای مدیریت کلیدهای مخفی (خصوصی) به صورت مستقل از هرگونه پروتکل است. این برنامه به عنوان یک پشتیبان (بک‌اند) برای gpg و gpgsm و همچنین برای چند ابزار دیگر به کار می‌رود.

این عامل در صورت نیاز به طور خودکار توسط gpg، gpgsm، gpgconf یا gpg-connect-agent راه‌اندازی می‌شود. بنابراین دلیلی برای راه‌اندازی دستی آن وجود ندارد. در صورتی که می‌خواهید از Secure Shell Agent موجود در آن استفاده کنید، می‌توانید عامل را با دستور زیر راه‌اندازی کنید:

gpg-connect-agent /bye

اگر می‌خواهید عامل در حال اجرا را به صورت دستی متوقف کنید، می‌توانید با خیال راحت این کار را با دستور زیر انجام دهید:

gpgconf --kill gpg-agent

شما همیشه باید خطوط زیر را به پروندهٔ .bashrc خود یا هر پروندهٔ راه‌اندازی دیگری که برای تمام فراخوانی‌های پوسته استفاده می‌شود اضافه کنید:

GPG_TTY=$(tty)
export GPG_TTY

مهم است که این متغیر محیطی همیشه خروجی دستور tty را منعکس کند. برای سیستم‌های W32 این گزینه مورد نیاز نیست.

لطفاً اطمینان حاصل کنید که یک برنامهٔ مناسب pinentry تحت نام پروندهٔ پیش‌فرض (که وابسته به سیستم است) نصب شده باشد یا از گزینهٔ pinentry-program برای تعیین نام کامل آن برنامه استفاده کنید. اغلب مفید است که یک پیوند نمادین از pinentry واقعیِ مورد استفاده (مانند ‘/usr/bin/pinentry-gtk’) به مورد موردانتظار (مانند ‘/usr/bin/pinentry’) ایجاد شود.

دستورات (COMMANDS)

دستورات تفاوتی با گزینه‌ها ندارند به جز اینکه فقط یک دستور مجاز است.

--version

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

--help

-h

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

--dump-options

فهرستی از تمام گزینه‌ها و دستورات موجود را چاپ می‌کند. توجه داشته باشید که نمی‌توانید این دستور را مخفف کنید.

--server

در حالت سرور اجرا می‌شود و در stdin منتظر دستورات می‌ماند. حالت پیش‌فرض، ایجاد یک سوکت و گوش دادن به دستورات در آنجا است.

--daemon [command line]

برنامه gpg-agent را به عنوان یک دیمن آغاز می‌کند؛ یعنی آن را از کنسول جدا کرده و در پس‌زمینه اجرا می‌کند.

به عنوان یک روش جایگزین می‌توانید یک فرآیند جدید به عنوان فرزند gpg-agent ایجاد کنید: gpg-agent --daemon /bin/sh. به این ترتیب یک پوسته جدید با محیطی که به درستی تنظیم شده دریافت می‌کنید؛ پس از خروج از این پوسته، gpg-agent ظرف چند ثانیه خاتمه می‌یابد.

--supervised

در پیش‌زمینه اجرا می‌شود، گزارش‌ها را به طور پیش‌فرض به stderr می‌فرستد، و به توصیف‌کننده‌های فایل ارائه‌شده که از قبل باید به سوکت‌های شنونده متصل شده باشند گوش می‌دهد. این گزینه منسوخ شده است و در Windows پشتیبانی نمی‌شود.

اگر در ‘common.conf’ گزینه no-autostart تنظیم شده باشد، هرگونه تلاش برای راه‌اندازی نادیده گرفته خواهد شد.

در حالت --supervised، تا زمانی که توصیف‌کننده‌های فایل مختلف در متغیر محیطی LISTEN_FDNAMES مشخص شده باشند، می‌توان آن‌ها را برای استفاده به عنوان انواع مختلف سوکت (مانند ssh، extra) ارائه داد (برای اطلاعات بیشتر در مورد این قرارداد، sd_listen_fds(3) را در برخی توزیع‌های Linux ببینید).

گزینه‌ها (OPTIONS)

گزینه‌ها ممکن است در خط فرمان یا پس از حذف دو خط تیره ابتدایی، در پرونده تنظیمات استفاده شوند.

--options file

تنظیمات را به جای پرونده تنظیمات پیش‌فرض اختصاصی کاربر، از file می‌خواند. پرونده تنظیمات پیش‌فرض ‘gpg-agent.conf’ نام دارد و انتظار می‌رود مستقیماً در دایرکتوری ‘.gnupg’ زیر دایرکتوری خانگی کاربر قرار داشته باشد. اگر از این گزینه در یک پرونده گزینه‌ها استفاده شود، نادیده گرفته خواهد شد.

--homedir dir

نام دایرکتوری خانگی را به dir تنظیم می‌کند. اگر از این گزینه استفاده نشود، دایرکتوری خانگی به طور پیش‌فرض ‘~/.gnupg’ خواهد بود. این گزینه تنها در صورتی که در خط فرمان داده شود شناخته می‌شود. همچنین بر هر دایرکتوری خانگی تعیین‌شده از طریق متغیر محیطی ‘GNUPGHOME’ یا (در سیستم‌های Windows) به وسیله مدخل رجیستری HKCU\Software\GNU\GnuPG:HomeDir اولویت دارد.

در سیستم‌های Windows امکان نصب GnuPG به عنوان یک برنامه قابل‌حمل (portable) وجود دارد. در این حالت تنها این گزینه خط فرمان در نظر گرفته می‌شود و تمام روش‌های دیگر برای تنظیم دایرکتوری خانگی نادیده گرفته می‌شوند.

-v

--verbose

اطلاعات بیشتری را هنگام اجرا در خروجی نمایش می‌دهد. می‌توانید با دادن چندین دستور verbose به gpg-agent، مانند ‘-vv’، میزان پرگویی (جزئیات خروجی) را افزایش دهید.

-q

--quiet

تلاش می‌کند تا جای ممکن بی‌صدا باشد.

--batch

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

--faked-system-time epoch

این گزینه فقط برای آزمودن کاربرد دارد؛ زمان سیستم را به عقب یا جلو به epoch تنظیم می‌کند که تعداد ثانیه‌های سپری‌شده از ابتدای سال 1970 است.

--debug-level level

انتخاب سطح اشکال‌زدایی برای بررسی مشکلات. level می‌تواند یک مقدار عددی یا یک کلمهٔ کلیدی باشد:

نحوهٔ نگاشت این پیام‌ها به پرچم‌های اشکال‌زدایی واقعی مشخص نشده است و ممکن است در نسخه‌های جدیدتر این برنامه تغییر کند. با این حال، آنها با دقت انتخاب شده‌اند تا بیشترین کمک را به اشکال‌زدایی برسانند.

--debug flags

تنظیم پرچم‌های اشکال‌زدایی. همهٔ پرچم‌ها با هم OR می‌شوند و flags می‌تواند در ساختار نحوی C (مانند 0x0042) یا به صورت فهرستی از نام پرچم‌ها که با کاما از هم جدا شده‌اند، داده شود. برای دریافت فهرستی از تمام پرچم‌های پشتیبانی‌شده می‌توان از تک‌واژهٔ "help" استفاده کرد. این گزینه تنها برای اشکال‌زدایی سودمند است و رفتار آن ممکن است در هر زمانی بدون اطلاع قبلی تغییر کند.

--debug-all

همانند --debug=0xffffffff

--debug-wait n

هنگام اجرا در حالت سرور، پیش از ورود به حلقهٔ پردازش اصلی، n ثانیه درنگ کرده و pid را چاپ می‌کند. این کار زمان کافی برای اتصال یک اشکال‌زدا را فراهم می‌سازد.

--debug-quick-random

این گزینه از استفاده از سطح کیفیت تصادفی بسیار امن (GCRY_VERY_STRONG_RANDOM در Libgcrypt) جلوگیری کرده و تمام درخواست‌ها را به کیفیت تصادفی استاندارد تقلیل می‌دهد. این گزینه تنها برای آزمودن به کار می‌رود و نباید برای هیچ کلیدی در محیط عملیاتی استفاده شود. این گزینه تنها زمانی مؤثر است که در خط فرمان داده شود.

در GNU/Linux، راه دیگر برای تولید سریع کلیدهای ناامن، استفاده از rngd برای پر کردن استخر آنتروپی هسته با داده‌های تصادفی با کیفیت پایین‌تر است. rngd معمولاً توسط بستهٔ rng-tools ارائه می‌شود. می‌توان آن را به این صورت اجرا کرد: ‘sudo rngd -f -r /dev/urandom’.

--debug-pinentry

این گزینه اطلاعات اشکال‌زدایی اضافی مربوط به Pinentry را فعال می‌کند. در حال حاضر این گزینه تنها زمانی سودمند است که همراه با --debug 1024 استفاده شود.

--no-detach

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

--steal-socket

در حالت --daemon، gpg-agent یک gpg-agent در حال اجرای دیگر را تشخیص داده و اجازه نمی‌دهد نمونهٔ جدیدی آغاز شود. از این گزینه می‌توان برای نادیده گرفتن این بررسی استفاده کرد: فرایند جدید gpg-agent تلاش خواهد کرد سوکت‌های ارتباطی را از فرایند در حال اجرا در اختیار بگیرد و در هر صورت شروع به کار کند. از این گزینه به‌طور کلی نباید استفاده شود.

-s

--sh

-c

--csh

قالب‌بندی خروجی اطلاعات در حالت دیمن به‌ترتیب جهت استفاده در شل استاندارد Bourne یا C-shell. حالت پیش‌فرض، حدس زدن آن بر اساس متغیر محیطی SHELL است که تقریباً در تمام موارد درست عمل می‌کند.

--grab

--no-grab

به pinentry اعلام می‌کند که صفحه‌کلید و ماوس را در انحصار خود بگیرد (grab کند). این گزینه باید روی X-Serverها برای جلوگیری از حملات شنود در X (حملات X-sniffing) استفاده شود. هرگونه استفاده از گزینهٔ --grab بر گزینهٔ استفاده‌شدهٔ --no-grab اولویت داشته و آن را لغو می‌کند. مقدار پیش‌فرض --no-grab است.

--log-file file

تمام خروجی‌های ثبت گزارش را به انتهای file می‌افزاید. این کار برای مشاهدهٔ آنچه که agent در عمل انجام می‌دهد بسیار مفید است. از ‘socket://’ برای ثبت گزارش در سوکت استفاده کنید. اگر در پلتفرم ویندوز نه فایل گزارش و نه توصیف‌گر فایل گزارش تنظیم نشده باشد، ورودی رجیستری HKCU\Software\GNU\GnuPG:DefaultLogFile (در صورت تنظیم بودن) برای تعیین خروجی گزارش‌گیری استفاده می‌شود.

--no-allow-mark-trusted

به کلاینت‌ها اجازه نمی‌دهد کلیدها را به‌عنوان مورد اعتماد علامت‌گذاری کنند، یعنی آن‌ها را در فایل ‘trustlist.txt’ قرار دهند. این کار پذیرش ناخواسته و سهوی کلیدهای Root-CA را برای کاربران دشوارتر می‌کند.

--no-user-trustlist

لیست اعتماد کاربر را کاملاً نادیده می‌گیرد و تنها لیست اعتماد سراسری (‘/etc/gnupg/trustlist.txt’) را در نظر می‌گیرد. این امر به‌طور ضمنی شامل گزینهٔ --no-allow-mark-trusted است.

--sys-trustlist-name file

نام پیش‌فرض لیست اعتماد سراسری را از "trustlist.txt" به file تغییر می‌دهد. اگر file شامل هیچ اسلشی نباشد و با "~/" شروع نشود، در دایرکتوری پیکربندی سیستم (‘/etc/gnupg’) جستجو می‌شود.

--allow-preset-passphrase

این گزینه امکان استفاده از gpg-preset-passphrase را برای مقداردهی اولیهٔ حافظهٔ پنهان داخلی gpg-agent با گذرواژه‌ها فراهم می‌کند.

--no-allow-loopback-pinentry

--allow-loopback-pinentry

به کلاینت‌ها اجازه می‌دهد یا مانع آن‌ها می‌شود که از قابلیت‌های loopback pinentry استفاده کنند؛ برای جزئیات به گزینهٔ pinentry-mode مراجعه کنید. حالت مجاز (Allow) پیش‌فرض است.

گزینهٔ --force در دستور Assuan با نام DELETE_KEY نیز توسط این گزینه کنترل می‌شود: در صورتی که loopback pinentry غیرمجاز باشد، این گزینه نادیده گرفته می‌شود.

--no-allow-external-cache

به Pinentry اعلام می‌کند قابلیت‌هایی را که از یک حافظهٔ پنهان خارجی برای گذرواژه‌ها استفاده می‌کنند، فعال نکند.

برخی از محیط‌های رومیزی ترجیح می‌دهند تمام اطلاعات اعتبارسنجی را با یک گذرواژهٔ اصلی باز کنند و ممکن است یک Pinentry نصب کرده باشند که برای پیاده‌سازی چنین سیاستی از یک حافظهٔ پنهان خارجی اضافی استفاده می‌کند. با استفاده از این گزینه، به Pinentry توصیه می‌شود از چنین حافظهٔ پنهانی استفاده نکند و در عوض همیشه گذرواژهٔ درخواستی را از کاربر بپرسد.

--allow-emacs-pinentry

به Pinentry اعلام می‌کند قابلیت‌های انتقال ورود گذرواژه به یک نمونهٔ در حال اجرای Emacs را مجاز بداند. نحوهٔ دقیق انجام این کار به نسخهٔ Pinentry مورد استفاده بستگی دارد.

--ignore-cache-for-signing

این گزینه به gpg-agent اجازه می‌دهد حافظهٔ نهان عبارت عبور را برای تمام عملیات‌های امضا دور بزند. توجه داشته باشید که گزینه‌ای برای هر نشست نیز به منظور کنترل این رفتار وجود دارد، اما این گزینهٔ خط فرمان اولویت دارد.

--default-cache-ttl n

مدت‌زمان معتبر بودن یک مدخل حافظهٔ نهان را روی n ثانیه تنظیم می‌کند. مقدار پیش‌فرض 600 ثانیه است. هر بار که به یک مدخل در حافظهٔ نهان دسترسی پیدا شود، تایمر آن مدخل بازنشانی می‌شود. برای تنظیم حداکثر طول عمر یک مدخل، از max-cache-ttl استفاده کنید. توجه داشته باشید که اگر هیچ کلاینتی درخواست عملیات حافظهٔ نهان ندهد، ممکن است عبارت عبور ذخیره‌شده بلافاصله از حافظه خارج نشود. این امر به دلیل یک تابع خانه‌داری داخلی است که تنها هر چند ثانیه یک بار اجرا می‌شود.

--default-cache-ttl-ssh n

مدت‌زمان معتبر بودن یک مدخل حافظهٔ نهانِ استفاده‌شده برای کلیدهای SSH را روی n ثانیه تنظیم می‌کند. مقدار پیش‌فرض 1800 ثانیه است. هر بار که به یک مدخل در حافظهٔ نهان دسترسی پیدا شود، تایمر آن مدخل بازنشانی می‌شود. برای تنظیم حداکثر طول عمر یک مدخل، از max-cache-ttl-ssh استفاده کنید.

--max-cache-ttl n

حداکثر مدت‌زمان معتبر بودن یک مدخل حافظهٔ نهان را روی n ثانیه تنظیم می‌کند. پس از این مدت، یک مدخل حافظهٔ نهان منقضی خواهد شد حتی اگر اخیراً به آن دسترسی پیدا شده باشد یا با استفاده از gpg-preset-passphrase تنظیم شده باشد. مقدار پیش‌فرض 2 ساعت (7200 ثانیه) است.

--max-cache-ttl-ssh n

حداکثر مدت‌زمان معتبر بودن یک مدخل حافظهٔ نهانِ استفاده‌شده برای کلیدهای SSH را روی n ثانیه تنظیم می‌کند. پس از این مدت، یک مدخل حافظهٔ نهان منقضی خواهد شد حتی اگر اخیراً به آن دسترسی پیدا شده باشد یا با استفاده از gpg-preset-passphrase تنظیم شده باشد. مقدار پیش‌فرض 2 ساعت (7200 ثانیه) است.

--enforce-passphrase-constraints

محدودیت‌های عبارت عبور را با اجازه ندادن به کاربر برای دور زدن آن‌ها از طریق دکمهٔ ``Take it anyway'' اجباری می‌کند.

--min-passphrase-len n

حداقل طول یک عبارت عبور را تعیین می‌کند. هنگام وارد کردن عبارت عبور جدیدی که کوتاه‌تر از این مقدار باشد، هشداری نمایش داده خواهد شد. پیش‌فرض 8 است.

--min-passphrase-nonalpha n

حداقل تعداد ارقام یا نویسه‌های خاصِ موردنیاز در یک عبارت عبور را تعیین می‌کند. هنگام وارد کردن عبارت عبور جدیدی با تعداد ارقام یا نویسه‌های خاص کمتر از این مقدار، هشداری نمایش داده خواهد شد. پیش‌فرض 1 است.

--check-passphrase-pattern file

--check-sym-passphrase-pattern file

عبارت عبور را در برابر الگوی داده‌شده در file بررسی می‌کند. هنگام وارد کردن عبارت عبور جدیدی که با یکی از این الگوها مطابقت داشته باشد، هشداری نمایش داده خواهد شد. اگر file شامل هیچ خط موربی (اسلش) نباشد و با "~/" شروع نشود، در پوشهٔ پیکربندی سیستم (‘/etc/gnupg’) جستجو می‌شود. پیش‌فرض این است که از هیچ پروندهٔ الگویی استفاده نشود. نگارش دوم این گزینه فقط هنگام ایجاد یک کلید متقارن جدید به کار می‌رود تا امکان استفاده از الگوهای متفاوت برای چنین عبارت‌های عبوری فراهم شود.

نکتهٔ امنیتی: مشخص شده است که بررسی عبارت عبور در برابر فهرستی از الگوها یا حتی در برابر یک واژه‌نامهٔ کامل، برای وادار کردن به استفاده از عبارت‌های عبور مناسب چندان مؤثر نیست. کاربران به زودی راه‌هایی برای دور زدن چنین سیاستی پیدا خواهند کرد. سیاست بهتر، آموزش رفتارهای امنیتی مناسب به کاربران و در صورت تمایل اجرای منظم یک ابزار شکستن عبارت عبور بر روی عبارت‌های عبور تمام کاربران برای شناسایی موارد بسیار ساده است.

--max-passphrase-days n

اگر n روز از آخرین تغییر گذشته باشد، از کاربر می‌خواهد عبارت عبور را تغییر دهد. با تنظیم بودن --enforce-passphrase-constraints، کاربر نمی‌تواند این بررسی را دور بزند.

--enable-passphrase-history

این گزینه هنوز کاری انجام نمی‌دهد.

--pinentry-invisible-char char

این گزینه از Pinentry درخواست می‌کند تا از char برای نمایش نویسه‌های پنهان استفاده کند. char باید یک رشتهٔ UTF-8 تک‌نویسه‌ای باشد. یک Pinentry ممکن است این درخواست را بپذیرد یا نپذیرد.

--pinentry-timeout n

این گزینه از Pinentry می‌خواهد که پس از n ثانیه بدون ورودی کاربر، با پایان مهلت زمانی (timeout) مواجه شود. مقدار پیش‌فرض 0 از pinentry درخواست پایان زمان نمی‌کند، با این حال در این حالت ممکن است Pinentry از مقدار مهلت زمانی پیش‌فرض خود استفاده کند. ممکن است Pinentry این درخواست را بپذیرد یا نپذیرد.

--pinentry-formatted-passphrase

این گزینه از Pinentry می‌خواهد هنگام درخواست عبارت عبور جدید از کاربر در زمانی که پنهان‌سازی عبارت عبور غیرفعال است، قالب‌بندی عبارت عبور را فعال کند.

اگر قالب‌بندی عبارت عبور فعال باشد، تمام نویسه‌های فاصله نشکن (non-breaking space) از عبارت عبور واردشده حذف می‌شوند. قالب‌بندی عبارت عبور بیش از همه در ترکیب با عبارت‌های عبور تولیدشده با ویژگی GENPIN در برخی از برنامه‌های Pinentry مفید است. توجه داشته باشید که چنین عبارت عبور تولیدشده‌ای، در صورت عدم دستکاری توسط کاربر، از بررسی تمام محدودیت‌های عبارت عبور عبور می‌کند، زیرا این محدودیت‌ها در عمل موجب تضعیف عبارت عبور تولیدشده می‌شوند.

--pinentry-program filename

از برنامه filename به عنوان ورودی PIN استفاده می‌کند. مقدار پیش‌فرض به نوع نصب وابسته است. در پیکربندی پیش‌فرض، نام pinentry پیش‌فرض ‘pinentry’ است؛ اگر آن پرونده وجود نداشته باشد اما پرونده ‘pinentry-basic’ موجود باشد، از دومی استفاده می‌شود.

در بستر Windows پیش‌فرض استفاده از نخستین برنامه موجود از این فهرست است: ‘bin\pinentry.exe’, ‘..\Gpg4win\bin\pinentry.exe’, ‘..\Gpg4win\pinentry.exe’, ‘..\GNU\GnuPG\pinentry.exe’, ‘..\GNU\bin\pinentry.exe’, ‘bin\pinentry-basic.exe’ که در آن نام پرونده‌ها نسبت به پوشه نصب GnuPG هستند.

--pinentry-touch-file filename

به‌طور پیش‌فرض، نام پرونده سوکتی که gpg-agent روی آن به درخواست‌ها گوش می‌دهد به Pinentry تحویل داده می‌شود تا بتواند پیش از خروج، آن پرونده را لمس (touch) کند (این کار را تنها در حالت curses انجام می‌دهد). این گزینه پرونده ارسال‌شده به Pinentry را به filename تغییر می‌دهد. نام ویژه /dev/null ممکن است برای غیرفعال کردن کامل این قابلیت استفاده شود. توجه داشته باشید که Pinentry آن پرونده را ایجاد نخواهد کرد، بلکه تنها زمان دسترسی و تغییر آن را به‌روزرسانی می‌کند.

--scdaemon-program filename

از برنامه filename به عنوان دیمن کارت هوشمند (Smartcard) استفاده می‌کند. مقدار پیش‌فرض به نوع نصب بستگی دارد و می‌تواند با دستور gpgconf نمایش داده شود.

--disable-scdaemon

از ابزار scdaemon استفاده نمی‌کند. این گزینه قابلیت انجام عملیات‌های کارت هوشمند را غیرفعال می‌کند. توجه داشته باشید که فعال کردن این گزینه در زمان اجرا، فرایند scdaemon که از قبل انشعاب‌یافته (fork شده) را متوقف نمی‌کند.

--disable-check-own-socket

gpg-agent برای شناسایی سوکت سرقت‌شده از یک خودآزمایی دوره‌ای استفاده می‌کند. این معمولاً به این معنی است که نمونه دوم gpg-agent سوکت را به دست گرفته است و پس از آن gpg-agent به کار خود پایان می‌دهد. این گزینه می‌تواند برای غیرفعال کردن این خودآزمایی به منظور اهداف اشکال‌زدایی استفاده شود.

--use-standard-socket

--no-use-standard-socket

--use-standard-socket-p

از GnuPG 2.1 به بعد همیشه از سوکت استاندارد استفاده می‌شود. این گزینه‌ها دیگر هیچ اثری ندارند. بنابراین دستور gpg-agent --use-standard-socket-p همیشه وضعیت موفقیت را بازمی‌گرداند.

--display string

--ttyname string

--ttytype string

--lc-ctype string

--lc-messages string

--xauthority string

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

--keep-tty

--keep-display

درخواست‌ها برای تغییر tty جاری یا متغیر DISPLAY در سامانه پنجرهٔ X را به ترتیب نادیده می‌گیرد. این برای قفل کردن pinentry جهت باز شدن در همان tty یا نمایشگری که عامل را در آن راه‌اندازی کرده‌اید مفید است.

--listen-backlog n

اندازهٔ صف اتصالات در انتظار را تنظیم می‌کند. پیش‌فرض 64 است.

--extra-socket name

سوکت اضافی به‌طور پیش‌فرض ایجاد می‌شود، می‌توانید از این گزینه برای تغییر نام سوکت استفاده کنید. برای غیرفعال کردن ایجاد سوکت، از ``none'' یا ``/dev/null'' برای name استفاده کنید.

همچنین روی اتصالات بومی gpg-agent در سوکت داده‌شده گوش می‌دهد. کاربرد مورد نظر برای این سوکت اضافی، راه‌اندازی بازارسال سوکت دامنه یونیکس (Unix domain socket forwarding) از یک ماشین دوردست به این سوکت در ماشین محلی است. سپس یک gpg در حال اجرا روی ماشین دوردست می‌تواند به gpg-agent محلی متصل شده و از کلیدهای خصوصی آن استفاده کند. این قابلیت، امکان رمزگشایی یا امضای داده‌ها را در یک ماشین دوردست بدون افشای کلیدهای خصوصی به ماشین دوردست فراهم می‌کند.

--enable-extended-key-format

--disable-extended-key-format

این گزینه‌ها منسوخ شده‌اند و هیچ تأثیری ندارند. قالب کلید گسترش‌یافته اکنون سال‌هاست استفاده می‌شود و از نگارش 2.1.12 پشتیبانی شده است. کلیدهای موجود با قالب قدیمی به محض دسترسی به آن‌ها به قالب جدید منتقل می‌شوند.

--enable-ssh-support

--enable-win32-openssh-support

--enable-putty-support

در بسترهای یونیکس پروتکل OpenSSH Agent همیشه فعال است، اما gpg-agent تنها در صورتی متغیر SSH_AUTH_SOCK را تنظیم می‌کند که گزینهٔ enable-ssh-support مشخص شده باشد. برخی توزیع‌های لینوکس از حضور این گزینه برای تصمیم‌گیری دربارهٔ اینکه آیا ssh-agent قدیمی باید راه‌اندازی شود یا خیر استفاده می‌کنند.

در ویندوز، پشتیبانی از پیاده‌سازی بومی ssh باید با استفاده از گزینهٔ enable-win32-openssh-support فعال شود. برای استفاده از gpg-agent به عنوان جایگزین Pageant در PuTTY، گزینهٔ enable-putty-support باید فعال باشد.

در این حالت کاری، عامل نه‌تنها پروتکل gpg-agent، بلکه پروتکل عامل مورد استفاده توسط OpenSSH (از طریق یک سوکت جداگانه یا Named Pipes) یا پروتکل مورد استفادهٔ PuTTY را نیز پیاده‌سازی می‌کند. در نتیجه، این قابلیت امکان استفاده از gpg-agent را به عنوان جایگزین مستقیم ssh-agent فراهم می‌آورد.

کلیدهای SSH که قرار است از طریق عامل استفاده شوند، ابتدا باید از طریق ابزار ssh-add به gpg-agent افزوده شوند. هنگامی که کلیدی افزوده می‌شود، ssh-add گذرواژهٔ پروندهٔ کلید ارائه‌شده را درخواست کرده و داده‌های کلید محافظت‌نشده را به عامل ارسال می‌کند؛ این امر موجب می‌شود gpg-agent عبارت عبوری (passphrase) درخواست کند که برای رمزگذاری کلید تازه‌دریافت‌شده و ذخیرهٔ آن در پوشهٔ اختصاصی gpg-agent استفاده می‌شود.

پس از اینکه کلیدی به این روش به gpg-agent افزوده شد، gpg-agent آمادهٔ استفاده از کلید خواهد بود.

نکته: در صورتی که gpg-agent یک درخواست امضا دریافت کند، ممکن است نیاز باشد برای عبارت عبور که برای رمزگشایی کلید ذخیره‌شده ضروری است، به کاربر اعلان داده شود. از آنجا که پروتکل ssh-agent سازوکاری برای اطلاع دادن به عامل دربارهٔ اینکه روی کدام نمایشگر/پایانه در حال اجراست ندارد، پشتیبانی ssh در gpg-agent از همان TTY یا نمایشگر X که gpg-agent در آن آغاز شده استفاده خواهد کرد. برای تغییر این نمایشگر به نمایشگر جاری، می‌توان از دستور زیر استفاده کرد:

gpg-connect-agent updatestartuptty /bye

اگرچه تمام مؤلفه‌های GnuPG تلاش می‌کنند در صورت نیاز gpg-agent را آغاز کنند، اما این امر برای پشتیبانی ssh امکان‌پذیر نیست زیرا ssh اطلاعی از آن ندارد. بنابراین اگر هیچ ابزار GnuPG که به عامل دسترسی داشته باشد اجرا نشده باشد، هیچ تضمینی وجود ندارد که ssh بتواند از gpg-agent برای احراز هویت استفاده کند. برای رفع این مشکل می‌توانید در صورت نیاز با استفاده از این دستور ساده gpg-agent را آغاز کنید:

gpg-connect-agent /bye

افزودن --verbose پیشرفت راه‌اندازی عامل را نشان می‌دهد.

گزینهٔ --enable-putty-support تنها در ویندوز موجود است و امکان استفاده از gpg-agent را با پیاده‌سازی ssh در putty فراهم می‌کند. این عملکرد شبیه به پشتیبانی معمولی ssh-agent است، اما طبق نیاز putty از صف پیام‌های ویندوز (Windows message queue) استفاده می‌کند.

ترتیب ارائه کلیدها به ssh عبارت است از:

gpg-connect-agent updatestartuptty /bye

gpg-connect-agent /bye

gpg-connect-agent 'GETINFO s2k_count' /bye
gpg-connect-agent 'GETINFO s2k_time' /bye

gpg-connect-agent 'GETINFO s2k_count_cal' /bye

مثال‌ها (EXAMPLES)

تنظیم متغیر محیطی GPG_TTY در پوستهٔ ورود (login shell) شما، برای مثال در اسکریپت آغازین ‘~/.bashrc’ اهمیت دارد:

export GPG_TTY=$(tty)

اگر پشتیبانی از عامل SSH (Ssh Agent Support) را فعال کرده‌اید، همچنین باید با افزودن این مورد به اسکریپت آغازین خود، ssh را از آن مطلع سازید:

unset SSH_AGENT_PID
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
  export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
fi

فایل‌ها (FILES)

برای کارکرد این عامل، به چند فایل پیکربندی نیاز است. به‌طور پیش‌فرض همگی آن‌ها در دایرکتوری خانگی فعلی قرار دارند (ببینید: [گزینه --homedir]).

gpg-agent.conf

این فایل پیکربندی استانداردی است که در هنگام راه‌اندازی توسط gpg-agent خوانده می‌شود. این فایل می‌تواند شامل هر گزینهٔ بلند معتبری باشد؛ نباید دو خط تیرهٔ ابتدایی وارد شوند و گزینه نباید مخفف گردد. این فایل پس از دریافت یک SIGHUP نیز مجدداً خوانده می‌شود، با این حال تنها چند گزینه واقعاً اثرگذار خواهند بود. این نام پیش‌فرض را می‌توان در خط فرمان تغییر داد (ببینید: [گزینه --options]). باید از این فایل پشتیبان تهیه کنید.

trustlist.txt

این فهرست کلیدهای مورد اعتماد است. باید از این فایل پشتیبان تهیه کنید.

خطوط توضیح، که با یک علامت هش (#) در ابتدای خط مشخص می‌شوند، و همچنین خطوط خالی نادیده گرفته می‌شوند. برای علامت‌گذاری یک کلید به عنوان مورد اعتماد، باید اثرانگشت آن را وارد کرده و پس از یک فاصله، حرف بزرگ S را قرار دهید. به‌طور اختیاری می‌توان از دونقطه برای جداسازی بایت‌های اثرانگشت استفاده کرد؛ این قابلیت امکان کپی و جای‌گذاری اثرانگشت را از خروجی فهرست کلیدها فراهم می‌کند. اگر در ابتدای خط یک علامت ! قرار گیرد، کلید صریحاً به عنوان نامعتمد علامت‌گذاری می‌شود.

در اینجا مثالی آورده شده است که در آن دو کلید به عنوان کاملاً مورد اعتماد و یکی به عنوان غیرقابل اعتماد علامت‌گذاری شده‌اند:

# CN=Wurzel ZS 3,O=Intevation GmbH,C=DE
A6935DD34EF3087973C706FC311AA2CCF733765B S
# CN=PCA-1-Verwaltung-02/O=PKI-1-Verwaltung/C=DE
DC:BD:69:25:48:BD:BB:7E:31:6E:BB:80:D3:00:80:35:D4:F8:A6:CD S
# CN=Root-CA/O=Schlapphuete/L=Pullach/C=DE
!14:56:98:D3:FE:9C:CA:5A:31:6E:BC:81:D3:11:4E:00:90:A3:44:C2 S

پیش از وارد کردن یک کلید به این فایل، باید از اصالت آن اطمینان حاصل کنید. نحوهٔ انجام این کار به سازمان شما بستگی دارد؛ ممکن است مدیر سیستم شما از قبل کلیدهایی را که به اندازهٔ کافی مورد اعتماد تشخیص داده شده‌اند، در این فایل وارد کرده باشد. مکان‌هایی که برای یافتن اثرانگشت یک گواهی ریشه (root certificate) باید بررسی شوند، نامه‌های دریافتی از CA یا وب‌سایت CA است (پس از اینکه ۱۰۰٪ اطمینان حاصل کردید که این واقعاً وب‌سایت همان CA است). ممکن است بخواهید با استفاده از [گزینه --no-allow-mark-trusted]، به‌روزرسانی‌های تعاملی این فایل را غیرفعال کنید. حتی ممکن است توصیه شود دسترسی‌های آن را به فقط‌خواندنی تغییر دهید تا این فایل به طور ناخواسته تغییر داده نشود.

به عنوان یک قابلیت ویژه، خط include-default یک فهرست سراسری از گواهی‌های مورد اعتماد را شامل می‌شود (برای مثال ‘/etc/gnupg/trustlist.txt’). این فهرست سراسری همچنین در صورتی که فهرست محلی در دسترس نباشد استفاده خواهد شد؛ [گزینه --no-user-trustlist] استفادهٔ انحصاری از این فهرست سراسری را اجباری می‌کند.

امکان افزودن فلگ‌های بیشتری پس از S برای استفاده توسط فراخواننده وجود دارد:

sshcontrol

این فایل زمانی استفاده می‌شود که پشتیبانی از پروتکل عامل پوستهٔ امن (secure shell agent) فعال شده باشد (ببینید: [گزینه --enable-ssh-support]). تنها کلیدهای موجود در این فایل در پروتکل SSH استفاده می‌شوند. باید از این فایل پشتیبان تهیه کنید.

این فایل به نفع ویژگی "Use-for-ssh" در فایل‌های کلید منسوخ شده است.

ابزار ssh-add می‌تواند برای افزودن مدخل‌های جدید به این فایل استفاده شود؛ همچنین می‌توانید آن‌ها را به صورت دستی اضافه کنید. خطوط توضیح، که با یک علامت هش در ابتدای خط مشخص می‌شوند، و همچنین خطوط خالی نادیده گرفته می‌شوند. هر مدخل با فاصله‌های خالی اختیاری آغاز می‌شود، به دنبال آن keygrip کلید که به صورت ۴۰ رقم هگزادسیمال مشخص شده است می‌آید، و به طور اختیاری مقدار TTL کش‌کردن به ثانیه و فیلد اختیاری دیگری برای فلگ‌های دلخواه قرار می‌گیرد. یک مقدار غیرصفر برای TTL، پیش‌فرض سراسری تنظیم‌شده توسط --default-cache-ttl-ssh را بازنویسی می‌کند.

تنها فلگ پشتیبانی‌شده confirm است. اگر این فلگ برای یک کلید پیدا شود، در هر بار استفاده از آن کلید یک پنجرهٔ pinentry برای تأیید استفاده از آن ظاهر می‌شود. این فلگ در صورتی که کلید جدیدی با استفاده از گزینهٔ -c از دستور ssh-add در gpg-agent بارگذاری شده باشد، به‌طور خودکار تنظیم می‌شود.

می‌توان پیش از keygrip یک علامت ! قرار داد تا یک مدخل غیرفعال شود.

مثال زیر دقیقاً یک کلید را فهرست می‌کند. توجه داشته باشید کلیدهایی که از طریق یک کارت هوشمند OpenPGP در کارت‌خوان فعال در دسترس هستند، به‌طور ضمنی به این فهرست اضافه می‌شوند؛ یعنی نیازی به فهرست کردن آن‌ها نیست.

# Key added on: 2011-07-20 20:38:46
# Fingerprint:  5e:8d:c4:ad:e7:af:6e:27:8a:d6:13:e4:79:ad:0b:81
34B62F25E277CF13D3C6BCEBFD3F85D08F0A864B 0 confirm

private-keys-v1.d/

این دایرکتوری محلی است که gpg-agent کلیدهای خصوصی را در آن ذخیره می‌کند. هر کلید در پرونده‌ای با نامی متشکل از keygrip و پسوند ‘key’ ذخیره می‌شود. شما باید از تمام پرونده‌های موجود در این دایرکتوری نسخهٔ پشتیبان تهیه کنید و بسیار دقت داشته باشید که این نسخهٔ پشتیبان در جایی محفوظ و دور از دسترس نگهداری شود.

توجه داشته باشید که در نصب‌های بزرگ‌تر، قرار دادن پرونده‌های از پیش تعریف‌شده در دایرکتوری ‘/etc/skel/.gnupg’ مفید است تا کاربران تازه ایجادشده با یک پیکربندی آماده‌به‌کار شروع کنند. برای کاربران فعلی، یک اسکریپت کمکی کوچک برای ایجاد این پرونده‌ها ارائه شده است (ببینید: [addgnupghome]).

سیگنال‌ها (SIGNALS)

یک gpg-agent در حال اجرا را می‌توان با استفاده از سیگنال‌ها کنترل کرد، یعنی با استفاده از دستور kill جهت ارسال یک سیگنال به فرایند.

در اینجا فهرستی از سیگنال‌های پشتیبانی‌شده آمده است:

SIGHUP

این سیگنال تمام عبارت‌های عبور کش‌شده را پاک می‌کند و اگر برنامه با یک پروندهٔ پیکربندی راه‌اندازی شده باشد، پروندهٔ پیکربندی مجدداً خوانده می‌شود. تنها گزینه‌های خاصی اعمال می‌شوند: quiet، verbose، debug، debug-all، debug-level، debug-pinentry، no-grab، pinentry-program، pinentry-invisible-char، default-cache-ttl، max-cache-ttl، ignore-cache-for-signing، s2k-count، no-allow-external-cache، allow-emacs-pinentry، no-allow-mark-trusted، disable-scdaemon، و disable-check-own-socket. گزینهٔ scdaemon-program نیز پشتیبانی می‌شود، اما با توجه به پیاده‌سازی فعلی که scdaemon را فقط یک بار فراخوانی می‌کند، فایدهٔ چندانی ندارد مگر اینکه scdaemon را به صورت دستی خاتمه دهید.

SIGTERM

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

SIGINT

فرایند را بلافاصله متوقف می‌کند.

SIGUSR1

اطلاعات داخلی را در پرونده گزارش تخلیه می‌کند.

SIGUSR2

این سیگنال برای اهداف داخلی استفاده می‌شود.

همچنین ببینید (SEE ALSO)

gpg(1), gpgsm(1), gpgconf(1), gpg-connect-agent(1), scdaemon(1)

مستندات کامل این ابزار در قالب یک راهنمای Texinfo نگهداری می‌شود. اگر GnuPG و برنامه info به‌درستی در سیستم شما نصب شده باشند، دستور

info gnupg

باید دسترسی به راهنمای کامل، شامل ساختار منو و نمایه را برای شما فراهم کند.