'\" t
.\"     Title: ssh-tpm-agent
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-08-10
.\"    Manual: ssh-tpm-agent manual
.\"    Source: ssh-tpm-agent v0.9.0
.\"  Language: English
.\"
.TH "SSH\-TPM\-AGENT" "1" "2026-08-10" "ssh\-tpm\-agent v0.9.0" "ssh\-tpm\-agent manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
ssh-tpm-agent \- عامل ssh\-agent برای کلیدهای TPM 2.0
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBssh\-tpm\-agent\fP [\fIOPTIONS\fP]
.sp
\fBssh\-tpm\-agent\fP \fB\-\-print\-socket\fP
.sp
\fBssh\-tpm\-agent\fP \fB\-\-install\-user\-units\fP
.SH "توضیحات (DESCRIPTION)"
.sp
\fBssh\-tpm\-agent\fP برنامه‌ای است که با استفاده از یک ماژول پلتفرم معتمد (TPM) کلیدهایی ایجاد می‌کند تا امکان استفاده از کلیدهای خصوصی بسته‌بندی‌شده (wrapped) را برای احراز هویت با کلید عمومی فراهم سازد.
.SH "گزینه‌ها (OPTIONS)"
.sp
\fB\-l\fP \fIPATH\fP
.RS 4
مسیر سوکت UNIX برای باز کردن.
.sp
پیش‌فرض \fI$XDG_RUNTIME_DIR/ssh\-tpm\-agent.sock\fP است.
.RE
.sp
\fB\-A\fP \fIPATH\fP
.RS 4
سوکت‌های جایگزین (fallback) ssh\-agent جهت جستجوی کلیدهای تکمیلی.
.RE
.sp
\fB\-\-print\-socket\fP
.RS 4
سوکت را در STDIN چاپ می‌کند.
.RE
.sp
\fB\-\-key\-dir\fP \fIPATH\fP
.RS 4
مسیر دایرکتوری برای جستجوی کلیدهای مهروموم‌شدهٔ (sealed) TPM در آن.
.sp
پیش‌فرض \fI~/.ssh\fP است.
.RE
.sp
\fB\-\-no\-load\fP
.RS 4
به‌طور پیش‌فرض کلیدهای مهروموم‌شدهٔ TPM را از \fI~/.ssh\fP بارگذاری نمی‌کند.
.RE
.sp
\fB\-o, \-\-owner\-password\fP
.RS 4
درخواست گذرواژهٔ مالک.
.RE
.sp
\fB\-\-no\-cache\fP
.RS 4
عامل گذرواژه‌های کلید را در حافظهٔ موقت (cache) نگه نخواهد داشت.
.RE
.sp
\fB\-\-hierarchy\fP \fIHIERARCHY\fP
.RS 4
کلیدهای سلسله‌مراتب (hierarchy keys) را از پیش در عامل بارگذاری می‌کند.
.sp
برای اطلاعات بیشتر، \fBHierarchy Keys\fP را ببینید.
.sp
سلسله‌مراتب‌های موجود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
owner, o
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
endorsement, e
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
null, n
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
platform, p
.RE
.RE
.sp
\fB\-d\fP
.RS 4
فعال‌سازی ثبت گزارش‌های اشکال‌زدایی (debug).
.RE
.sp
\fB\-\-install\-user\-units\fP
.RS 4
واحدهای سیستمی systemd و پیکربندی‌های sshd را برای استفاده از ssh\-tpm\-agent به‌عنوان یک عامل کلید میزبان (hostkey agent) نصب می‌کند.
.RE
.sp
\fB\-\-swtpm\fP
.RS 4
کلیدها را به جای TPM واقعی درون یک نمونهٔ swtpm ذخیره می‌کند. این یک قابلیت امنیتی نیست و کلیدهای شما به‌صورت امن ذخیره نمی‌شوند.
.sp
همچنین می‌تواند از طریق متغیر محیطی \fBSSH_TPM_AGENT_SWTPM\fP فعال شود.
.RE.SH "مثال‌ها (EXAMPLES)"
.SS "استفاده معمول از عامل"
.sp
\fBssh\-tpm\-agent\fP می‌تواند به عنوان یک جایگزین مستقیم (drop\-in) برای ssh\-agent استفاده شود و به همان شیوه کار می‌کند.
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-tpm\-keygen
# افزودن ~/.ssh/id_ecdsa.pub به حساب‌های گیت‌هاب خود
$ ssh\-tpm\-agent &
$ export SSH_AUTH_SOCK=$(ssh\-tpm\-agent \-\-print\-socket)
$ ssh git@github.com
.fam
.fi
.if n .RE
.sp
برای نحوه استفاده از keygen، به \fBssh\-tpm\-keygen\fP(1) مراجعه کنید.
.SS "پشتیبانی از عامل جایگزین (Agent fallback)"
.sp
\fBssh\-tpm\-agent\fP از سازوکار بازگشت (fallback) به ssh\-agentهای مختلف پشتیبانی می‌کند. عامل‌ها را می‌توان با گزینه \fI\-A\fP اضافه کرد. این کار باعث می‌شود \fBssh\-tpm\-agent\fP برای یافتن کلیدها به تمام عامل‌های موجود رجوع کند (fan\-out).
.sp
این قابلیت زمانی کاربردی است که چندین کلید از پیاده‌سازی‌های مختلف عامل دارید، اما می‌خواهید تنها به یک سوکت متکی باشید.
.sp
.if n .RS 4
.nf
.fam C
# راه‌اندازی معمول ssh\-agent
$ eval $(ssh\-agent)
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# ایجاد یک کلید قدرتمند RSA
$ ssh\-keygen \-t rsa \-b 4096 \-f id_rsa \-C ssh\-agent
\&...
The key fingerprint is:
SHA256:zLSeyU/6NKHGEvyZLA866S1jGqwdwdAxRFff8Z2N1i0 ssh\-agent
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-add id_rsa
Identity added: id_rsa (ssh\-agent)
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# چاپ کلید بسیار طولانی
$ ssh\-add \-L
ssh\-rsa AAAAB3NzaC1yc[...]8TWynQ== ssh\-agent
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# ایجاد کلید روی 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\*(Aqs randomart image is the color of television, tuned to a dead channel.
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# اجرای ssh\-tpm\-agent با یک سوکت پراکسی
$ ssh\-tpm\-agent \-A "${SSH_AUTH_SOCK}" &
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ export SSH_AUTH_SOCK="$(ssh\-tpm\-agent \-\-print\-socket)"
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
# پروکسی کردن کلیدها از ssh\-agent توسط ssh\-tpm\-agent
$ ssh\-add \-L
ssh\-rsa AAAAB3NzaC1yc[...]8TWynQ== ssh\-agent
ecdsa\-sha2\-nistp256 AAAAE2VjZHNhLXNo[...]q4whro= ssh\-tpm\-agent
.fam
.fi
.if n .RE.SS "کاربرد کلیدهای میزبان (Hostkeys usage)"
.sp
می‌توان از \fBssh\-tpm\-agent\fP برای ارائه کلیدهای میزبان (host keys) یک سرور ssh نیز استفاده کرد.
دستور \fBssh\-tpm\-hostkeys\fP دارای گزینه‌های مفیدی است که به نصب پیکربندی‌ها
و سرویس‌های systemd روی سیستم کمک می‌کنند. این کار یک سوکت سیستمی برای ssh\-tpm\-agent
در مسیر \fI/var/tmp/ssh\-tpm\-agent.sock\fP ایجاد می‌کند.
.sp
.if n .RS 4
.nf
.fam C
$ 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
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ 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
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ sudo ssh\-tpm\-hostkeys \-\-install\-sshd\-config
Installed /etc/ssh/sshd_config.d/10\-ssh\-tpm\-agent.conf
Restart sshd: systemd restart sshd
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ systemctl enable \-\-now ssh\-tpm\-agent.socket
$ systemd restart sshd
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ sudo ssh\-tpm\-hostkeys
ecdsa\-sha2\-nistp256 AAAAE2V[...]YNwqWY0= root@localhost
ssh\-rsa AAAAB3NzaC1ycA[...]N1Jg3fLQKSe7f root@localhost
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
$ ssh\-keyscan \-t ecdsa localhost
# localhost:22 SSH\-2.0\-OpenSSH_9.4
localhost ecdsa\-sha2\-nistp256 AAAAE2V[...]YNwqWY0=
.fam
.fi
.if n .RE
.sp
به‌عنوان راهکار جایگزین، می‌توان از گزینه‌های نصب توکار صرف‌نظر کرد و تنها یک
پیکربندی الحاقی (drop\-in) برای sshd در مسیر /etc/ssh/sshd_config.d با محتوای زیر قرار داد.
.sp
.if n .RS 4
.nf
.fam C
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
.fam
.fi
.if n .RE.SS "کلیدهای سلسله‌مراتب (Hierarchy keys)"
.sp
تراشه‌های TPM قادرند با استفاده از سلسله‌مراتب‌های سطح‌بالا، کلیدهای ایستا (static keys) ایجاد کنند.
این قابلیت به کاربر امکان می‌دهد کلیدهایی بسازد که برای طول عمر دستگاه،
برای مالک فعلی دستگاه، یا برای نشست (session) جاری دستگاه معتبر باشند.
این کلیدها نیز، مانند سایر کلیدهای ایجادشده توسط \fBssh\-tpm\-keygen\fP، هرگز
از TPM خارج نمی‌شوند و همواره می‌توان آن‌ها را دوباره ایجاد کرد.
.sp
این کلیدها می‌توانند از پیش در \fBssh\-tpm\-agent\fP بارگذاری شوند.
.sp
.if n .RS 4
.nf
.fam C
$ 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)
.fam
.fi
.if n .RE
.sp
برای استفاده به‌همراه \f(CRsshd\fP، بخش عمومی (public) این کلیدها را می‌توان با ترکیب
\fI\-A\fP و \fI\-\-hierarchy\fP ایجاد کرد.
.sp
.if n .RS 4
.nf
.fam C
$ 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
.fam
.fi
.if n .RE
.sp
این فایل‌ها می‌توانند طبق روال معمول همراه با \fIHostKey\fP در \fIssh_config\fP استفاده شوند.
.sp
سلسله‌مراتب‌های مختلف کلید، ویژگی‌ها و طول عمر متفاوتی دارند.
.sp
سلسله‌مراتب \fIendorsement\fP کلیدهای ساخته‌شده برای طول عمر دستگاه را ذخیره می‌کند. این
سلسله‌مراتب نباید در طول عمر دستگاه تغییر کند.
.sp
سلسله‌مراتب \fIowner\fP کلیدهای ساخته‌شده برای مالک دستگاه را نگهداری می‌کند. این کلیدها
هنگام اجرای دستور \fBtpm2_clear\fP(1) روی پلتفرم بازنشانی (rotate) می‌شوند؛ کاری که
باید هنگام انتقال دستگاه به مالک جدید انجام گیرد.
.sp
سلسله‌مراتب \fInull\fP کلیدهای ساخته‌شده برای نشست جاری را ذخیره می‌کند. منظور از نشست
معمولاً یک چرخه راه‌اندازی و خاموشی (power cycle) دستگاه است.
.sp
\fBنکته:\fP این ویژگی \fIآزمایشی\fP است. \fBssh\-tpm\-agent\fP اشیاء TPM را در حین اجرا
در وضعیت بارگذاری‌شده نگه می‌دارد. اگر تلاش کنید هم‌زمان از کلیدهای سلسله‌مراتب به همراه
کلیدهای معمول ایجادشده توسط \fBssh\-tpm\-keygen\fP استفاده کنید، حافظه برخی دستگاه‌های TPM
ممکن است به پایان برسد.
.SH "محیط (ENVIRONMENT)"
.sp
\fBSSH_TPM_AUTH_SOCK\fP
.RS 4
مسیر یک سوکت دامنه یونیکس (unix\-domain socket) را جهت ارتباط با کارگزار (agent) مشخص می‌کند.
.sp
پیش‌فرض آن \fI/var/tmp/ssh\-tpm\-agent.sock\fP است.
.RE
.sp
\fBSSH_ASKPASS\fP
.RS 4
اگر \fBssh\-tpm\-agent\fP و سایر برنامه‌ها نیاز به خواندن گذرواژه داشته باشند، در صورت امکان
به‌طور پیش‌فرض از ترمینال استفاده می‌کنند. چنانچه ترمینالی در دسترس نباشد، از اجرای برنامه‌ای
که \fBSSH_ASKPASS\fP به آن اشاره دارد استفاده خواهند کرد.
.sp
برای اطلاعات بیشتر، \fBssh\fP(1) را ذیل بخش \fBENVIRONMENT\fP ببینید.
.RE
.sp
\fBSSH_ASKPASS_REQUIRE\fP
.RS 4
امکان کنترل نحوه استفاده از برنامه askpass را فراهم می‌کند.
مقادیر معتبر عبارتند از:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBnever\fP اطمینان می‌دهد که \fBssh\fP هرگز برای استفاده از برنامه askpass تلاش نخواهد کرد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBprefer\fP استفاده از برنامه askpass را ترجیح می‌دهد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBforce\fP اطمینان می‌دهد که تمامی ورودی‌های عبارت‌عبور (passphrase) از برنامه askpass استفاده خواهند کرد.
.RE
.sp
برای اطلاعات بیشتر، \fBssh\fP(1) را ذیل بخش \fBENVIRONMENT\fP ببینید.
.RE
.sp
\fBSSH_TPM_AGENT_SWTPM\fP
.RS 4
مشخص می‌کند که آیا \fBssh\-tpm\-agent\fP باید از پشتیبان (backend) swtpm استفاده کند یا خیر. هر مقدار غیرخالی به عنوان درست (true) در نظر گرفته می‌شود.
.RE
.sp
\fBSSH_TPM_LANDLOCK\fP
.RS 4
در صورت تنظیم، \fBssh\-tpm\-agent\fP و سایر برنامه‌ها در صورت امکان محدودسازی امنیتی (sandbox) مبتنی بر landlock را اعمال می‌کنند.
.sp
به‌طور پیش‌فرض غیرفعال است.
.sp
برای اطلاعات بیشتر، \fBlandlock\fP(7) را ببینید.
.RE.SH "فایل‌ها (FILES)"
.sp
\fI~/ssh/id_rsa.tpm\fP, \fI~/ssh/id_ecdsa.tpm\fP
.RS 4
شامل کلیدهای خصوصی ssh مورد استفاده توسط \fBssh\-tpm\-agent\fP است. این‌ها فایل‌های کلید TPM 2.0 TSS هستند و به‌صورت امن توسط TPM بسته‌بندی (wrap) شده‌اند. می‌توان آن‌ها را به‌صورت عمومی به اشتراک گذاشت چرا که تنها توسط همان TPM که روی آن ایجاد شده‌اند قابل استفاده هستند؛ با این حال احتمالاً بهتر است این کار را انجام ندهید.
.RE
.sp
\fI~/ssh/id_rsa.pub\fP, \fI~/ssh/id_ecdsa.pub\fP
.RS 4
شامل کلیدهای عمومی ssh است. این کلیدها را می‌توان به‌صورت عمومی به اشتراک گذاشت و قالب آن‌ها مشابه کلیدهای ایجادشده توسط \fBssh\-keygen\fP(1) است.
.RE
.sp
\fI/run/user/$UID/ssh\-tpm\-agent.sock\fP
.RS 4
مسیر پیش‌فرض سوکت UNIX کاربر برای \fBssh\-tpm\-agent\fP. مورد استفاده توسط کاربران به‌صورت مجزا.
.RE
.sp
\fI/var/tmp/ssh\-tpm\-agent.sock\fP
.RS 4
مسیر پیش‌فرض سوکت UNIX در سطح سیستم برای \fBssh\-tpm\-agent\fP. مورد استفاده برای کلیدهای میزبان (host keys) و سیستم.
.RE
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBssh\-agent\fP(1), \fBssh\fP(1), \fBssh\-tpm\-keygen\fP(1), \fBssh\-keygen\fP(1)
.SH "نکات، استانداردها و سایر موارد (NOTES, STANDARDS AND OTHER)"
.sp
.URL "https://www.hansenpartnership.com/draft\-bottomley\-tpm2\-keys.html" "مشخصات ASN.1 برای فایل‌های کلید TPM 2.0" ""
.sp
.URL "https://linderud.dev/blog/store\-ssh\-keys\-inside\-the\-tpm\-ssh\-tpm\-agent" "ذخیرهٔ کلیدهای ssh درون TPM: ssh\-tpm\-agent" ""