نام (NAME)

swtpm_setup - ابزار راهاندازی و پیکربندی ماژول پلتفرم مورد اعتماد مبتنی بر نرمافزار (TPM)

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

swtpm_setup [OPTIONS]

توضیحات (DESCRIPTION)

دستور swtpm_setup ابزاری است که وضعیت اولیه را برای یک TPM مبتنی بر libtpms آماده‌سازی می‌کند.

گزینهها (OPTIONS)

گزینه‌های زیر پشتیبانی می‌شوند:

--runas <userid>

از این شناسه کاربری (userid) برای اجرای swtpm_setup استفاده کنید. تنها کاربر root می‌تواند از این گزینه استفاده کند.

--config <file>

مسیر فایل پیکربندی شامل ابزاری که برای ایجاد گواهی‌ها استفاده می‌شود؛ همچنین ببینید: swtpm_setup.conf.

اگر این پارامتر ارائه نشود، فایل پیکربندی پیش‌فرض استفاده خواهد شد. ترتیب جستجو برای فایل پیکربندی پیش‌فرض به شرح زیر است: اگر متغیر محیطی XDG_CONFIG_HOME تنظیم شده باشد، در صورت موجود بودن از ${XDG_CONFIG_HOME}/swtpm_setup.conf استفاده می‌شود؛ در غیر این صورت اگر متغیر محیطی HOME تنظیم شده باشد، در صورت در دسترس بودن از ${HOME}/.config/swtpm_setup.conf استفاده خواهد شد. اگر هیچ‌یک از موارد قبلی موجود نباشد، از /etc/swtpm_setup.conf استفاده خواهد شد.

--tpm-state <dir> or --tpmstate <dir>

مسیری که وضعیت TPM در آن نوشته خواهد شد؛ این یک آرگومان اجباری است. پیشوند dir:// را برای استفاده از بک‌اند دایرکتوری، یا پیشوند file:// را برای استفاده از فایل خطی اضافه کنید.

--tpm <path to executable>

مسیر فایل اجرایی TPM؛ این یک آرگومان اختیاری است و به طور پیش‌فرض از فایل اجرایی swtpm یافت‌شده در PATH استفاده می‌شود.

--tpm2

راه‌اندازی را روی یک TPM 2 انجام می‌دهد؛ به طور پیش‌فرض یک TPM 1.2 راه‌اندازی می‌شود.

--createek

ایجاد یک کلید تایید اعتبار (EK).

--allow-signing

یک EK با قابلیت امضا ایجاد می‌کند. این گزینه به --tpm2 نیاز دارد.

این گزینه یک EK غیر استاندارد ایجاد خواهد کرد. هنگام ایجاد مجدد EK، ابزارهای TPM 2 باید از قالب EK (الگوی EK Template) استفاده کنند که در نمایه NV متناظر با EK ایجادشده نوشته شده است (به عنوان مثال، نمایه NV با شناسه 0x01c00004 برای RSA 2048 EK). در غیر این صورت، EK ایجادشده توسط ابزار با کلید واقعی مورد استفاده یا پیمانه (modulus) نمایش داده‌شده در گواهی EK مطابقت نخواهد داشت.

توجه داشته باشید که مشخصات TCG با عنوان «EK Credential Profile For TPM Family 2.0; Level 0» در بخش مربوط به «EK Usage» پیشنهاد می‌کند که «کلید تایید اعتبار می‌تواند به عنوان یک کلید رمزگشایی یا امضا ایجاد شود.» با این حال، برخی از پلتفرم‌ها یک EK را به عنوان کلید امضا یا به عنوان کلید امضا و رمزنگاری نمی‌پذیرند، و بنابراین این گزینه باید با احتیاط بسیار استفاده شود.

--decryption

یک EK ایجاد می‌کند که می‌تواند برای رمزگذاری کلید (key encipherment) استفاده شود. این حالت پیش‌فرض است مگر اینکه --allow-signing داده شود. این گزینه به --tpm2 نیاز دارد.

--ecc

کلیدهای رمزنگاری منحنی بیضوی (ECC) ایجاد می‌کند؛ به طور پیش‌فرض کلیدهای RSA تولید می‌شوند.

--take-ownership

تصاحب مالکیت؛ این گزینه مستلزم --createek است. این گزینه فقط برای TPM 1.2 در دسترس است.

--ownerpass <password>

ارائه گذرواژه دلخواه برای مالک؛ پیش‌فرض ooo است. این گزینه فقط برای TPM 1.2 در دسترس است.

--owner-well-known

استفاده از گذرواژه‌ای متشکل از صفرها (۲۰ بایت صفر) به عنوان گذرواژه مالک. این گزینه فقط برای TPM 1.2 در دسترس است.

--srkpass <password>

ارائه گذرواژه دلخواه برای SRK؛ پیش‌فرض sss است. این گزینه فقط برای TPM 1.2 در دسترس است.

--srk-well-known

استفاده از گذرواژه‌ای متشکل از صفرها (۲۰ بایت صفر) به عنوان گذرواژه SRK. این گزینه فقط برای TPM 1.2 در دسترس است.

--create-ek-cert

ایجاد یک گواهی EK؛ این گزینه مستلزم --createek است.

--create-platform-cert

ایجاد یک گواهی پلتفرم؛ این گزینه مستلزم --create-ek-cert است.

--lock-nvram

قفل کردن دسترسی NVRAM برای تمام مکان‌های NVRAM که در آن‌ها داده نوشته شده است.

--display

در پایان، تا جای ممکن بیشترین اطلاعات را درباره پیکربندی TPM نمایش می‌دهد.

--logfile <logfile>

فایل لاگ برای ثبت رویدادها. به طور پیش‌فرض ثبت رویدادها در stdout و stderr انجام می‌شود.

--keyfile <keyfile>

فایل کلید حاوی یک کلید هگز اسکی (ASCII hex) متشکل از ۳۲ رقم هگزادسیمال همراه با یک 0x اختیاری در ابتدای آن است. این کلیدی است که شبیه‌ساز TPM برای رمزنگاری وضعیت TPM استفاده می‌کند.

--keyfile-fd <file descriptor>

مشابه --keyfile است اما کلید از توصیف‌کننده فایل (file descriptor) خوانده خواهد شد.

--pwdfile <passphrase file>

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

--pwdfile-fd <file descriptor>

مشابه --pwdfile است اما عبارت عبور از توصیف‌کننده فایل خوانده خواهد شد.

--ciper <cipher>

الگوریتم رمزنگاری (cipher) می‌تواند aes-cbc یا aes-128-cbc برای رمزنگاری ۱۲۸ بیتی AES، یا aes-256-cbc برای رمزنگاری ۲۵۶ بیتی AES باشد. بعداً در خط فرمان swtpm نیز باید از همین الگوریتم رمزنگاری استفاده شود.

--overwrite

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

--not-overwrite

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

--vmid <VM ID>

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

--pcr-banks <PCR banks>

فهرست اختیاری جداشده با کاما از بانک‌های PCR جهت فعال‌سازی. ارائه - به کاربر امکان می‌دهد از انتخاب صرف‌نظر کرده و تمام بانک‌های PCR را فعال کند. اگر این گزینه ارائه نشود، فایل پیکربندی swtpm_setup.conf برای مدخل active_pcr_banks بررسی خواهد شد. اگر چنین مدخلی یافت نشود، مجموعه پیش‌فرض بانک‌های PCR فعال خواهد شد. مجموعه پیش‌فرض بانک‌های PCR را می‌توان با استفاده از گزینه --help تعیین کرد.

--swtpm_ioctl <executable>

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

--tcsd-system-ps-file <file>

این گزینه منسوخ شده و هیچ تاثیری ندارد (از نسخه 0.4).

--rsa-keysize <keysize> (since v0.4)

این گزینه امکان تعیین اندازه کلید TPM 2 RSA EK را فراهم می‌کند، مانند 2048 یا 3072. اندازه‌های پشتیبانی‌شده کلید برای یک TPM 2 را می‌توان با استفاده از گزینه --print-capabilities استعلام کرد. اندازه پیش‌فرض هم برای TPM 1.2 و هم برای TPM 2 برابر با ۲۰۴۸ بیت است. اگر max داده شود، بزرگ‌ترین اندازه کلید ممکن استفاده می‌شود.

--reconfigure (since v0.7)

این گزینه امکان پیکربندی مجدد بانک‌های PCR فعال یک TPM 2 را با استفاده از گزینه --pcr-banks فراهم می‌کند.

--profile <json-profile> (since v0.10)

یک TPM 2 را با پروفایل ارائه‌شده پیکربندی می‌کند. پروفایل‌های نمونه به این شکل هستند:

{"Name": "null"}
{"Name": "default-v1"}
{
 "Name": "custom",
 "Algorithms":"rsa,rsa-min-size=1024,tdes-min-size=128,hmac,aes,\
               aes-min-size=128,mgf1,keyedhash,xor,sha256,sha384,\
               sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,ecdh,ecdaa,\
               sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,kdf1-sp800-108,\
               ecc,ecc-min-size=192,ecc-nist,ecc-bn,symcipher,camellia,\
               camellia-min-size=128,cmac,ctr,ofb,cbc,cfb,ecb"
}

پروفایل JSON باید حاوی فیلد name با نام پروفایلی باشد که توسط libtpms پشتیبانی می‌شود. تنها پروفایل custom یا پروفایل‌هایی که نام آن‌ها با custom: شروع می‌شود قابل تغییر هستند و ممکن است شامل فیلدهای Algorithms، Commands یا Attributes با انتخاب‌های کاربر باشند. فیلدهای ناشناخته در پروفایل JSON نادیده گرفته خواهند شد. برای اطلاعات بیشتر صفحه راهنمای swtpm را ببینید.

--profile-name <profile filename| built-in profile name (since v0.10)

یک TPM 2 را با پروفایلی که از یکی از مکان‌های زیر به ترتیب نشان‌داده‌شده بارگیری می‌شود، پیکربندی می‌کند، مگر اینکه با یک پیشوند تعیین شده باشد:

--profile-file <file> (since v0.10)

پیکربندی یک TPM 2 با پروفایلی از یک فایل.

--profile-file-fd <fd> (since v0.10)

پیکربندی یک TPM 2 با پروفایل خوانده‌شده از یک توصیف‌کننده فایل.

--profile-remove-disabled check|fips-host (since v0.10)

هنگامی که این گزینه ارسال شود، swtpm الگوریتم‌هایی را از پروفایل داده‌شده حذف می‌کند که OpenSSL هنگام فعال بودن حالت FIPS در میزبان نمی‌تواند از آن‌ها استفاده کند. اگر پارامتر check داده شود، الگوریتم‌ها پیش از حذف بررسی می‌شوند در حالی که پارامتر fips-host حذف تمام الگوریتم‌های بالقوه غیرفعال را بدون آزمودن آن‌ها اجبار می‌کند.

این گزینه تنها زمانی کار می‌کند که به پروفایل custom ارجاع داده شود، مثلاً با ارسال --profile ´{"Name":"custom:test"}´.

این گزینه پارامتر remove-disable را به عنوان بخشی از گزینه --profile به swtpm منتقل می‌کند. برای اطلاعات بیشتر صفحه راهنمای swtpm را ببینید.

--print-profiles (since v0.10)

چاپ تمام پروفایل‌های یافت‌شده در پوشه‌های پروفایل محلی و توزیع و نمایش پروفایل‌های داخلی. تمام پروفایل‌های ذخیره‌شده در فایل‌ها باید پسوند .json داشته باشند. نام‌ها در JSON نمایش‌داده‌شده نامی را نشان خواهند داد که با آن می‌توان این پروفایل‌ها را با گزینه --profile-name بارگیری کرد، یعنی نام فایل آن‌ها بدون پسوند .json نمایش داده می‌شود. بنابراین، پروفایلی با نام فایل myprofile.json مقدار Name را برابر با myprofile نشان خواهد داد. ایجادکننده پروفایل ممکن است بخواهد Name را در JSON پروفایل روی custom:myprofile تنظیم کند.

--print-capabilities (since v0.2)

چاپ قابلیت‌هایی که پس از نسخه 0.1 به swtpm_setup افزوده شده‌اند. خروجی ممکن است شامل موارد زیر باشد:

{
  "type": "swtpm_setup",
  "features": [
    "tpm-1.2",
    "tpm-2.0",
    "cmdarg-keyfile-fd",
    "cmdarg-pwdfile-fd",
    "tpm12-not-need-root",
    "cmdarg-write-ek-cert-files",
    "cmdarg-create-config-files",
    "cmdarg-reconfigure-pcr-banks",
    "tpm2-rsa-keysize-2048",
    "tpm2-rsa-keysize-3072",
    "cmdarg-profile",
    "cmdarg-profile-remove-disabled"
  ],
  "version": "0.7.0"
}

فیلد version از نسخه 0.7 در دسترس است.

معنای عبارت‌های ویژگی (feature verbs) به شرح زیر است:

--write-ek-cert-files <directory> (since v0.7)

این گزینه باعث می‌شود فایل‌های کلید تایید اعتبار (EK) در پوشه ارائه‌شده نوشته شوند. این فایل‌ها حاوی EKهای با قالب DER هستند که در مکان‌های NVRAM مربوط به TPM 1.2 یا TPM 2 نوشته شده‌اند. فایل‌های EK از الگوی نام‌گذاری ek-<key type>.crt پیروی می‌کنند. نمونه‌هایی از نام فایل‌ها عبارتند از: ek-rsa2048.crt، ek-rsa3072.crt و ek-secp384r1.crt.

کلیدهایی که برای یک TPM 2 نوشته می‌شوند ممکن است با گذشت زمان و تغییر استحکام پیش‌فرض کلیدهای EK تغییر کنند. این بدان معناست که هنگام جستجوی EKها باید به دنبال تمام فایل‌های منطبق با الگوی نام‌گذاری بالا باشید.

--create-config-files [[overwrite][,root][,skip-if-exist]] (since v0.7)

این گزینه به کاربر امکان می‌دهد فایل‌های پیکربندی را برای swtpm_setup و swtpm-localca در پوشه‌های $XDG_CONFIG_HOME یا $HOME/.config ایجاد کند.

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

معنای گزینه‌ها به شرح زیر است:

--help, -h

نمایش صفحه راهنما

مثال‌های کاربردی (EXAMPLE USAGE)

برای شبیه‌سازی ساخت یک TPM، معمولاً دستور زیر اجرا می‌شود:

#> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
    --create-ek-cert --create-platform-cert --lock-nvram

نکته: از نسخه 0.4 راه‌اندازی TPM 1.2 دیگر به امتیازات root نیازی ندارد.

هر کاربری همچنین می‌تواند ساخت یک TPM را با استفاده از ابزار swtpm_localca شبیه‌سازی کند. مثال زیر فرض می‌کند که کاربر متغیر محیطی XDG_CONFIG_HOME را به صورت زیر تنظیم کرده است (برای مثال با استفاده از bash):

export XDG_CONFIG_HOME=~/.config

نکته: متغیر XDG_CONFIG_HOME بخشی از مشخصات راهنمای پایه XDG (XDG Base Directory Specification) است.

فایل‌های پیکربندی زیر باید ایجاد شوند:

~/.config/swtpm_setup.conf:

# Program invoked for creating certificates
create_certs_tool= /usr/share/swtpm/swtpm-localca
create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf
create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options

~/.config/swtpm-localca.conf:

statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca
signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem
issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem
certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial

~/.config/swtpm-localca.options:

--platform-manufacturer Fedora
--platform-version 2.12
--platform-model QEMU

نکته: ابزار swtpm-create-user-config-files می‌تواند برای ایجاد چنین فایل‌هایی (با محتوای متفاوت) استفاده شود:

#> /usr/share/swtpm/swtpm-create-user-config-files
Writing /home/stefanb/.config/swtpm_setup.conf.
Writing /home/stefanb/.config/swtpm-localca.conf.
Writing /home/stefanb/.config/swtpm-localca.options.

دستورات زیر اکنون یک TPM 2 با یک EK و گواهی پلتفرم ایجاد می‌کنند. وضعیت TPM 2 در پوشه ${XDG_CONFIG_HOME}/mytpm1 ذخیره خواهد شد.

#> mkdir -p ${XDG_CONFIG_HOME}/mytpm1
#> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \
    --create-ek-cert --create-platform-cert --lock-nvram

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

swtpm_setup.conf

گزارش باگ‌ها (REPORTING BUGS)

گزارش باگ‌ها به Stefan Berger <stefanb@linux.ibm.com>