نام (NAME)

tpm2_evictcontrol(1) - دائمی کردن یک شیء گذرا یا خارج کردن (تخلیه) یک شیء دائمی.

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

tpm2_evictcontrol [OPTIONS] [ARGUMENT]

توضیحات (DESCRIPTION)

دستور tpm2_evictcontrol(1) - امکان پایدار (دائمی) کردن یک شیء گذرا یا خارج کردن (تخلیه) یک شیء پایدار از TPM را فراهم می‌کند. آرگومان HANDLE نمایه‌ای را که هندل به آن اختصاص می‌یابد، کنترل می‌کند. اگر شیء مشخص‌شده از طریق -c گذرا باشد و یک HANDLE دائمی مشخص شده باشد، شیء در HANDLE پایدار خواهد شد. اگر HANDLE یک - باشد، شیء در اولین موقعیت هندل دائمی موجود ذخیره و پایدار خواهد شد. اگر شیء مشخص‌شده از طریق -c یک هندل دائمی باشد، شیء از موقعیت هندل دائمی خود خارج (تخلیه) خواهد شد.

گزینه‌ها (OPTIONS)

•: -C, --hierarchy=OBJECT:

سلسله‌مراتب مجازشماری که برای تأیید و مجاز کردن دستورات استفاده می‌شود. به طور پیش‌فرض بر روی سلسله‌مراتب “owner” تنظیم است. گزینه‌های پشتیبانی‌شده عبارتند از:

•: o برای TPM_RH_OWNER
•: p برای TPM_RH_PLATFORM
•: <num> که در آن می‌توان از یک عدد خام استفاده کرد.

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

مشخص‌کننده شیء زمینه (context object) برای یک شیء گذرا یا دائمی. اگر OBJECT یک شیء گذرا باشد، دائمی خواهد شد؛ خواه در هندل مشخص‌شده توسط آرگومان یا در اولین هندل دائمی خالی و در دسترس. اگر OBJECT مربوط به یک شیء دائمی باشد، شیء از حافظه غیرفرار (non-volatile) خارج (تخلیه) خواهد شد.

•: -P, --auth=AUTH:

مقدار احراز اصالت برای سلسله‌مراتب مشخص‌شده با -C.

•: -o, --output=FILE:

به‌صورت اختیاری یک شیء سریالی‌شده که نشان‌دهنده هندل دائمی است را در خروجی می‌نویسد. در صورت عدم دستکاری، این فایل‌ها برای استفاده امن‌تر از هندل‌های دائمی خام هستند. در مورد یک هندل دائمی خام، باید بررسی و تأیید شود که شیء اشاره‌شده همان شیء مورد انتظار است.

•: --cphash=FILE

مسیر فایل برای ذخیره هش پارامترهای دستور. این مقدار معمولاً با عنوان cpHash شناخته می‌شود. نکته: هنگام انتخاب این گزینه، ابزار عملاً دستور را اجرا نمی‌کند و صرفاً مقدار cpHash را برمی‌گرداند.

•: ARGUMENT آرگومان خط فرمان، هندل دائمی را برای ذخیره شیء گذرا مشخص می‌کند.

خروجی (OUTPUT)

این ابزار یک دیکشنری سازگار با YAML با فیلدهای زیر در خروجی تولید می‌کند: persistent-handle: action: evicted|persisted

که در آن persistent-handle هندلی است که عملیات روی آن انجام گرفته است. که در آن action می‌تواند یکی از دو مقدار evicted یا persisted باشد. اگر شیء evicted شود، شیء دیگر در آدرس persistent-handle درون TPM مستقر نخواهد بود. اگر شیء persisted شود، شیء در آدرس persistent-handle درون TPM مستقر خواهد بود.

مراجع (REFERENCES)

قالب شیء زمینه (CONTEXT OBJECT FORMAT)

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

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

•: owner: سلسله‌مراتب مالک (owner)
•: platform: سلسله‌مراتب پلتفرم (platform)
•: endorsement: سلسله‌مراتب تأیید (endorsement)
•: lockout: شیء دائمی کنترل قفل (lockout)

•: اگر آرگومان بتواند به صورت عدد بارگیری شود، به عنوان یک هندل در نظر گرفته شده (مانند 0x81010013) و مستقیماً استفاده می‌شود.

قالب‌بندی احراز هویت (AUTHORIZATION FORMATTING)

مجوز برای استفاده از یک شیء در TPM 2.0 می‌تواند به ۳ شکل مختلف باشد: ۱. گذرواژه (Password) ۲. HMAC ۳. نشست‌ها (Sessions)

نکته: “مجوزها در صورت مشخص نشدن به طور پیش‌فرض بر روی گذرواژه خالی تنظیم می‌شوند”.

برای احراز اصالت با مقادیر auth، دستورات ابزار به طور ضمنی یک نشست HMAC ایجاد می‌کنند. بنابراین گذرواژه‌ها به صورت رمزگذاری‌نشده ارسال نمی‌شوند. این امر در مورد گذرواژه‌های تعریف‌شده برای اشیاء صدق نمی‌کند. در این حالت، باید از یک نشست HMAC استفاده شود (به tpm2_startauthsession(1) مراجعه کنید).

گذرواژه‌ها (PASSWORDS)

گذرواژه‌ها با استفاده از شناسه‌های پیشوندی به اشکال زیر تفسیر می‌شوند.

نکته: به طور پیش‌فرض فرض می‌شود گذرواژه‌های فاقد پیشوند در قالب رشته هستند.

رشته (STRING)

یک گذرواژه رشته‌ای که با پیشوند “str:” یا عدم وجود آن (رشته خام بدون پیشوند) مشخص می‌شود، پردازش تفسیری نشده و مستقیماً برای احراز هویت استفاده می‌شود.

مثال‌ها (EXAMPLES)

foobar
str:foobar

رشته هگز (HEX-STRING)

یک گذرواژه رشته هگز که با پیشوند “hex:” مشخص می‌شود، از حالت شانزده‌شانزدهی (هگز) به قالب یک آرایه بایتی تبدیل می‌شود؛ بنابراین استفاده از گذرواژه‌هایی با نویسه‌های غیرقابل‌چاپ یا ناسازگار با ترمینال را ممکن می‌سازد.

مثال (EXAMPLE)

hex:1122334455667788

فایل (FILE)

یک گذرواژه مبتنی بر فایل که با پیشوند “file:” مشخص می‌شود، باید مسیر فایلی حاوی گذرواژه برای خوانده شدن توسط ابزار باشد، یا “-” برای استفاده از ورودی استاندارد (stdin). ذخیره گذرواژه‌ها در فایل از نشت اطلاعات جلوگیری می‌کند؛ زیرا گذرواژه‌هایی که به عنوان گزینه‌های دستور ارسال می‌شوند را می‌توان از طریق فهرست فرایندها یا تاریخچه پوسته خواند.

مثال‌ها (EXAMPLES)

# برای استفاده از stdin و درخواست تعاملی
file:-
# برای استفاده از یک فایل از یک مسیر
file:path/to/password/file
# برای ارسال گذرواژه از طریق stdin با استفاده از echo:
echo foobar | tpm2_tool -p file:-
# برای استفاده از bash here-string از طریق stdin:
tpm2_tool -p file:- <<< foobar

نشست‌ها (SESSIONS)

هنگام استفاده از یک نشست خط‌مشی (policy session) برای مجاز کردن استفاده از یک شیء، آرگومان گزینه را با کلمه کلیدی session آغاز کنید. سپس مسیری به فایل نشستی که با tpm2_startauthsession(1) ساخته شده است مشخص نمایید. به صورت اختیاری، اگر نشست مستلزم ارسال یک مقدار auth همراه با هندل نشست باشد (مانند گذرواژه خط‌مشی)، یک علامت + و یک رشته را مطابق آنچه در بخش گذرواژه‌ها (PASSWORDS) توضیح داده شد اضافه کنید.

مثال‌ها (EXAMPLES)

برای استفاده از یک فایل زمینه نشست با نام session.ctx:

session:session.ctx

برای استفاده از فایل زمینه نشست session.ctx و ارسال مقدار auth با عنوان mypassword:

session:session.ctx+mypassword

برای استفاده از فایل زمینه نشست session.ctx و ارسال مقدار auth هگزادسیمال با مقدار 0x11223344:

session:session.ctx+hex:11223344

مجوزهای PCR (PCR AUTHORIZATIONS)

می‌توان با استفاده از پیشوند “pcr:” و زبان کوچک PCR، یک خط‌مشی PCR را برآورده کرد. زبان کوچک PCR به شرح زیر است: <pcr-spec>=<raw-pcr-file>

مشخصات PCR در بخش “مشخص‌کننده‌های بانک PCR” مستند شده است.

آرگومان raw-pcr-file یک آرگومان اختیاری است که حاوی خروجی محتویات خام PCR مطابق با مقدار بازگردانده‌شده از tpm2_pcrread(1) می‌باشد.

مشخص‌کننده‌های بانک PCR

مثال‌ها (EXAMPLES)

برای برآورده ساختن یک خط‌مشی PCR از نوع sha256 روی بانک‌های ۰، ۱، ۲ و ۳ از این مشخص‌کننده استفاده کنید:

pcr:sha256:0,1,2,3

مشخص کردن AUTH.

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

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

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

استفاده موفقیت‌آمیز از قابلیت صفحات راهنما نیازمند آن است که صفحات نصب شده باشند یا در MANPATH قرار داشته باشند؛ برای جزئیات بیشتر به man(1) رجوع کنید.

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

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

رابط TCTI یا “Transmission Interface” سازوکار ارتباطی با 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 برای استفاده توسط این TCTI می‌تواند مشخص شود. مقدار پیش‌فرض /dev/tpm0 است.

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

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

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

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

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

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 مترادف هستند.

مثال‌ها (EXAMPLES)

دائمی کردن یک هندل گذرا در نشانی 0x81010002 (To make a transient handle persistent at address 0x81010002)

tpm2_changeauth -c o ownerauth
tpm2_createprimary -c primary.ctx -P ownerauth
tpm2_evictcontrol -C o -c primary.ctx 0x81010002 -P ownerauth

بیرون راندن یک هندل دائمی (To evict a persistent handle)

tpm2_evictcontrol -C o -c 0x81010002 -P ownerauth

دائمی کردن یک هندل گذرا و خروجی دادن یک هندل دائمی سریالی‌شده (To make a transient handle persistent and output a serialized persistent handle)

tpm2_evictcontrol -C o -c primary.ctx -o primary.handle -P ownerauth

کدهای بازگشتی (RETURNS)

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

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

اشکالات (BUGS)

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

راهنما (HELP)

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

مجوز (LICENSE)

این اثر تحت مجوز بین‌المللی کریتیو کامنز ارجاع ۴.۰ (CC BY 4.0)منتشر شده است. .