.\" SPDX-License-Identifier: MIT .\" .\" Copyright 2021 Google LLC .\" .\" Use of this source code is governed by an MIT-style license that can be .\" found in the LICENSE file or at https://opensource.org/licenses/MIT. .\" .TH "FSVERITY" "1" "November 2025" "fsverity-utils v1.7" "User Commands" .hy . .SH "نام (NAME)" .PP fsverity \- ابزار فضای کاربری برای fs-verity . . .SH "خلاصه دستور (SYNOPSIS)" .PP \f[B]fsverity digest\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R]\&... .PD 0 .P .PD \f[B]fsverity dump_metadata\f[R] [\f[I]OPTION\f[R]\&...] \f[I]TYPE\f[R] \f[I]FILE\f[R] .PD 0 .P .PD \f[B]fsverity enable\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R] .PD 0 .P .PD \f[B]fsverity measure\f[R] \f[I]FILE\f[R]\&... .PD 0 .P .PD \f[B]fsverity sign\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R] \f[I]OUT_SIGFILE\f[R] . . .SH "توضیحات (DESCRIPTION)" .PP \f[B]fsverity\f[R] یک ابزار فضای کاربری برای fs-verity است. fs-verity یکی از قابلیت‌های سیستم‌فایل در هستهٔ لینوکس است که راستی‌آزمایی شفاف و برحسب تقاضای محتوای فایل‌های فقط‌خواندنی را با استفاده از درخت‌های مرکل (Merkle trees) انجام می‌دهد. .PP \f[B]fsverity\f[R] می‌تواند fs-verity را روی فایل‌ها فعال کند، خلاصه‌های (digests) فایل‌های fs-verity را دریافت نماید، و فایل‌ها را برای استفاده با fs-verity امضا کند (در کنار قابلیت‌های دیگر). عملکرد \f[B]fsverity\f[R] به زیردستورهای گوناگونی تقسیم شده است. .PP این صفحهٔ راهنما بر مستندسازی تمام زیردستورها و گزینه‌های \f[B]fsverity\f[R] تمرکز دارد. برای مثال‌ها و اطلاعات بیشتر دربارهٔ قابلیت fs-verity در هسته، به مراجع موجود در انتهای این صفحه مراجعه کنید. . . .SH "گزینه‌ها (OPTIONS)" .PP \f[B]fsverity\f[R] همواره گزینه‌های زیر را می‌پذیرد: .TP \f[B]--help\f[R] نمایش راهنما برای یک زیردستور یا تمام زیردستورها. .TP \f[B]--version\f[R] نمایش نسخهٔ fsverity-utils. . . .SH "زیردستورها (SUBCOMMANDS)" . .SS \f[B]fsverity digest\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R]\&... .PP محاسبهٔ خلاصهٔ fs-verity برای فایل یا فایل‌های داده‌شده. این دستور عمدتاً برای آماده‌سازی جهت امضای خلاصه به کار می‌رود. در برخی موارد می‌توان به جای آن از \f[B]fsverity sign\f[R] استفاده کرد تا خلاصه‌سازی و امضای فایل در یک مرحله انجام شود. .PP گزینه‌های پذیرفته‌شده توسط \f[B]fsverity digest\f[R]: .TP \f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R] اندازهٔ بلوک درخت مرکل (به بایت) برای استفاده. این مقدار باید توانی از ۲ و حداقل دو برابر اندازهٔ مقادیر هش باشد. .RS .PP توجه داشته باشید که پیاده‌سازی‌های fs-verity در هستهٔ لینوکس محدودیت‌های بیشتری روی اندازهٔ بلوک درخت مرکل اعمال می‌کنند. لینوکس نسخهٔ 6.2 و قبل‌تر نیازمند آن هستند که اندازهٔ بلوک درخت مرکل با هر دو موردِ اندازهٔ صفحهٔ سیستم و اندازهٔ بلوک سیستم‌فایل برابر باشد. این مقادیر اغلب ۴۰۹۶ هستند. لینوکس نسخهٔ 6.3 و بعد از آن انعطاف‌پذیرتر هستند؛ آن‌ها نیازمند آنند که اندازهٔ بلوک درخت مرکل توانی از ۲ باشد که بزرگ‌تر یا مساوی ۱۰۲۴ و کوچک‌تر یا مساوی اندازهٔ صفحهٔ سیستم و اندازهٔ بلوک سیستم‌فایل است. مقدار پیش‌فرض این گزینه ۴۰۹۶ است. .RE .TP \f[B]--compact\f[R] هنگام چاپ خلاصهٔ فایل، فقط رشتهٔ هگزادسیمالِ خلاصه را چاپ می‌کند؛ نام الگوریتم و نام فایل را چاپ نمی‌کند. .TP \f[B]--for-builtin-sig\f[R] قالب‌بندی خلاصهٔ فایل به شیوه‌ای که با پشتیبانی هستهٔ لینوکس از راستی‌آزمایی امضای توکار fs-verity سازگار باشد. این به معنی قالب‌بندی آن به صورت یک \f[B]struct fsverity_formatted_digest\f[R] است. اگر از امضاهای توکار استفاده می‌کنید اما برای انجام امضا از \f[B]fsverity sign\f[R] بهره نمی‌برید، از این گزینه استفاده کنید. .TP \f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R] الگوریتم هش مورد استفاده برای ساخت درخت مرکل. گزینه‌های معتبر sha256 و sha512 هستند. پیش‌فرض sha256 است. .TP \f[B]--out-merkle-tree\f[R]=\f[I]FILE\f[R] نوشتن درخت مرکل محاسبه‌شده در فایل داده‌شده. طرح‌بندی درخت مرکل مشابه حالتی خواهد بود که توسط فراخوانی کنترلی \f[B]FS_IOC_READ_VERITY_METADATA\f[R] در هستهٔ لینوکس استفاده می‌شود. .RS .PP به‌طور معمول این گزینه کاربردی ندارد، اما ممکن است در مواردی لازم باشد که فرادادهٔ fs-verity توسط چیزی غیر از پیاده‌سازی‌های بومی هستهٔ لینوکس مصرف شود. برای امضای فایل نیازی به این گزینه نیست. .RE .TP \f[B]--out-descriptor\f[R]=\f[I]FILE\f[R] نوشتن توصیف‌گرِ (descriptor) محاسبه‌شدهٔ fs-verity در فایل داده‌شده. .RS .PP به‌طور معمول این گزینه کاربردی ندارد، اما ممکن است در مواردی لازم باشد که فرادادهٔ fs-verity توسط چیزی غیر از پیاده‌سازی‌های بومی هستهٔ لینوکس مصرف شود. برای امضای فایل نیازی به این گزینه نیست. .RE .TP \f[B]--salt\f[R]=\f[I]SALT\f[R] نمک (salt) مورد استفاده در درخت مرکل، به صورت یک رشتهٔ هگزادسیمال. نمک مقداری است که به ابتدای هر بلوک هش‌شده اضافه می‌شود؛ می‌توان از آن برای شخصی‌سازی هش برای یک فایل یا دستگاه خاص استفاده کرد. حالت پیش‌فرض بدون نمک است. . .SS \f[B]fsverity dump_metadata\f[R] [\f[I]OPTION\f[R]\&...] \f[I]TYPE\f[R] \f[I]FILE\f[R] .PP تخلیهٔ (dump) فرادادهٔ fs-verity از فایل داده‌شده. باید قابلیت fs-verity روی فایل فعال باشد و سیستم‌فایل نیز باید از فراخوانی کنترلی \f[B]FS_IOC_READ_VERITY_METADATA\f[R] پشتیبانی کند (این قابلیت در لینوکس نسخهٔ 5.12 اضافه شد). این زیردستور معمولاً کاربردی ندارد، اما می‌تواند در مواردی مفید باشد که یک برنامهٔ سرور در فضای کاربری فایلی از نوع verity را به کلاینتی تحویل می‌دهد که راستی‌آزمایی سازگار با fs-verity را پیاده‌سازی کرده است. .PP مقدار \f[I]TYPE\f[R] می‌تواند یکی از مقادیر \[lq]merkle_tree\[rq]، \[lq]descriptor\[rq] یا \[lq]signature\[rq] باشد که نوع فراداده برای تخلیه را مشخص می‌کند. مقدار \[lq]signature\[rq] به امضای توکار (در صورت وجود) اشاره دارد؛ امضاهای مدیریت‌شده در فضای کاربری لحاظ نخواهند شد. .PP گزینه‌های پذیرفته‌شده توسط \f[B]fsverity dump_metadata\f[R]: .TP \f[B]--length\f[R]=\f[I]LENGTH\f[R] طول مورد نظر بر حسب بایت برای تخلیه از مورد فرادادهٔ مشخص‌شده. تنها در ترکیب با \f[B]--offset\f[R] پذیرفته می‌شود. .TP \f[B]--offset\f[R]=\f[I]offset\f[R] آفست بر حسب بایت درون مورد فرادادهٔ مشخص‌شده که تخلیه از آنجا آغاز می‌شود. تنها در ترکیب با \f[B]--length\f[R] پذیرفته می‌شود. . .SS \f[B]fsverity enable\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R] .PP فعال‌سازی fs-verity روی فایل مشخص‌شده. این دستور تنها در صورتی کار خواهد کرد که سیستم‌فایل از fs-verity پشتیبانی کند. .PP گزینه‌های پذیرفته‌شده توسط \f[B]fsverity enable\f[R]: .TP \f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. .TP \f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. .TP \f[B]--salt\f[R]=\f[I]SALT\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. .TP \f[B]--signature\f[R]=\f[I]SIGFILE\f[R] امضای توکار را برای اعمال روی فایل مشخص می‌کند. \f[I]SIGFILE\f[R] باید فایلی باشد که حاوی امضا در قالب PKCS#7 DER است، برای مثال آنچه که توسط دستور \f[B]fsverity sign\f[R] تولید می‌شود. .RS .PP توجه داشته باشید که این گزینه تنها در صورتی لازم است که از قابلیت پشتیبانی هستهٔ لینوکس از راستی‌آزمایی امضای توکار fs-verity استفاده شود. اگر قرار است امضاها در فضای کاربری راستی‌آزمایی شوند به این گزینه نیازی نیست، زیرا در آن حالت امضاها باید جداگانه ذخیره گردند. .RE . .SS \f[B]fsverity measure\f[R] \f[I]FILE\f[R]\&... .PP نمایش خلاصهٔ fs-verity برای فایل یا فایل‌های داده‌شده. باید قابلیت fs-verity روی فایل‌ها فعال باشد. خروجی مشابه دستور \f[B]fsverity digest\f[R] با پارامترهای مناسب خواهد بود، اما \f[B]fsverity measure\f[R] برای هر فایل صرف‌نظر از اندازهٔ آن، در زمانی ثابت اجرا خواهد شد. .PP دستور \f[B]fsverity measure\f[R] هیچ گزینه‌ای نمی‌پذیرد. . .SS \f[B]fsverity sign\f[R] [\f[I]OPTION\f[R]\&...] \f[I]FILE\f[R] \f[I]OUT_SIGFILE\f[R] .PP امضای فایل داده‌شده برای fs-verity، به گونه‌ای که با پشتیبانی هستهٔ لینوکس از راستی‌آزمایی امضای توکار fs-verity سازگار باشد. امضا در قالب PKCS#7 DER در فایل \f[I]OUT_SIGFILE\f[R] نوشته خواهد شد. .PP کلید خصوصی می‌تواند از طریق فایل کلید یا از طریق توکن PKCS#11 مشخص شود. برای استفاده از فایل کلید، گزینهٔ \f[B]--key\f[R] و به صورت اختیاری \f[B]--cert\f[R] را مشخص کنید. برای استفاده از توکن PKCS#11، گزینه‌های \f[B]--pkcs11-engine\f[R]، \f[B]--pkcs11-module\f[R]، \f[B]--cert\f[R] و به صورت اختیاری \f[B]--pkcs11-keyid\f[R] را ارائه دهید. اگر fsverity-utils با نسخه‌ای از OpenSSL ساخته شده باشد که از توکن‌های PKCS#11 پشتیبانی نمی‌کند، پشتیبانی از توکن PKCS#11 در دسترس نخواهد بود. .PP دستور \f[B]fsverity sign\f[R] فقط در صورتی باید استفاده شود که به سازگاری با امضاهای توکار fs-verity نیاز داشته باشید. این تنها راه ایجاد امضاها با fs-verity نیست. برای اطلاعات بیشتر، فایل README مربوط به fsverity-utils را ببینید. .PP گزینه‌های پذیرفته‌شده توسط \f[B]fsverity sign\f[R]: .TP \f[B]--block-size\f[R]=\f[I]BLOCK_SIZE\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. .TP \f[B]--cert\f[R]=\f[I]CERTFILE\f[R] فایل حاوی گواهی (certificate) را در قالب PEM مشخص می‌کند. این گزینه زمانی لازم است که \f[I]KEYFILE\f[R] فقط شامل کلید خصوصی بوده و فاقد گواهی باشد، یا اگر از یک توکن PKCS#11 استفاده شود. .TP \f[B]--hash-alg\f[R]=\f[I]HASH_ALG\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. .TP \f[B]--key\f[R]=\f[I]KEYFILE\f[R] فایل حاوی کلید خصوصی را در قالب PEM مشخص می‌کند. این گزینه در صورت عدم استفاده از توکن PKCS#11 الزامی است. .TP \f[B]--out-descriptor\f[R]=\f[I]FILE\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. .TP \f[B]--out-merkle-tree\f[R]=\f[I]FILE\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. .TP \f[B]--pkcs11-engine\f[R]=\f[I]SOFILE\f[R] مسیر فایل موتور PKCS#11 متعلق به OpenSSL را مشخص می‌کند. این مقدار معمولاً مسیری به فایل ‎.so در libp11 خواهد بود. این گزینه هنگام استفاده از توکن PKCS#11 الزامی است. .TP \f[B]--pkcs11-keyid\f[R]=\f[I]KEYID\f[R] شناسهٔ کلید را در قالب یک PKCS#11 URI مشخص می‌کند. در صورت عدم ارائه، کلید پیش‌فرض مرتبط با توکن استفاده می‌شود. این گزینه تنها هنگام استفاده از یک توکن PKCS#11 قابل استفاده است. .TP \f[B]--pkcs11-module\f[R]=\f[I]SOFILE\f[R] مسیر کتابخانهٔ ماژولِ مختص توکن PKCS#11 را مشخص می‌کند. این گزینه هنگام استفاده از توکن PKCS#11 الزامی است. .TP \f[B]--salt\f[R]=\f[I]SALT\f[R] مشابه گزینهٔ \f[B]fsverity digest\f[R]. . . .SH "همچنین ببینید (SEE ALSO)" .PP برای دستورات نمونه و اطلاعات بیشتر، فایل README مربوط به fsverity-utils را در ببینید. .PP همچنین مستندات هسته را برای fs-verity در مشاهده کنید.