نام (NAME)

fsverity - ابزار فضای کاربری برای fs-verity

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

fsverity digest [OPTION...] FILE...

fsverity dump_metadata [OPTION...] TYPE FILE

fsverity enable [OPTION...] FILE

fsverity measure FILE...

fsverity sign [OPTION...] FILE OUT_SIGFILE

توضیحات (DESCRIPTION)

fsverity یک ابزار فضای کاربری برای fs-verity است. fs-verity یکی از قابلیت‌های سیستم‌فایل در هستهٔ لینوکس است که راستی‌آزمایی شفاف و برحسب تقاضای محتوای فایل‌های فقط‌خواندنی را با استفاده از درخت‌های مرکل (Merkle trees) انجام می‌دهد.

fsverity می‌تواند fs-verity را روی فایل‌ها فعال کند، خلاصه‌های (digests) فایل‌های fs-verity را دریافت نماید، و فایل‌ها را برای استفاده با fs-verity امضا کند (در کنار قابلیت‌های دیگر). عملکرد fsverity به زیردستورهای گوناگونی تقسیم شده است.

این صفحهٔ راهنما بر مستندسازی تمام زیردستورها و گزینه‌های fsverity تمرکز دارد. برای مثال‌ها و اطلاعات بیشتر دربارهٔ قابلیت fs-verity در هسته، به مراجع موجود در انتهای این صفحه مراجعه کنید.

گزینه‌ها (OPTIONS)

fsverity همواره گزینه‌های زیر را می‌پذیرد:

--help: نمایش راهنما برای یک زیردستور یا تمام زیردستورها.
--version: نمایش نسخهٔ fsverity-utils.

زیردستورها (SUBCOMMANDS)

fsverity digest [OPTION...] FILE...

محاسبهٔ خلاصهٔ fs-verity برای فایل یا فایل‌های داده‌شده. این دستور عمدتاً برای آماده‌سازی جهت امضای خلاصه به کار می‌رود. در برخی موارد می‌توان به جای آن از fsverity sign استفاده کرد تا خلاصه‌سازی و امضای فایل در یک مرحله انجام شود.

گزینه‌های پذیرفته‌شده توسط fsverity digest:

--block-size=BLOCK_SIZE: اندازهٔ بلوک درخت مرکل (به بایت) برای استفاده. این مقدار باید توانی از ۲ و حداقل دو برابر اندازهٔ مقادیر هش باشد.

توجه داشته باشید که پیاده‌سازی‌های fs-verity در هستهٔ لینوکس محدودیت‌های بیشتری روی اندازهٔ بلوک درخت مرکل اعمال می‌کنند. لینوکس نسخهٔ 6.2 و قبل‌تر نیازمند آن هستند که اندازهٔ بلوک درخت مرکل با هر دو موردِ اندازهٔ صفحهٔ سیستم و اندازهٔ بلوک سیستم‌فایل برابر باشد. این مقادیر اغلب ۴۰۹۶ هستند. لینوکس نسخهٔ 6.3 و بعد از آن انعطاف‌پذیرتر هستند؛ آن‌ها نیازمند آنند که اندازهٔ بلوک درخت مرکل توانی از ۲ باشد که بزرگ‌تر یا مساوی ۱۰۲۴ و کوچک‌تر یا مساوی اندازهٔ صفحهٔ سیستم و اندازهٔ بلوک سیستم‌فایل است. مقدار پیش‌فرض این گزینه ۴۰۹۶ است.

--compact: هنگام چاپ خلاصهٔ فایل، فقط رشتهٔ هگزادسیمالِ خلاصه را چاپ می‌کند؛ نام الگوریتم و نام فایل را چاپ نمی‌کند.
--for-builtin-sig: قالب‌بندی خلاصهٔ فایل به شیوه‌ای که با پشتیبانی هستهٔ لینوکس از راستی‌آزمایی امضای توکار fs-verity سازگار باشد. این به معنی قالب‌بندی آن به صورت یک struct fsverity_formatted_digest است. اگر از امضاهای توکار استفاده می‌کنید اما برای انجام امضا از fsverity sign بهره نمی‌برید، از این گزینه استفاده کنید.
--hash-alg=HASH_ALG: الگوریتم هش مورد استفاده برای ساخت درخت مرکل. گزینه‌های معتبر sha256 و sha512 هستند. پیش‌فرض sha256 است.
--out-merkle-tree=FILE: نوشتن درخت مرکل محاسبه‌شده در فایل داده‌شده. طرح‌بندی درخت مرکل مشابه حالتی خواهد بود که توسط فراخوانی کنترلی FS_IOC_READ_VERITY_METADATA در هستهٔ لینوکس استفاده می‌شود.

به‌طور معمول این گزینه کاربردی ندارد، اما ممکن است در مواردی لازم باشد که فرادادهٔ fs-verity توسط چیزی غیر از پیاده‌سازی‌های بومی هستهٔ لینوکس مصرف شود. برای امضای فایل نیازی به این گزینه نیست.

--out-descriptor=FILE: نوشتن توصیف‌گرِ (descriptor) محاسبه‌شدهٔ fs-verity در فایل داده‌شده.

به‌طور معمول این گزینه کاربردی ندارد، اما ممکن است در مواردی لازم باشد که فرادادهٔ fs-verity توسط چیزی غیر از پیاده‌سازی‌های بومی هستهٔ لینوکس مصرف شود. برای امضای فایل نیازی به این گزینه نیست.

--salt=SALT: نمک (salt) مورد استفاده در درخت مرکل، به صورت یک رشتهٔ هگزادسیمال. نمک مقداری است که به ابتدای هر بلوک هش‌شده اضافه می‌شود؛ می‌توان از آن برای شخصی‌سازی هش برای یک فایل یا دستگاه خاص استفاده کرد. حالت پیش‌فرض بدون نمک است.

fsverity dump_metadata [OPTION...] TYPE FILE

تخلیهٔ (dump) فرادادهٔ fs-verity از فایل داده‌شده. باید قابلیت fs-verity روی فایل فعال باشد و سیستم‌فایل نیز باید از فراخوانی کنترلی FS_IOC_READ_VERITY_METADATA پشتیبانی کند (این قابلیت در لینوکس نسخهٔ 5.12 اضافه شد). این زیردستور معمولاً کاربردی ندارد، اما می‌تواند در مواردی مفید باشد که یک برنامهٔ سرور در فضای کاربری فایلی از نوع verity را به کلاینتی تحویل می‌دهد که راستی‌آزمایی سازگار با fs-verity را پیاده‌سازی کرده است.

مقدار TYPE می‌تواند یکی از مقادیر “merkle_tree”، “descriptor” یا “signature” باشد که نوع فراداده برای تخلیه را مشخص می‌کند. مقدار “signature” به امضای توکار (در صورت وجود) اشاره دارد؛ امضاهای مدیریت‌شده در فضای کاربری لحاظ نخواهند شد.

گزینه‌های پذیرفته‌شده توسط fsverity dump_metadata:

--length=LENGTH: طول مورد نظر بر حسب بایت برای تخلیه از مورد فرادادهٔ مشخص‌شده. تنها در ترکیب با --offset پذیرفته می‌شود.
--offset=offset: آفست بر حسب بایت درون مورد فرادادهٔ مشخص‌شده که تخلیه از آنجا آغاز می‌شود. تنها در ترکیب با --length پذیرفته می‌شود.

fsverity enable [OPTION...] FILE

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

گزینه‌های پذیرفته‌شده توسط fsverity enable:

--block-size=BLOCK_SIZE: مشابه گزینهٔ fsverity digest.
--hash-alg=HASH_ALG: مشابه گزینهٔ fsverity digest.
--salt=SALT: مشابه گزینهٔ fsverity digest.
--signature=SIGFILE: امضای توکار را برای اعمال روی فایل مشخص می‌کند. SIGFILE باید فایلی باشد که حاوی امضا در قالب PKCS#7 DER است، برای مثال آنچه که توسط دستور fsverity sign تولید می‌شود.

توجه داشته باشید که این گزینه تنها در صورتی لازم است که از قابلیت پشتیبانی هستهٔ لینوکس از راستی‌آزمایی امضای توکار fs-verity استفاده شود. اگر قرار است امضاها در فضای کاربری راستی‌آزمایی شوند به این گزینه نیازی نیست، زیرا در آن حالت امضاها باید جداگانه ذخیره گردند.

fsverity measure FILE...

نمایش خلاصهٔ fs-verity برای فایل یا فایل‌های داده‌شده. باید قابلیت fs-verity روی فایل‌ها فعال باشد. خروجی مشابه دستور fsverity digest با پارامترهای مناسب خواهد بود، اما fsverity measure برای هر فایل صرف‌نظر از اندازهٔ آن، در زمانی ثابت اجرا خواهد شد.

دستور fsverity measure هیچ گزینه‌ای نمی‌پذیرد.

fsverity sign [OPTION...] FILE OUT_SIGFILE

امضای فایل داده‌شده برای fs-verity، به گونه‌ای که با پشتیبانی هستهٔ لینوکس از راستی‌آزمایی امضای توکار fs-verity سازگار باشد. امضا در قالب PKCS#7 DER در فایل OUT_SIGFILE نوشته خواهد شد.

کلید خصوصی می‌تواند از طریق فایل کلید یا از طریق توکن PKCS#11 مشخص شود. برای استفاده از فایل کلید، گزینهٔ --key و به صورت اختیاری --cert را مشخص کنید. برای استفاده از توکن PKCS#11، گزینه‌های --pkcs11-engine، --pkcs11-module، --cert و به صورت اختیاری --pkcs11-keyid را ارائه دهید. اگر fsverity-utils با نسخه‌ای از OpenSSL ساخته شده باشد که از توکن‌های PKCS#11 پشتیبانی نمی‌کند، پشتیبانی از توکن PKCS#11 در دسترس نخواهد بود.

دستور fsverity sign فقط در صورتی باید استفاده شود که به سازگاری با امضاهای توکار fs-verity نیاز داشته باشید. این تنها راه ایجاد امضاها با fs-verity نیست. برای اطلاعات بیشتر، فایل README مربوط به fsverity-utils را ببینید.

گزینه‌های پذیرفته‌شده توسط fsverity sign:

--block-size=BLOCK_SIZE: مشابه گزینهٔ fsverity digest.
--cert=CERTFILE: فایل حاوی گواهی (certificate) را در قالب PEM مشخص می‌کند. این گزینه زمانی لازم است که KEYFILE فقط شامل کلید خصوصی بوده و فاقد گواهی باشد، یا اگر از یک توکن PKCS#11 استفاده شود.
--hash-alg=HASH_ALG: مشابه گزینهٔ fsverity digest.
--key=KEYFILE: فایل حاوی کلید خصوصی را در قالب PEM مشخص می‌کند. این گزینه در صورت عدم استفاده از توکن PKCS#11 الزامی است.
--out-descriptor=FILE: مشابه گزینهٔ fsverity digest.
--out-merkle-tree=FILE: مشابه گزینهٔ fsverity digest.
--pkcs11-engine=SOFILE: مسیر فایل موتور PKCS#11 متعلق به OpenSSL را مشخص می‌کند. این مقدار معمولاً مسیری به فایل ‎.so در libp11 خواهد بود. این گزینه هنگام استفاده از توکن PKCS#11 الزامی است.
--pkcs11-keyid=KEYID: شناسهٔ کلید را در قالب یک PKCS#11 URI مشخص می‌کند. در صورت عدم ارائه، کلید پیش‌فرض مرتبط با توکن استفاده می‌شود. این گزینه تنها هنگام استفاده از یک توکن PKCS#11 قابل استفاده است.
--pkcs11-module=SOFILE: مسیر کتابخانهٔ ماژولِ مختص توکن PKCS#11 را مشخص می‌کند. این گزینه هنگام استفاده از توکن PKCS#11 الزامی است.
--salt=SALT: مشابه گزینهٔ fsverity digest.

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

برای دستورات نمونه و اطلاعات بیشتر، فایل README مربوط به fsverity-utils را در https://git.kernel.org/pub/scm/fs/fsverity/fsverity-utils.git/tree/README.md ببینید.

همچنین مستندات هسته را برای fs-verity در https://www.kernel.org/doc/html/latest/filesystems/fsverity.html مشاهده کنید.