SSH-TPM-AGENT(1) ssh-tpm-agent manual SSH-TPM-AGENT(1)

ssh-tpm-agent - عامل ssh-agent برای کلیدهای TPM 2.0

ssh-tpm-agent [OPTIONS]

ssh-tpm-agent --print-socket

ssh-tpm-agent --install-user-units

ssh-tpm-agent برنامه‌ای است که با استفاده از یک ماژول پلتفرم معتمد (TPM) کلیدهایی ایجاد می‌کند تا امکان استفاده از کلیدهای خصوصی بسته‌بندی‌شده (wrapped) را برای احراز هویت با کلید عمومی فراهم سازد.

-l PATH

مسیر سوکت UNIX برای باز کردن.

پیش‌فرض $XDG_RUNTIME_DIR/ssh-tpm-agent.sock است.

-A PATH

سوکت‌های جایگزین (fallback) ssh-agent جهت جستجوی کلیدهای تکمیلی.

--print-socket

سوکت را در STDIN چاپ می‌کند.

--key-dir PATH

مسیر دایرکتوری برای جستجوی کلیدهای مهروموم‌شدهٔ (sealed) TPM در آن.

پیش‌فرض ~/.ssh است.

--no-load

به‌طور پیش‌فرض کلیدهای مهروموم‌شدهٔ TPM را از ~/.ssh بارگذاری نمی‌کند.

-o, --owner-password

درخواست گذرواژهٔ مالک.

--no-cache

عامل گذرواژه‌های کلید را در حافظهٔ موقت (cache) نگه نخواهد داشت.

--hierarchy HIERARCHY

کلیدهای سلسله‌مراتب (hierarchy keys) را از پیش در عامل بارگذاری می‌کند.

برای اطلاعات بیشتر، Hierarchy Keys را ببینید.

سلسله‌مراتب‌های موجود:

•owner, o
•endorsement, e
•null, n
•platform, p

-d

فعال‌سازی ثبت گزارش‌های اشکال‌زدایی (debug).

--install-user-units

واحدهای سیستمی systemd و پیکربندی‌های sshd را برای استفاده از ssh-tpm-agent به‌عنوان یک عامل کلید میزبان (hostkey agent) نصب می‌کند.

--swtpm

کلیدها را به جای TPM واقعی درون یک نمونهٔ swtpm ذخیره می‌کند. این یک قابلیت امنیتی نیست و کلیدهای شما به‌صورت امن ذخیره نمی‌شوند.

همچنین می‌تواند از طریق متغیر محیطی SSH_TPM_AGENT_SWTPM فعال شود.

ssh-tpm-agent می‌تواند به عنوان یک جایگزین مستقیم (drop-in) برای ssh-agent استفاده شود و به همان شیوه کار می‌کند.

$ ssh-tpm-keygen
# افزودن ~/.ssh/id_ecdsa.pub به حساب‌های گیت‌هاب خود
$ ssh-tpm-agent &
$ export SSH_AUTH_SOCK=$(ssh-tpm-agent --print-socket)
$ ssh git@github.com

برای نحوه استفاده از keygen، به ssh-tpm-keygen(1) مراجعه کنید.

ssh-tpm-agent از سازوکار بازگشت (fallback) به ssh-agentهای مختلف پشتیبانی می‌کند. عامل‌ها را می‌توان با گزینه -A اضافه کرد. این کار باعث می‌شود ssh-tpm-agent برای یافتن کلیدها به تمام عامل‌های موجود رجوع کند (fan-out).

این قابلیت زمانی کاربردی است که چندین کلید از پیاده‌سازی‌های مختلف عامل دارید، اما می‌خواهید تنها به یک سوکت متکی باشید.

# راه‌اندازی معمول ssh-agent
$ eval $(ssh-agent)
# ایجاد یک کلید قدرتمند RSA
$ ssh-keygen -t rsa -b 4096 -f id_rsa -C ssh-agent
...
The key fingerprint is:
SHA256:zLSeyU/6NKHGEvyZLA866S1jGqwdwdAxRFff8Z2N1i0 ssh-agent
$ ssh-add id_rsa
Identity added: id_rsa (ssh-agent)
# چاپ کلید بسیار طولانی
$ ssh-add -L
ssh-rsa AAAAB3NzaC1yc[...]8TWynQ== ssh-agent
# ایجاد کلید روی TPM
$ ssh-tpm-keygen -C ssh-tpm-agent
Generating a sealed public/private ecdsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_ecdsa):
Enter passphrase (empty for no passphrase):
Confirm passphrase:
Your identification has been saved in /home/user/.ssh/id_ecdsa.tpm
Your public key has been saved in /home/user/.ssh/id_ecdsa.pub
The key fingerprint is:
SHA256:PoQyuzOpEBLqT+xtP0dnvyBVL6UQTiQeCWN/EXIxPOo
The key's randomart image is the color of television, tuned to a dead channel.
# اجرای ssh-tpm-agent با یک سوکت پراکسی
$ ssh-tpm-agent -A "${SSH_AUTH_SOCK}" &
$ export SSH_AUTH_SOCK="$(ssh-tpm-agent --print-socket)"
# پروکسی کردن کلیدها از ssh-agent توسط ssh-tpm-agent
$ ssh-add -L
ssh-rsa AAAAB3NzaC1yc[...]8TWynQ== ssh-agent
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNo[...]q4whro= ssh-tpm-agent

می‌توان از ssh-tpm-agent برای ارائه کلیدهای میزبان (host keys) یک سرور ssh نیز استفاده کرد. دستور ssh-tpm-hostkeys دارای گزینه‌های مفیدی است که به نصب پیکربندی‌ها و سرویس‌های systemd روی سیستم کمک می‌کنند. این کار یک سوکت سیستمی برای ssh-tpm-agent در مسیر /var/tmp/ssh-tpm-agent.sock ایجاد می‌کند.

$ sudo ssh-tpm-keygen -A
2023/09/03 17:03:08 INFO Generating new ECDSA host key
2023/09/03 17:03:08 INFO Wrote /etc/ssh/ssh_tpm_host_ecdsa_key.tpm
2023/09/03 17:03:08 INFO Generating new RSA host key
2023/09/03 17:03:15 INFO Wrote /etc/ssh/ssh_tpm_host_rsa_key.tpm
$ sudo ssh-tpm-hostkeys --install-system-units
Installed /usr/lib/systemd/system/ssh-tpm-agent.service
Installed /usr/lib/systemd/system/ssh-tpm-agent.socket
Installed /usr/lib/systemd/system/ssh-tpm-genkeys.service
Enable with: systemctl enable --now ssh-tpm-agent.socket
$ sudo ssh-tpm-hostkeys --install-sshd-config
Installed /etc/ssh/sshd_config.d/10-ssh-tpm-agent.conf
Restart sshd: systemd restart sshd
$ systemctl enable --now ssh-tpm-agent.socket
$ systemd restart sshd
$ sudo ssh-tpm-hostkeys
ecdsa-sha2-nistp256 AAAAE2V[...]YNwqWY0= root@localhost
ssh-rsa AAAAB3NzaC1ycA[...]N1Jg3fLQKSe7f root@localhost
$ ssh-keyscan -t ecdsa localhost
# localhost:22 SSH-2.0-OpenSSH_9.4
localhost ecdsa-sha2-nistp256 AAAAE2V[...]YNwqWY0=

به‌عنوان راهکار جایگزین، می‌توان از گزینه‌های نصب توکار صرف‌نظر کرد و تنها یک پیکربندی الحاقی (drop-in) برای sshd در مسیر /etc/ssh/sshd_config.d با محتوای زیر قرار داد.

HostKeyAgent /var/tmp/ssh-tpm-agent.sock
HostKey /etc/ssh/ssh_tpm_host_ecdsa_key.pub
HostKey /etc/ssh/ssh_tpm_host_rsa_key.pub

تراشه‌های TPM قادرند با استفاده از سلسله‌مراتب‌های سطح‌بالا، کلیدهای ایستا (static keys) ایجاد کنند. این قابلیت به کاربر امکان می‌دهد کلیدهایی بسازد که برای طول عمر دستگاه، برای مالک فعلی دستگاه، یا برای نشست (session) جاری دستگاه معتبر باشند. این کلیدها نیز، مانند سایر کلیدهای ایجادشده توسط ssh-tpm-keygen، هرگز از TPM خارج نمی‌شوند و همواره می‌توان آن‌ها را دوباره ایجاد کرد.

این کلیدها می‌توانند از پیش در ssh-tpm-agent بارگذاری شوند.

$ ssh-tpm-agent --hierarchy owner &
$ export SSH_AUTH_SOCK="$(ssh-tpm-agent --print-socket)"
$ ssh-add -l
2048 SHA256:yt7A20tcRnzgaD2ATgAXSNWy9sP6wznysp3SkoK3Gj8 Owner hierarchy key (RSA)
256 SHA256:PmEsMeh/DwFP04iUaWLNeX4maMR6r1vfqw1BbbdFjIg Owner hierarchy key (ECDSA)

برای استفاده به‌همراه sshd، بخش عمومی (public) این کلیدها را می‌توان با ترکیب -A و --hierarchy ایجاد کرد.

$ ssh-tpm-keygen -A --hierarchy owner
2025/03/10 21:57:08 INFO Generating new hierarcy host key algorithm=RSA hierarchy=owner
2025/03/10 21:57:10 INFO Wrote public key filename=/etc/ssh/ssh_tpm_host_rsa_key.pub
2025/03/10 21:57:10 INFO Generating new hierarcy host key algorithm=ECDSA hierarchy=owner
2025/03/10 21:57:10 INFO Wrote public key filename=/etc/ssh/ssh_tpm_host_ecdsa_key.pub

این فایل‌ها می‌توانند طبق روال معمول همراه با HostKey در ssh_config استفاده شوند.

سلسله‌مراتب‌های مختلف کلید، ویژگی‌ها و طول عمر متفاوتی دارند.

سلسله‌مراتب endorsement کلیدهای ساخته‌شده برای طول عمر دستگاه را ذخیره می‌کند. این سلسله‌مراتب نباید در طول عمر دستگاه تغییر کند.

سلسله‌مراتب owner کلیدهای ساخته‌شده برای مالک دستگاه را نگهداری می‌کند. این کلیدها هنگام اجرای دستور tpm2_clear(1) روی پلتفرم بازنشانی (rotate) می‌شوند؛ کاری که باید هنگام انتقال دستگاه به مالک جدید انجام گیرد.

سلسله‌مراتب null کلیدهای ساخته‌شده برای نشست جاری را ذخیره می‌کند. منظور از نشست معمولاً یک چرخه راه‌اندازی و خاموشی (power cycle) دستگاه است.

نکته: این ویژگی آزمایشی است. ssh-tpm-agent اشیاء TPM را در حین اجرا در وضعیت بارگذاری‌شده نگه می‌دارد. اگر تلاش کنید هم‌زمان از کلیدهای سلسله‌مراتب به همراه کلیدهای معمول ایجادشده توسط ssh-tpm-keygen استفاده کنید، حافظه برخی دستگاه‌های TPM ممکن است به پایان برسد.

SSH_TPM_AUTH_SOCK

مسیر یک سوکت دامنه یونیکس (unix-domain socket) را جهت ارتباط با کارگزار (agent) مشخص می‌کند.

پیش‌فرض آن /var/tmp/ssh-tpm-agent.sock است.

SSH_ASKPASS

اگر ssh-tpm-agent و سایر برنامه‌ها نیاز به خواندن گذرواژه داشته باشند، در صورت امکان به‌طور پیش‌فرض از ترمینال استفاده می‌کنند. چنانچه ترمینالی در دسترس نباشد، از اجرای برنامه‌ای که SSH_ASKPASS به آن اشاره دارد استفاده خواهند کرد.

برای اطلاعات بیشتر، ssh(1) را ذیل بخش ENVIRONMENT ببینید.

SSH_ASKPASS_REQUIRE

امکان کنترل نحوه استفاده از برنامه askpass را فراهم می‌کند. مقادیر معتبر عبارتند از:
•never اطمینان می‌دهد که ssh هرگز برای استفاده از برنامه askpass تلاش نخواهد کرد.
•prefer استفاده از برنامه askpass را ترجیح می‌دهد.
•force اطمینان می‌دهد که تمامی ورودی‌های عبارت‌عبور (passphrase) از برنامه askpass استفاده خواهند کرد.

برای اطلاعات بیشتر، ssh(1) را ذیل بخش ENVIRONMENT ببینید.

SSH_TPM_AGENT_SWTPM

مشخص می‌کند که آیا ssh-tpm-agent باید از پشتیبان (backend) swtpm استفاده کند یا خیر. هر مقدار غیرخالی به عنوان درست (true) در نظر گرفته می‌شود.

SSH_TPM_LANDLOCK

در صورت تنظیم، ssh-tpm-agent و سایر برنامه‌ها در صورت امکان محدودسازی امنیتی (sandbox) مبتنی بر landlock را اعمال می‌کنند.

به‌طور پیش‌فرض غیرفعال است.

برای اطلاعات بیشتر، landlock(7) را ببینید.

~/ssh/id_rsa.tpm, ~/ssh/id_ecdsa.tpm

شامل کلیدهای خصوصی ssh مورد استفاده توسط ssh-tpm-agent است. این‌ها فایل‌های کلید TPM 2.0 TSS هستند و به‌صورت امن توسط TPM بسته‌بندی (wrap) شده‌اند. می‌توان آن‌ها را به‌صورت عمومی به اشتراک گذاشت چرا که تنها توسط همان TPM که روی آن ایجاد شده‌اند قابل استفاده هستند؛ با این حال احتمالاً بهتر است این کار را انجام ندهید.

~/ssh/id_rsa.pub, ~/ssh/id_ecdsa.pub

شامل کلیدهای عمومی ssh است. این کلیدها را می‌توان به‌صورت عمومی به اشتراک گذاشت و قالب آن‌ها مشابه کلیدهای ایجادشده توسط ssh-keygen(1) است.

/run/user/$UID/ssh-tpm-agent.sock

مسیر پیش‌فرض سوکت UNIX کاربر برای ssh-tpm-agent. مورد استفاده توسط کاربران به‌صورت مجزا.

/var/tmp/ssh-tpm-agent.sock

مسیر پیش‌فرض سوکت UNIX در سطح سیستم برای ssh-tpm-agent. مورد استفاده برای کلیدهای میزبان (host keys) و سیستم.

ssh-agent(1), ssh(1), ssh-tpm-keygen(1), ssh-keygen(1)

مشخصات ASN.1 برای فایل‌های کلید TPM 2.0 https://www.hansenpartnership.com/draft-bottomley-tpm2-keys.html

ذخیرهٔ کلیدهای ssh درون TPM: ssh-tpm-agent https://linderud.dev/blog/store-ssh-keys-inside-the-tpm-ssh-tpm-agent

2026-08-10 ssh-tpm-agent v0.9.0