إنتقل إلى المحتوى الرئيسي

دليل التثبيت

يرشدك هذا الدليل الشامل خلال عملية التكامل الكاملة بين DuoKey Cockpit وبين CyberArk Enterprise Password Vault باستخدام موفّر PKCS#11 CockpitDLL.

نظرة عامة​

تتكون عملية التكامل من هذه المراحل الرئيسية:

  1. تكوين DuoKey Cockpit - إنشاء تطبيق KMS Client والحصول على بيانات الاعتماد
  2. تثبيت CockpitDLL - تثبيت موفّر PKCS#11 على خادم CyberArk
  3. تكوين CyberArk - إعداد تكامل HSM في CyberArk
  4. إنشاء المفتاح الرئيسي - إنشاء مفتاح تشفير جديد في DuoKey HSM
  5. إعادة تشفير الخزنة - الترحيل إلى التشفير المُدار بواسطة DuoKey
  6. التحقق والاختبار - التحقق من صحة التكامل
هام

نفّذ هذه الخطوات في بيئة تطوير/اختبار أولاً قبل تطبيقها في الإنتاج. أنشئ نسخًا احتياطية من خزنة CyberArk الخاصة بك قبل المتابعة.

المرحلة 1: تكوين DuoKey Cockpit​

الخطوة 1.1: تسجيل الدخول إلى DuoKey Cockpit​

  1. انتقل إلى عنوان URL الخاص بـ DuoKey Cockpit في متصفح ويب
  2. أدخل بيانات الاعتماد الخاصة بك لتسجيل الدخول

الخطوة 1.2: إنشاء تطبيق KMS Client​

  1. في لوحة التنقل اليسرى في Cockpit، انقر على عنصر القائمة Apps

  2. انقر على زر + لإنشاء تطبيق جديد

  3. في صفحة Create New App، قم بتكوين ما يلي:

    • App Name: أدخل CyberArk-EPV (أو الاسم الذي تفضّله)
    • App Type: اختر KMS Client من القائمة المنسدلة
    • Description (اختياري): أدخل PKCS#11 integration for CyberArk EPV
    • Access Control (اختياري): عيّن الأدوار إذا كنت تستخدم RBAC

  4. انقر على CREATE لإضافة تطبيق KMS Client الجديد

الخطوة 1.3: نسخ بيانات اعتماد واجهة API​

  1. بمجرد إنشاء التطبيق، سترى صفحة تفاصيل التطبيق
  2. انقر على VIEW API KEY أو API CREDENTIALS
  3. انسخ API Key - ستحتاج إليه لاحقًا لمصادقة PKCS#11
احفظ بيانات الاعتماد بشكل آمن

خزّن مفتاح API في مدير كلمات مرور آمن. ستحتاج إليه لتكوين موفّر PKCS#11.

  1. لاحظ أيضًا API Endpoint URL (على سبيل المثال، https://cockpit.duokey.com أو عنوان URL المحلي الخاص بك)

المرحلة 2: تنزيل وتثبيت CockpitDLL​

الخطوة 2.1: تنزيل DuoKey PKCS#11 CockpitDLL​

  1. نزّل أحدث إصدار من DuoKey PKCS#11 CockpitDLL لنظام Windows 64-bit من:

    • بوابة عملاء DuoKey، أو
    • تواصل مع [email protected] للحصول على رابط التنزيل

  2. يجب أن تتلقى ملفًا باسم مشابه لـ: DuokeyCockpitDLL_x64.msi

الخطوة 2.2: تثبيت CockpitDLL​

  1. شغّل المُثبّت DuokeyCockpitDLL_x64.msi بامتيازات المسؤول (Administrator)

  2. اتبع معالج التثبيت:

    • اقبل اتفاقية الترخيص
    • اختر دليل التثبيت (الافتراضي: C:\Program Files\Duokey\CockpitDLL\)
    • انقر على Install

  3. سيضع المُثبّت الملفات التالية:

    • C:\Program Files\Duokey\CockpitDLL\DuokeyCockpitPkcs11.dll - مكتبة PKCS#11
    • C:\Program Files\Duokey\CockpitDLL\DuokeyCockpitConfig.exe - أداة التكوين

الخطوة 2.3: تكوين نقطة نهاية CockpitDLL​

افتح Command Prompt كمسؤول وشغّل:

للجهاز المحلي (تكوين على مستوى النظام):

cd "C:\Program Files\Duokey\CockpitDLL"
DuokeyCockpitConfig.exe machine --api-endpoint https://your-cockpit-url.duokey.com

للمستخدم الحالي فقط:

cd "C:\Program Files\Duokey\CockpitDLL"
DuokeyCockpitConfig.exe user --api-endpoint https://your-cockpit-url.duokey.com

استبدل your-cockpit-url.duokey.com بعنوان URL الفعلي الخاص بـ DuoKey Cockpit.

تخزين التكوين

يُخزّن التكوين في سجل Windows (Windows Registry):

  • الجهاز: HKEY_LOCAL_MACHINE\SOFTWARE\Duokey\CockpitDLL
  • المستخدم: HKEY_CURRENT_USER\SOFTWARE\Duokey\CockpitDLL

الخطوة 2.4: التحقق من التثبيت​

تحقق من أن ملف DLL مُثبّت بشكل صحيح:

dir "C:\Program Files\Duokey\CockpitDLL\DuokeyCockpitPkcs11.dll"

يجب أن ترى ملف DLL مدرجًا في القائمة.

المرحلة 3: تكوين CyberArk EPV​

الخطوة 3.1: إعداد الاتصال بالشبكة​

هام - يُنفَّذ قبل التحصين (Hardening)

يجب إكمال هذه الخطوات قبل تطبيق إجراءات تحصين CyberArk. تقيّد نصوص التحصين البرمجية الاتصال الخارجي وقد تحظر الوصول إلى DuoKey Cockpit.

3.1.1: تكوين ملف Hosts​

  1. افتح ملف hosts في Windows بامتيازات المسؤول:

    notepad C:\Windows\System32\drivers\etc\hosts

  2. أضف إدخالاً لنقطة نهاية DuoKey Cockpit الخاصة بك:

    <IP_Address> your-cockpit-url.duokey.com

    استبدل <IP_Address> بعنوان IP الفعلي الخاص بـ DuoKey Cockpit.

3.1.2: تكوين قواعد جدار الحماية​

  1. عدّل C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini

  2. أضف DuoKey Cockpit إلى القائمة البيضاء لجدار الحماية في القسم [AllowNonStandardFWAddresses]:

    [AllowNonStandardFWAddresses]
    AllowNonStandardFWAddresses=xx.xxx.xxx.xxx,Yes,443:inbound/tcp,443:outbound/tcp

    استبدل xx.xxx.xxx.xxx بعنوان IP الخاص بـ DuoKey Cockpit.

3.1.3: استعادة مجموعة تشفير TLS​

بعد تحصين CyberArk، قد تحتاج إلى استعادة مجموعات تشفير TLS المتوافقة:

  1. افتح Windows PowerShell كمسؤول

  2. شغّل الأمر التالي:

    Enable-TlsCipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

  3. تحقق من إضافة مجموعة التشفير عن طريق فحص سجل Windows:

    Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Cryptography\Configuration\Local\SSL\00010002

الخطوة 3.2: تكوين مسار موفّر PKCS#11​

  1. افتح C:\Program Files (x86)\PrivateArk\Server\conf\dbparm.ini باستخدام محرّر نصوص

  2. أضف أو عدّل القسم [HSM]:

    [HSM]
    PKCS11ProviderPath=C:\Program Files\Duokey\CockpitDLL\DuokeyCockpitPkcs11.dll

  3. احفظ الملف

الخطوة 3.3: تكوين رمز PIN لـ PKCS#11 (مفتاح API)​

3.3.1: إنشاء ملف مفتاح API​

  1. أنشئ دليلاً لتخزين المفاتيح المؤقت:

    mkdir C:\temp\duokey

  2. أنشئ ملفًا C:\temp\duokey\api_key.txt بالمحتوى التالي:

    api_key = "<your_api_key_from_step_1.3>"

    استبدل <your_api_key_from_step_1.3> بمفتاح API الفعلي من DuoKey Cockpit.

3.3.2: تكوين رمز PIN باستخدام CAVaultManager​

  1. افتح Command Prompt كمسؤول

  2. انتقل إلى دليل خادم CyberArk:

    cd "C:\Program Files (x86)\PrivateArk\Server"

  3. شغّل CAVaultManager لتخزين مفتاح API بشكل آمن:

    CAVaultManager.exe SecureSecretFiles /SecretType HSM /Secret file://C:\temp\duokey\api_key.txt

  4. تحقق من تشفير رمز PIN عن طريق فتح dbparm.ini - يجب أن ترى:

    HSMPinCode=<encrypted_value>
أفضل ممارسة أمنية

احذف ملف C:\temp\duokey\api_key.txt بعد بدء تشغيل خادم CyberArk بنجاح:

del C:\temp\duokey\api_key.txt

3.3.3: إيقاف خادم PrivateArk​

إذا كان خادم PrivateArk قيد التشغيل، أوقفه قبل المتابعة:

net stop PrivateArk

المرحلة 4: إنشاء مفتاح رئيسي جديد في DuoKey HSM​

الخطوة 4.1: إنشاء مفتاح الخادم على HSM​

  1. من Command Prompt في دليل خادم CyberArk:

    cd "C:\Program Files (x86)\PrivateArk\Server"

  2. شغّل الأمر لإنشاء مفتاح خادم جديد:

    CAVaultManager.exe GenerateKeyOnHSM /ServerKey

  3. لاحظ KeyID من الاستجابة. على سبيل المثال:

    CAVLT187I Server Key was successfully generated on HSM device (KeyID=HSM#1).

    سيكون KeyID هو HSM#1 (أو HSM#2 أو HSM#3 وهكذا)

الخطوة 4.2: التحقق من المفتاح في DuoKey Cockpit​

  1. سجّل الدخول إلى واجهة ويب DuoKey Cockpit

  2. انتقل إلى قسم Apps

  3. انقر على تطبيق CyberArk-EPV الذي أنشأته سابقًا

  4. انقر على علامة التبويب Keys أو Security Objects

  5. يجب أن ترى مفتاحًا جديدًا أنشأه تطبيق CyberArk EPV مع طابع زمني

الخطوة 4.3: تحديث ServerKey في dbparm.ini​

  1. افتح C:\Program Files (x86)\PrivateArk\Server\conf\dbparm.ini

  2. ابحث عن معلمة ServerKey أو أضفها واضبطها على KeyID من الخطوة 4.1:

    ServerKey=HSM#1

  3. احفظ الملف

لا تشغّل الخادم بعد

لا تشغّل خادم PrivateArk حتى بعد إكمال إعادة تشفير الخزنة في المرحلة 5.

المرحلة 5: إعادة تشفير خزنة CyberArk​

الخطوة 5.1: التحضير لإعادة التشفير​

  1. تأكد من امتلاكك لما يلي:

    • نسخة احتياطية حالية من الخزنة
    • المفتاح الخاص للاسترداد (RecPrv.key)
    • ملف كلمة مرور طوارئ الخزنة (VaultEmergency.pass)
    • مفتاح خادم جديد تم إنشاؤه (من المرحلة 4)

  2. حدد موقع دليل مفاتيح مشغّل CyberArk (على سبيل المثال، C:\OperatorKeys)

الخطوة 5.2: تشغيل أداة ChangeServerKeys​

  1. افتح Command Prompt كمسؤول

  2. انتقل إلى دليل خادم CyberArk:

    cd "C:\Program Files (x86)\PrivateArk\Server"

  3. شغّل أداة ChangeServerKeys:

    ChangeServerKeys.exe <keys_directory> <vault_emergency_pass_path> HSM#1

    مثال:

    ChangeServerKeys.exe C:\OperatorKeys C:\OperatorKeys\VaultEmergency.pass HSM#1

  4. ستطلب الأداة تأكيدًا:

    HSM generation 1 was chosen, are you sure you want to change server keys to HSM (y/n)?

    اكتب y واضغط على Enter

  5. اتبع التعليمات:

    Verify that the current master key is at C:\OperatorKeys\RecPrv.key, and press any key.

    اضغط على أي مفتاح للمتابعة

  6. ستبدأ عملية إعادة التشفير. مثال على الإخراج:

    CHSRVK043I Signing entropy file C:\PrivateArk\Safes\entropy.rnd with new keys.
    CHSRVK034I Encrypting server private key.
    CHSRVK058I Encrypting Backup key.
    CHSRVK057I Encrypting Database access passwords.
    CHSRVK020I Keys of Safe System changed successfully.
    CHSRVK040I Changing keys for Safe <SafeName>.
    ...
    CHSRVK054I ChangeServerKeys process was successful.
وقت إعادة التشفير

تعتمد مدة عملية إعادة التشفير على عدد وحجم الخزائن (safes) في خزنتك. قد يستغرق ذلك من عدة دقائق إلى ساعات للخزائن الكبيرة.

الخطوة 5.3: التحقق من نجاح إعادة التشفير​

  1. تأكد من ظهور رسالة النجاح:

    CHSRVK054I ChangeServerKeys process was successful. DBParm.ini must be updated to point to new keys for Vault to start.

  2. تحقق من أن معلمة ServerKey في dbparm.ini مضبوطة بشكل صحيح:

    ServerKey=HSM#1

المرحلة 6: البدء والتحقق​

الخطوة 6.1: بدء خادم PrivateArk​

  1. ابدأ خدمة خادم PrivateArk:

    net start PrivateArk

  2. راقب بدء تشغيل الخدمة في عارض الأحداث (Event Viewer) أو سجلات CyberArk:

    C:\Program Files (x86)\PrivateArk\Server\Logs

الخطوة 6.2: التحقق من تكامل HSM​

فحص سجلات CyberArk​

ابحث عن تهيئة HSM الناجحة في سجلات PrivateArk:

CAVLT187I Successfully connected to HSM device
ITADM114I Successfully connected to Database, Database id 0

اختبار عمليات الخزنة​

  1. افتح PrivateArk Client أو PVWA (Password Vault Web Access)

  2. سجّل الدخول باستخدام بيانات الاعتماد الخاصة بك

  3. نفّذ العمليات الأساسية:

    • افتح خزنة (safe) موجودة
    • أضف حسابًا جديدًا
    • استرجع كلمة مرور

  4. إذا نجحت جميع العمليات، فإن تكامل HSM يعمل بشكل صحيح

الخطوة 6.3: التحقق في DuoKey Cockpit​

  1. سجّل الدخول إلى DuoKey Cockpit

  2. انتقل إلى تطبيق CyberArk-EPV الخاص بك

  3. تحقق من علامة التبويب Audit Log

  4. يجب أن ترى العمليات التشفيرية مسجّلة:

    • إنشاء المفاتيح
    • عمليات التشفير
    • عمليات فك التشفير

استكشاف الأخطاء وإصلاحها​

المشكلات الشائعة​

المشكلة: "Failed to connect to HSM"​

الأسباب المحتملة:

  • تكوين غير صحيح لنقطة نهاية API
  • مشكلات في الاتصال بالشبكة
  • جدار الحماية يحظر حركة مرور HTTPS

الحل:

  1. تحقق من تكوين نقطة النهاية:

    reg query "HKLM\SOFTWARE\Duokey\CockpitDLL" /v ApiEndpoint

  2. اختبر الاتصال:

    ping your-cockpit-url.duokey.com
    curl https://your-cockpit-url.duokey.com/api/health

  3. تحقق من قواعد جدار الحماية في dbparm.ini

المشكلة: "Invalid PIN" أو "Authentication Failed"​

الأسباب المحتملة:

  • مفتاح API غير صحيح
  • مفتاح API غير مشفّر بشكل صحيح
  • انتهت صلاحية مفتاح API أو تم إبطاله

الحل:

  1. تحقق من أن مفتاح API في DuoKey Cockpit لا يزال صالحًا

  2. أعد تشغيل CAVaultManager بمفتاح API الصحيح:

    CAVaultManager.exe SecureSecretFiles /SecretType HSM /Secret file://C:\temp\duokey\api_key.txt

  3. أعد تشغيل خادم PrivateArk

المشكلة: "Key not found" أو "HSM#1 not found"​

الأسباب المحتملة:

  • لم يتم إنشاء المفتاح بنجاح
  • KeyID غير صحيح في dbparm.ini
  • تم حذف المفتاح من DuoKey Cockpit

الحل:

  1. تحقق من وجود المفتاح في DuoKey Cockpit

  2. تأكد من أن KeyID في dbparm.ini يطابق المفتاح في Cockpit

  3. أنشئ مفتاحًا جديدًا إذا لزم الأمر

المشكلة: أخطاء اتصال TLS/SSL​

الأسباب المحتملة:

  • مجموعات تشفير TLS غير متوافقة
  • فشل التحقق من صحة الشهادة
  • عدم تطابق إصدار TLS

الحل:

  1. تأكد من تمكين TLS 1.2 أو أعلى

  2. استعد مجموعة التشفير المطلوبة:

    Enable-TlsCipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

  3. تحقق من سلسلة الثقة للشهادة

الحصول على المساعدة​

إذا واجهت مشكلات غير مغطاة هنا:

  1. تحقق من سجلات CyberArk: C:\Program Files (x86)\PrivateArk\Server\Logs

  2. تحقق من عارض أحداث Windows (Event Viewer) بحثًا عن أخطاء التطبيق والنظام

  3. راجع سجلات تدقيق DuoKey Cockpit بحثًا عن العمليات الفاشلة

  4. تواصل مع الدعم:

    • البريد الإلكتروني: [email protected]
    • أرفق: ملفات السجل، ورسائل الأخطاء، وتفاصيل التكوين

الخطوات التالية​

بعد نجاح التكامل:

  1. اختبر بشكل شامل - نفّذ اختبارًا شاملاً لجميع عمليات الخزنة

  2. وثّق التكوين - سجّل جميع تفاصيل التكوين لسجلاتك

  3. النسخ الاحتياطي - أنشئ نسخة احتياطية جديدة من خزنتك مع تشفير HSM

  4. المراقبة - أعدّ المراقبة لعمليات HSM في DuoKey Cockpit

  5. خطّط لتدوير المفاتيح - راجع دليل تدوير المفاتيح

  6. التعافي من الكوارث - حدّث إجراءات التعافي من الكوارث لتشمل الوصول إلى DuoKey Cockpit

انتقل إلى دليل العمليات للاطلاع على مهام الإدارة اليومية.