---
title: "تدوير المفتاح الرئيسي ومفتاح التوقيع والوصول الطارئ"
description: "دوّر المفتاح الرئيسي الذي يحمي بيانات الاعتماد المخزنة واستخدم الوصول الطارئ."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/ar/llms.txt
> Use this file to discover all available pages before exploring further.

# تدوير المفتاح الرئيسي ومفتاح التوقيع والوصول الطارئ

<span id="master-key-and-signing-key-rotation-and-break-glass-access"></span>

هذه هي الضوابط المسماة التي يطلبها المدقق في 21-compliance.md القسم 14. تعرض هذه الصفحة الإجراء؛ والسجلات الناتجة عنه هي الإثبات.

## المفاتيح <!--quire:the-keys-->

تُحفظ كل بيانات اعتماد مخزنة باستخدام مفتاح تشفير بيانات جديد (DEK). ويغلف المفتاح الرئيسي مفتاح DEK (ويسمى KEK)، ويُخزن مرجع المفتاح الرئيسي بجانبه (`key_ref` أو المرجع ضمن قيمة مجمعة). يعيد تدوير المفتاح الرئيسي تغليف مفاتيح DEK. ولا يفك تشفير بيانات اعتماد ولا يعيد تشفيرها.

| الإعداد | معناه |
| --- | --- |
| `QUIRE_MASTER_KEY` | المفتاح الرئيسي الحالي: 32 بايت بترميز base64. تُغلف كل أسرار جديدة به |
| `QUIRE_MASTER_KEY_VERSION` | وسم الإصدار. يكون `v1` عند عدم تعيينه. ارفعه كلما غيرت المفتاح |
| `QUIRE_MASTER_KEY_RETIRED` | المفاتيح الأقدم التي قد تظل أسرار مخزنة تحتها، مثل `v1=<base64>,v0=<base64>`. للقراءة فقط ولا تكتب إليها |

تقرأ طبقة الويب والعامل والأمر `bun run kek:rotate` الإعدادات الثلاثة نفسها. ويجب أن تتطابق قيمها جميعًا وإلا تعذر على أحدها فتح ما أغلقه الآخر.

من دون `QUIRE_MASTER_KEY` يحتفظ كل نظام فرعي بالمفتاح الذي يشتقه من `QUIRE_SECRET_KEY`. ويعمل ذلك، لكن صفحة حالة النظام تعرض الحالة متدهورة. وتظل البيانات قابلة للقراءة بعد ضبط مفتاح رئيسي، وهذه هي طريقة نقلها كلها منه في أول عملية تدوير. يستطيع كل من يقرأ بيئة العملية فك تشفير بيانات الاعتماد المخزنة، لذا ينبغي أن يملك تثبيت الإنتاج مفتاحًا رئيسيًا محفوظًا في مخزن أسرار وليس في النسخة الاحتياطية نفسها التي تحفظ قاعدة البيانات.

## التدوير <!--quire:rotating-->

يظهر عمر المفتاح في منصة الإدارة ضمن الأمان والمفتاح الرئيسي، كما يظهر المقياس `quire.secrets.master_key.age` بالأيام. ويضيف الجدول اليومي `platform.key_age` (03:41 UTC) تذكيرًا إلى سلسلة تدقيق المنصة عندما يبلغ عمر المفتاح 365 يومًا، ثم كل 30 يومًا إلى أن يجري تدويره. نفذ التدوير عند ظهور التذكير وكلما احتمل انكشاف المفتاح.

1. أنشئ المفتاح الجديد: `openssl rand -base64 32`.
2. عيّن `QUIRE_MASTER_KEY` عليه و`QUIRE_MASTER_KEY_VERSION` إلى الوسم التالي (`v2`). وانقل المفتاح القديم إلى `QUIRE_MASTER_KEY_RETIRED` بصيغة `v1=<old base64>`. احتفظ بنسخة من كليهما خارج هذا المضيف.
3. انشر طبقة الويب والعامل بالإعدادات الجديدة. تُغلف الأسرار الجديدة عندئذ تحت `env:QUIRE_MASTER_KEY:v2`، بينما تظل القديمة قابلة للفتح بالمفتاح المتقاعد.
4. اطلب التدوير مع ذكر السبب الذي سيظهر في سجل التدقيق:
   - من لوحة التحكم: الأمان، المفتاح الرئيسي، تدوير المفتاح الرئيسي؛ أو
   - من shell بالبيئة نفسها: `bun run kek:rotate request --reason "Annual rotation, ticket SEC-114"`.
5. يعيد العامل تغليف دفعة كل دقيقة (وفق جدول المجدول `platform.key_rotation`) ويستأنف بعد إعادة التشغيل. لإكماله دفعة واحدة، نفّذ `bun run kek:rotate run`. وتابعه عبر `bun run kek:rotate status`.
6. بعد أن يسجل النظام اكتمال التدوير مع **صفر قيم غير محسومة وصفر إخفاقات**، أزل المفتاح المتقاعد من `QUIRE_MASTER_KEY_RETIRED` وأعد النشر. وأبقِه حتى ذلك الحين؛ فقد تظل قيمة لم يستطع نقلها مغلفة بالمفتاح القديم.

### ما تمر عليه المهمة <!--quire:what-the-job-walks-->

كل مخزن يحمل مفتاح DEK مغلفًا: المخازن المدرجة في `SEALED_STORES` (`apps/worker/src/key-rotation.ts`). تُفحص مخازن قاعدة التحكم فيها؛ أما مخازن المؤسسات فتُفحص مؤسسةً تلو الأخرى وفق أمان الصفوف، وفي قاعدة البيانات التي توجد فيها المؤسسة. وبذلك يُدوّر المستأجر المثبت على قاعدة بيانات مخصصة ضمن تلك القاعدة. يفشل أحد الاختبارات إذا أضاف المخطط عمودًا لمفتاح مغلف لم تسرده القائمة، ويفشل اختبار آخر إذا صنفت مراجعة بيانات الاعتماد عمودًا مغلقًا أغفلته القائمة.

### السجل <!--quire:the-record-->

- `ops.key_rotation`: صف لكل عملية تدوير مع سببها ومقدم الطلب والحالة والإجماليات (أُعيد تغليفها، حديثة أصلًا، غير محسومة، فاشلة).
- `ops.key_rotation_progress`: صف لكل مخزن ونطاق بعد فحصه، مع مراجع المفاتيح التي تعذر قراءتها وعدد القيم التي تستخدم كل مرجع. وتتخطاها عملية التدوير المستأنفة.
- سلسلة تدقيق المنصة: `platform/key_rotation_request` مع السبب، وإدخال `platform/key_rotation_store` لكل مخزن وإحصاءاته، ثم `platform/key_rotation_complete` أو `platform/key_rotation_fail`؛ و`platform/key_age_reminder` للتذكير.
- المقاييس: `quire.secrets.master_key.age` و`quire.secrets.rewrap.outstanding` للقيم التي لم يستطع آخر تدوير نقلها.

### عند وجود قيم غير محسومة <!--quire:when-values-are-unresolved-->

تكون القيمة غير المحسومة مغلفة بمرجع مفتاح لا يملكه هذا التثبيت أو ليست بصيغة العمود المتوقعة. ويسمي سجل التقدم المرجع (مثل `env:QUIRE_MASTER_KEY:v0 (unreadable)`). أعد ذلك المفتاح إلى `QUIRE_MASTER_KEY_RETIRED` واطلب تدويرًا آخر؛ أو اطلب من مسؤول المؤسسة إدخال بيانات الاعتماد مجددًا إن فُقد المفتاح نهائيًا، وعندئذ تُحفظ تحت المفتاح الحالي. تعرض عملية التدوير الفاشلة الخطأ في سجلها؛ أصلح السبب واطلب العملية مجددًا.

## مفاتيح التوقيع <!--quire:signing-keys-->

تملك كل مؤسسة، باستقلال عن المفتاح الرئيسي، مفتاح RSA خاصًا بها لتوقيع رموز OpenID Connect ورسائل LTI، ويُنشر في `/.well-known/jwks.json`. لا يحتاج هذا الإجراء إلى مشغل. ينشر الجدول كل ساعة `platform.signing_keys` مفتاحًا بديلًا قبل سبعة أيام من اكتمال التسعين يومًا للمفتاح الحالي؛ وبعد أسبوع يبدأ البديل بالتوقيع ويتقاعد القديم، وبعد تسعين يومًا يُحذف المفتاح القديم من مجموعة المفاتيح. يسجل كل انتقال في سلسلة تدقيق المنصة باسم `platform/signing_key_advance`.

لتبديل مفتاح مؤسسة مبكرًا، مثلًا بعد انكشافه:

- من لوحة التحكم: الأمان، المفتاح الرئيسي، نشر مفتاح توقيع جديد (يتطلب `platform/keys_manage`)؛ أو
- من shell مع بيئة العامل: `bun run kek:rotate signing-keys rotate
  --tenant <slug or id> --reason "Key exposed, INC-3310"`. `bun run kek:rotate
  signing-keys status` يعرض مفاتيح كل مؤسسة ومراحلها.

يُنشر المفتاح الجديد فورًا ويبدأ التوقيع بعد سبعة أيام عندما يتقاعد الحالي. وهذه المهلة مقصودة: تحفظ الجهات المعتمدة مجموعة المفاتيح مؤقتًا، والتداخل الأقصر يعطل كل الأدوات دفعة واحدة. ويبقى المفتاح المتقاعد ضمن المجموعة 90 يومًا أخرى كي تستمر عملية التحقق من الرموز التي وقعها. وإذا تطلب انكشافه إيقاف الوثوق به قبل ذلك، فإن حذف صفه تغيير ينفذه المشغل بصلاحياته في قاعدة البيانات بموجب سجل تغيير (فالوصول الطارئ للقراءة فقط)، وعندئذ يفشل التحقق من الرموز التي وقعها. ويسجل التدوير القسري باسم `platform/signing_key_rotate` مع السبب في سلسلة التدقيق. يحتاج العامل إلى إعدادات `QUIRE_MASTER_KEY` نفسها الموجودة في طبقة الويب لتغليف المفتاح الجديد؛ ويعيد `bun run kek:rotate` الخاص بالمفتاح الرئيسي تغليف مفاتيح التوقيع إلى جانب بقية البيانات (`oauth_signing_key` مدرج في `SEALED_STORES`).

## الوصول الطارئ إلى الإنتاج <!--quire:break-glass-production-access-->

لا يحتفظ أحد بوصول دائم إلى الإنتاج. وعندما يتعذر الانتظار، يمنح مالك صلاحية طارئة من لوحة المنصة ضمن الأمان والوصول الطارئ.

- يشمل المنح نطاقًا (مؤسسة واحدة أو سجل المنصة) وسببًا لا يقل عن 20 حرفًا يذكر الحادثة أو التذكرة ومدة بين 5 و240 دقيقة. وينتهي تلقائيًا، إذ يجري التحقق من وقته مع كل عبارة.
- يمكن منحه للمالك الذي يصدره أو لمالك آخر (إجراء يتطلب شخصين). ولا يستطيع استخدامه إلا الشخص المحدد فيه. يتطلب الإصدار `platform/break_glass_issue` والاستخدام `platform/break_glass_use`؛ وكلاهما مقصور افتراضيًا على المالكين.
- تمر العبارات عبر البوابة لا عبر تسجيل دخول مباشر لقاعدة البيانات: القراءة فقط، واحدة في كل مرة، محصورة في المؤسسة أو سجل التحكم، بمهلة خمس ثوانٍ و500 صف كحد أقصى. وتُعرض القيم الثنائية بحجمها.
- تسجل سلسلة تدقيق المنصة الإصدار مع السبب والإلغاء وكل عبارة قبل تنفيذها (`platform/break_glass_statement`، والعبارات المرفوضة بحالة `denied`) وكل نتيجة (`platform/break_glass_result`). ويحفظ `ops.break_glass_statement` معرفات إدخالات التدقيق، ليصل سجل الإصدار بإدخالات التدقيق التابعة له.
- لا يُتاح إجراء كتابات. وإذا لم يحتمل تغيير انتظار إصدار جديد، فيُنفذ خارج هذا المنتج بصلاحيات المشغل في قاعدة البيانات وبموجب سجل تغيير خاص به، ويُذكر فيه مرجع الحادثة المستخدم هنا.

لماذا لا نمنح بيانات اتصال قاعدة البيانات: صلاحية Postgres تظل سارية بعد انتهاء جلسة طلبها، وتتجاوز أمان الصفوف الذي يعتمد عليه التطبيق، ولا تستطيع الكتابة إلى سلسلة تدقيق هذا المنتج؛ لذا لن تُدقق عباراتها إلا بقدر ما تُحفظ سجلات الخادم. تجعل البوابة سجل التدقيق جزءًا من آلية الوصول لا ممارسةً خارجية.

للرد على طلب تدقيق: اعرض المنح ضمن الفترة من صفحة الوصول الطارئ، وافتح سجل منحة لعرض عباراتها ومعرفات إدخالات التدقيق، ثم اقرأ الإدخالات من سلسلة تدقيق المنصة (`bun run audit:verify --platform` يثبت سلامة السلسلة).

Source: https://docs.quirelms.com/ar/ops/key-rotation/index.mdx