نام (NAME)

tpm2_tr_encode - کدگذاری یک دستگیره ماندگار و TPM2B_NAME به صورت یک ESYS_TR سریال‌شده در خروجی

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

tpm2_tr_encode [OPTIONS]

توضیحات (DESCRIPTION)

دستور tpm2_tr_encode(1) یک دستگیره ماندگار TPM2 را به همراه یک TPM2B_PUBLIC مقداردهی‌شده، به صورت یک ESYS_TR سریال‌شده کدگذاری می‌کند. این قابلیت برای انتقال کلید عمومی و دستگیره از محیطی که در آن TPM در دسترس نیست به محیط دیگری که TPM دارد و استفاده از آن از طریق ESAPI API یا tpm2-tools(1) مفید است.

گزینه‌ها (OPTIONS)

•: -c, --object-context=OBJECT:

دستگیره ماندگار (Persistent handle).

•: -f, --format:

انتخاب قالب برای فایل خروجی کلید عمومی. مقدار “tss” (پیش‌فرض) یک داده باینری (binary blob) مطابق با مشخصات TPM 2.0 در خروجی تولید می‌کند. مقدار “pem” یک کلید عمومی کدگذاری‌شده PEM سازگار با OpenSSL تولید خواهد کرد. مقدار “der” یک کلید عمومی کدگذاری‌شده DER سازگار با OpenSSL تولید خواهد کرد. مقدار “tpmt” یک داده باینری از ساختار TPMT_PUBLIC که در مشخصات TPM 2.0 به آن ارجاع داده شده است تولید می‌کند.

قالب کلید عمومی.

•: -o, --output=FILE:

مسیر فایل خروجی برای ذخیرهٔ ESYS_TR سریال‌شده.

ارجاعات (References)

قالب شیء زمینه (Context Object Format)

نوع یک شیء زمینه، چه یک دستگیره باشد و چه نام فایل، به‌ترتیب بر اساس منطق زیر تعیین می‌شود:

•: اگر آرگومان یک مسیر فایل باشد، فایل به عنوان یک شیء گذرای (transient) بازیابی‌شدهٔ TPM بارگذاری می‌شود.
•: اگر آرگومان با پیشوند یکی از موارد زیر مطابقت داشته باشد:

•: owner: سلسله‌مراتب مالک (owner hierarchy)
•: platform: سلسله‌مراتب پلتفرم (platform hierarchy)
•: endorsement: سلسله‌مراتب تصدیق (endorsement hierarchy)
•: lockout: شیء ماندگار کنترل قفل (lockout control persistent object)

•: اگر آرگومان بتواند به عنوان یک عدد بارگذاری شود، به عنوان یک دستگیره در نظر گرفته خواهد شد؛ برای نمونه 0x81010013 و مستقیماً استفاده می‌شود._OBJECT_.

گزینه‌های عمومی (COMMON OPTIONS)

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

•: -h, --help=[man|no-man]: نمایش صفحهٔ راهنمای ابزار (manpage). به‌طور پیش‌فرض، تلاش می‌کند صفحه‌بند راهنما (manpager) را برای این ابزار فراخوانی کند، اما در صورت عدم موفقیت، خلاصهٔ کوتاهی از ابزار را نمایش می‌دهد. این رفتار مشابه زمانی است که آرگومان گزینهٔ “man” مشخص شود؛ با این حال اگر صراحتاً “man” درخواست شود، ابزار خطاهای man را در stderr ارائه می‌دهد. اگر گزینهٔ “no-man” مشخص شود، یا فراخوانی manpager شکست بخورد، گزینه‌های کوتاه در stdout چاپ خواهند شد.

برای استفاده موفق از ویژگی صفحات راهنما، نیاز است که صفحات راهنما نصب شده باشند یا در MANPATH قرار داشته باشند؛ برای جزئیات بیشتر man(1) را ببینید.

•: -v, --version: نمایش اطلاعات نسخهٔ این ابزار، TCTIهای پشتیبانی‌شده و خروج.
•: -V, --verbose: افزایش اطلاعاتی که ابزار هنگام اجرا در کنسول چاپ می‌کند. هنگام استفاده از این گزینه، نام فایل و شماره خط چاپ می‌شوند.
•: -Q, --quiet: بی‌صدا کردن خروجی عادی ابزار در stdout.
•: -Z, --enable-errata: فعال‌سازی اعمال رفع نقص‌های خطانامه (errata fixups). زمانی مفید است که لازم باشد یک اصلاحیه به دستورهای ارسالی به TPM اعمال شود. تعریف متغیر محیطی TPM2TOOLS_ENABLE_ERRATA معادل این گزینه است.
•: -z, --pwd-session: استفاده از نشست رمزعبور (password session) به‌جای نشست HMAC برای احراز هویت. یک گذرواژهٔ متن‌آشکار برای مجازشماری عملیات به TPM ارسال می‌شود. این گزینه می‌تواند برای جلوگیری از مشکلاتی که هنگام استفاده از نشست‌های بدون نمک (unsalted) در حالت OpenSSL FIPS رخ می‌دهد استفاده شود. اگر از مقادیر auth استفاده می‌شود، باید از یک نشست نمک‌دار برای احراز هویت استفاده شود.
•: -R, --autoflush: فعال‌سازی پاکسازی خودکار (autoflush) برای اشیاء گذرا (transient objects) ایجادشده توسط دستور. اگر یک شیء والد از یک فایل زمینه بارگذاری شود، شیء والد گذرا نیز پاکسازی خواهد شد. همچنین اگر متغیر محیطی TPM2TOOLS_AUTOFLUSH بر روی yes یا true تنظیم شده باشد، می‌توان پاکسازی خودکار را فعال کرد. اطلاعاتی که ممکن است بسیاری از کاربران انتظار داشته باشند.

پیکربندی TCTI (TCTI Configuration)

‏TCTI یا “رابط انتقال” سازوکار ارتباط با TPM است. ‏TCTIها می‌توانند برای ارتباط با TPMها در رسانه‌های مختلف تغییر داده شوند.

برای کنترل TCTI، ابزارها به موارد زیر ترتیب اثر می‌دهند:

1.: گزینهٔ خط فرمان -T یا --tcti
2.: متغیر محیطی: TPM2TOOLS_TCTI.

نکته: گزینهٔ خط فرمان همیشه متغیر محیطی را بازنویسی می‌کند (اولویت بالاتری دارد).

‏TCTIهای شناخته‌شده کنونی عبارتند از:

•: ‏tabrmd - مدیر منبع، با نام tabrmd. توجه داشته باشید که tabrmd و abrmd به عنوان نام tcti مترادف هستند.
•: ‏mssim - معمولاً برای ارتباط با شبیه‌ساز نرم‌افزاری TPM استفاده می‌شود.
•: ‏device - هنگام ارتباط مستقیم با یک فایل دستگاه TPM استفاده می‌شود.
•: ‏none - هیچ اتصالی با TPM برقرار نمی‌کند. برخی از ابزارها گزینه‌های خارج از TPM (off-tpm) را مجاز می‌دانند و بنابراین از عدم استفاده از TCTI پشتیبانی می‌کنند. ابزارهایی که از آن پشتیبانی نمی‌کنند، در صورت تلاش برای استفاده بدون اتصال TCTI با خطا مواجه می‌شوند. از هیچ گزینه‌ای پشتیبانی نمی‌کند و باید دقیقاً به صورت متن “none” ارائه شود.

آرگومان‌های گزینهٔ خط فرمان یا متغیر محیطی به فرم زیر هستند:

<tcti-name>:<tcti-option-config>

مشخص کردن یک رشتهٔ خالی برای هر کدام از <tcti-name> یا <tcti-option-config> باعث می‌شود به ترتیب برای آن بخش از مقدار پیش‌فرض استفاده شود.

پیش‌فرض‌های TCTI (TCTI Defaults)

هنگامی که یک TCTI مشخص نشده باشد، TCTI پیش‌فرض با استفاده از معناشناسی dlopen(3) جستجو می‌شود. ابزارها به دنبال TCTIهای tabrmd، device و mssim به همان ترتیب خواهند گشت و از نخستین موردی که یافت شود استفاده می‌کنند. شما می‌توانید با استفاده از گزینهٔ -v برای چاپ اطلاعات نسخه، بررسی کنید که کدام TCTI به عنوان پیش‌فرض انتخاب خواهد شد. جفت کلید-مقدار “default-tcti” مشخص می‌کند کدام‌یک از TCTIهای یادشده پیش‌فرض است.

TCTIهای سفارشی (Custom TCTIs)

هر TCTI که رابط پویای TCTI را پیاده‌سازی کرده باشد می‌تواند بارگذاری شود. ابزارها در داخل از dlopen(3) استفاده می‌کنند، و از مقدار خام tcti-name برای جستجو استفاده می‌شود. بنابراین، این مقدار می‌تواند یک مسیر به کتابخانه مشترک یا نام یک کتابخانه باشد آن‌گونه که توسط معناشناسی dlopen(3) درک می‌شود.

گزینه‌های TCTI (TCTI OPTIONS)

این مجموعه از گزینه‌ها برای پیکربندی ماژول‌های مختلف و شناخته‌شدهٔ TCTI موجود استفاده می‌شوند:

•: device: برای TCTI نوع device، فایل دستگاه نویسه‌ای TPM برای استفاده توسط device TCTI می‌تواند مشخص شود. پیش‌فرض /dev/tpm0 است.

مثال: -T device:/dev/tpm0 یا export TPM2TOOLS_TCTI=“device:/dev/tpm0”

•: mssim: برای TCTI نوع mssim، نام دامنه یا آدرس IP و شماره درگاه (port) مورد استفاده توسط شبیه‌ساز می‌تواند مشخص شود. مقادیر پیش‌فرض 127.0.0.1 و 2321 هستند.

مثال: -T mssim:host=localhost,port=2321 یا export TPM2TOOLS_TCTI=“mssim:host=localhost,port=2321”

•: abrmd: برای TCTI نوع abrmd، قالب رشتهٔ پیکربندی مجموعه‌ای از جفت‌های کلید-مقدار ساده است که با نویسهٔ “,” از هم جدا شده‌اند. هر رشتهٔ کلید و مقدار با نویسهٔ “=” جدا می‌شوند.

•: ‏TCTI نوع abrmd از دو کلید پشتیبانی می‌کند:

1.: `bus_name' : نام سرویس tabrmd روی گذرگاه (یک رشته).
2.: `bus_type' : نوع نمونهٔ dbus (یک رشته) که به `session' و `system' محدود است.

مشخص کردن نام tcti برابر با tabrmd و یک رشتهٔ پیکربندی به صورت bus_name=com.example.FooBar:

\--tcti=tabrmd:bus_name=com.example.FooBar

مشخص کردن tcti پیش‌فرض (abrmd) و یک رشتهٔ پیکربندی به صورت bus_type=session:

\--tcti:bus_type=session

نکته: abrmd و tabrmd مترادف هستند. ماژول‌های مختلف و شناخته‌شدهٔ TCTI.

مثال‌ها (EXAMPLES)

سریال‌سازی یک کلید عمومی و دستگیره به صورت یک ESYS_TR

tpm2_createprimary -c primary.ctx
tpm2_evictcontrol -c primary.ctx -o primary.tr 0x81000002
tpm2_readpublic -c primary.tr -o primary.pub
tpm2_tr_encode -c 0x81000002 -u primary.pub -o primary2.tr

وضعیت خروج (EXIT STATUS)

ابزارها می‌توانند هر یک از کدهای خروج زیر را بازگردانند:

•: 0 - موفقیت.
•: 1 - خطای عمومی و نامشخص.
•: 2 - خطای پردازش گزینه‌ها.
•: 3 - خطای احراز هویت.
•: 4 - خطای مربوط به TCTI.
•: 5 - طرح‌واره پشتیبانی‌نشده (Non supported scheme). مربوط به tpm2_testparams.

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

مسائل گیت‌هاب (Github Issues)

راهنما (HELP)

به فهرست پستی (Mailing List)مراجعه کنید.

کپی‌رایت و تکثیر (COPYRIGHT)

این اثر تحت مجوز Creative Commons Attribution 4.0 International License (CC BY 4.0) منتشر شده است.