این سند اطلاعات ضروری در مورد فرآیند چرخش کلید برای یک برنامه وب ایزوله (IWA) ارائه میدهد، از جمله زمان لازم برای این کار و مراحلی که توسعهدهندگان باید در صورت گم شدن یا لو رفتن کلید دنبال کنند.
چرخش کلید برای IWAها
چرخش کلید مکانیزمی است که به کلیدهای خصوصی مورد استفاده برای امضای IWA شما اجازه میدهد در صورت نشت یا از دست رفتن، جایگزین شوند. این فرآیند باعث میشود برنامه کاربردی باشد و شناسه و مبدا بسته پایدار را حفظ کند و تداوم توزیع و بهروزرسانیهای برنامه شما را تضمین کند.
فرآیند چرخش کلید نیازی به هیچ گونه تغییر مدیر یا کاربر ندارد و اگر به درستی انجام شود، برای آنها قابل درک نخواهد بود. کانالهای ارتباطی مورد اعتماد که در طول فرآیند اولیه فهرستبندی مجوز ایجاد شدهاند، برای فعال کردن چرخش کلید ضروری هستند.
نیاز به چرخش کلید
چرخش کلید در دو سناریوی اصلی کاملاً ضروری است:
- نشت یا لو رفتن کلید: اگر کلید امضای خصوصی شما لو رفته یا احتمال لو رفتن آن وجود دارد، باید فوراً فرآیند چرخش کلید را برای ایمنسازی برنامه خود آغاز کنید. یک کلید لو رفته میتواند برای جعل هویت شما، آسیب رساندن به کاربران برنامه شما و به خطر انداختن اعتبار شرکت شما استفاده شود.
- از دست دادن کلید: اگر دسترسی به کلید امضای خصوصی خود را از دست بدهید و نتوانید بهروزرسانیهای جدید را امضا کنید، برای بازیابی توانایی توزیع برنامهتان، چرخش کلید ضروری است.
الزامات توسعهدهنده
قبل از شروع چرخش کلید، باید معیارهای زیر را داشته باشید:
- برنامهی مجاز: فقط برنامههای مجاز میتوانند مشمول چرخش کلید شوند.
- ایمیل معتبر: برای درخواست چرخش کلید، باید از آدرس ایمیل معتبری که در طول فرآیند فهرستبندی مجاز ارائه شده است، استفاده کنید.
انصراف از برنامههای میزبانیشده و انتشار نسخههای جدید
پس از تغییر کلید، تمام نمونههای برنامه نصبشده که با کلید معتبر امضا نشدهاند، مسدود میشوند. برای جلوگیری از اختلال برای کاربرانتان، باید برنامهای را که با کلید جدید (یا هر دو کلید) امضا شده است، ارائه دهید. جزئیات فنی بستههای کنار گذاشتهشده را میتوانید در بخش «نحوه امضای بسته با چندین کلید» بیابید. بسته به شرایط خاص شما، سناریوهای مختلفی وجود دارد:
سناریوی الف: کلید گم نشده است (برای مثال، چرخش پیشگیرانه یا نشتی)
شما باید برنامه را با هر دو کلید (قدیمی و جدید) امضا کنید و آنها را از طریق یکی از روشهای زیر به کاربران تحویل دهید:
- انتشار نسخه جدید برنامه (افزودن نسخه جدید به مانیفستهای بهروزرسانی شما)، یا
- بهروزرسانی فایلهای
.swbnمیزبانیشده (که در مانیفستهای بهروزرسانی شما لینک شدهاند) برای امضا شدن با هر دو کلید. ابزار CLI به شما امکان میدهد امضای دیگری را به بستهswbnموجود اضافه کنید.
این کار باید قبل از پردازش چرخش کلید توسط گوگل انجام شود تا مطمئن شوید کاربران شما متوجه این تغییر نمیشوند.
سناریوی ب: کلید گم شده است
از آنجا که برنامه با کلید گمشده قابل امضا نیست، این مورد پیچیدهتر است. درخواست چرخش کلید را بدهید و از مسئول گوگل خود مراحل بعدی را بپرسید. ممکن است از شما خواسته شود امضاهای جدید را طبق این دستورالعملها به بستههای میزبانیشده خود اضافه کنید.
فرآیند چرخش کلید
فرآیند چرخش کلید شامل مراحل زیر است:
| قدم | اکشن | جزئیات | مسئول |
|---|---|---|---|
| ۱ | درخواست چرخش کلید | توسعهدهنده/شریک از طریق ایمیل معتبر ارائه شده در فرآیند فهرستبندی مجاز، با رابط گوگل خود (شرکت مهندسی همکار یا سایر نقاط تماس) تماس میگیرد و دستورالعملهای چرخش کلید را با توضیح دلیل درخواست میکند. در صورت لو رفتن کلید، توصیه میکنیم برای سرعت بخشیدن به فرآیند، مانیفست بهروزرسانی را به همراه بستههای امضا شده با کلیدهای قدیمی و جدید پیوست کنید. | توسعهدهنده / شریک |
| ۲ | پاسخ به درخواست کننده | گوگل کانتکت دستورالعملها و سوالات بیشتری را در اختیار درخواستکننده قرار میدهد. این مرحله ممکن است شامل چند مرحله رفت و برگشت باشد. | تماس با گوگل |
| ۳ | ارائه داده | توسعهدهنده/شریک دستورالعملها را دنبال میکند، که از جمله ممکن است شامل موارد زیر باشد:
| توسعهدهنده / شریک |
| ۴ | پردازش درخواست و ارائه بازخورد | گوگل درخواست چرخش کلید را بررسی میکند و ظرف یک هفته کاری پاسخ میدهد، یا آن را تأیید یا رد میکند، یا برای سوالات بیشتر با توسعهدهنده تماس میگیرد. پس از تأیید، گوگل کلید را میچرخاند و بازخورد خود را ارائه میدهد. | تماس با گوگل |
بهروزرسانی کانال و پین کردن نسخه
مدیران سیستم گاهی اوقات از کانالهای بهروزرسانی سفارشی یا پینگذاری نسخه استفاده میکنند که به آنها امکان مدیریت نسخههای برنامه را در دستگاههای کلاینت خود میدهد. پس از چرخش کلید، تمام برنامههای نصب شده با کلیدهای نامعتبر نامعتبر شده و مسدود میشوند. برای جلوگیری از این امر، نسخههای قبلی برنامههای میزبانی شده تحت لینکهای ارائه شده در update_manifest.json نیز باید قبل از چرخش کلید، بهروزرسانی و با دو امضا امضا شوند. اگر کلید قدیمی شما گم شده است و برنامه را نمیتوان با دو کلید امضا کرد، فوراً به رابط گوگل خود اطلاع دهید. ما با شما همکاری خواهیم کرد تا وضعیت را کاهش دهیم تا برنامه بدون ایجاد اختلال در گردش کار کاربران شما بهروزرسانی شود.
نحوه امضای یک بسته با چندین کلید
این بخش توضیح میدهد که چگونه میتوانید بستههای وب خود را با یک یا دو کلید از طریق ابزارهای CLI یا پیکربندی افزونههای Webpack/Rollup/Vite امضا کنید. ابزارهای CLI همچنین امکان اضافه کردن یک امضای دیگر به بستههای swbn موجود را فراهم میکنند که میتواند در موارد از دست دادن کلید یا بهروزرسانی بستههای میزبانی شده قبلی مفید باشد.
ابزارهای CLI
ابتدا مطمئن شوید که بسته wbn-sign را با npm نصب کردهاید:
$ npm i wbn-sign
برای نصب بسته به صورت سراسری به جای نصب آن فقط در پوشه فعلی، از -g استفاده کنید.
امضا با یک کلید
$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem
امضا با دو کلید
$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>
آرگومان --web-bundle-id <id> را میتوان نادیده گرفت، اگر old_key اولین کلیدی باشد که نسخه اولیه برنامه با آن امضا شده است، آنگاه شناسه بسته از آن کلید استخراج میشود. میتوانید شناسه بسته را با دستور wbn-sign info signed.swbn تأیید کنید.
افزودن امضا به بسته موجود
$ wbn-sign add-signature signed.swbn key3.pem --in-place
اگر نمیخواهید بسته را لغو کنید اما یک فایل جدید با امضای دوگانه ایجاد میکنید، -o استفاده کنید.
اطلاعات بیشتر در مورد ابزار CLI
برای اطلاعات بیشتر در مورد استفاده از ابزار CLI ، صفحه npm wbn-sign را بررسی کنید. همچنین میتوانید wnb-sign help.
افزونه وبپک
امضا با یک کلید
برای پیکربندی افزونه Webpack جهت امضای IWA خود با استفاده از یک کلید خصوصی:
- افزونهی
WebBundlePluginرا طوری تنظیم کنید که به طور خودکار آدرس پایهی مورد نیاز را مستقیماً از این کلید استخراج کند. - برای تولید فایل
.swbnامضا شده خود، از یکNodeCryptoSigningStrategyواحد استفاده کنید.
// key is parsePemKey(private.pem)
plugins.push(
new WebBundlePlugin({
baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public' },
output: 'signed.swbn',
integrityBlockSign: {
strategy: new NodeCryptoSigningStrategy(key)
}
})
)
امضا با دو کلید
وقتی لازم است در طول چرخش کلید، درخواست خود را دو بار امضا کنید:
-
webBundleIdو Base URL را بر اساس (old_key) اصلی خود تعریف کنید تا از پایدار ماندن هویت برنامه برای کاربرانتان اطمینان حاصل شود. - از مجموعهای از استراتژیهای امضا برای اعمال کلیدهای خصوصی قدیمی و جدید خود استفاده کنید.
// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)
plugins.push(
new WebBundlePlugin({
baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public') },
output: 'signed.swbn',
integrityBlockSign: {
strategies: [
new NodeCryptoSigningStrategy(old_key),
new NodeCryptoSigningStrategy(new_key)
],
webBundleId: new WebBundleId(old_key).serialize()
}
})
)
افزونه Rollup یا Vite
امضا با یک کلید
برای استفاده از افزونه Rollup یا Vite جهت امضای برنامه خود با یک کلید خصوصی واحد، مشابه تنظیمات Webpack، این افزونه از یک استراتژی امضای واحد استفاده میکند و استخراج URL پایه از کلید ارائه شده را برای تولید خروجی امضا شده شما مدیریت میکند.
// key is parsePemKey(private.pem)
plugins.push({
...wbn({
baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public' },
output: 'signed.swbn',
integrityBlockSign: {
strategy: new NodeCryptoSigningStrategy(key)
}
}),
enforce: 'post'
})
امضا با دو کلید
برای امضای دوگانه برنامه خود با استفاده از Rollup یا Vite، باید افزونه را طوری پیکربندی کنید که چندین کلید را بپذیرد. این قطعه کد، کلیدهای خصوصی قدیمی و جدید را با استفاده از آرایه strategies اعمال میکند. این کار با حفظ صریح Base URL و webBundleId مشتق شده از کلید اصلی و موجود شما، یک انتقال یکپارچه را تضمین میکند.
// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)
plugins.push({
...wbn({
baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
static: { dir: 'public' },
output: 'signed.swbn',
integrityBlockSign: {
strategies: [
new NodeCryptoSigningStrategy(old_key),
new NodeCryptoSigningStrategy(new_key)
],
webBundleId: new WebBundleId(old_key).serialize()
}
}),
enforce: 'post'
})
نتیجهگیری
مدیریت موفقیتآمیز چرخش کلید برای IWA شما برای حفظ امنیت و تداوم توزیع برنامهتان بسیار مهم است. مستقل از وضعیت خاص شما (به عنوان مثال، اینکه کلید گم شده باشد یا خیر)، پیروی از مراحل ذکر شده تضمین میکند که کاربران شما حداقل اختلال را تجربه میکنند. با استفاده از ابزارهای CLI ارائه شده یا پیکربندیهای افزونه برای Webpack، Rollup یا Vite، میتوانید امضاهای برنامه خود را به طور موثر مدیریت کرده و فرآیند چرخش کلید را به راحتی طی کنید. در مواقع اضطراری، به یاد داشته باشید که فوراً از طریق ایمیل مورد اعتماد تعیین شده خود با مخاطب گوگل خود ارتباط برقرار کنید.