שימוש במפתח Cloud HSM עם OpenSSL

במדריך הזה מפורטות הוראות להגדרת OpenSSL לשימוש במפתח Cloud HSM ב-Debian 11 (Bullseye). ההוראות האלה רלוונטיות בדרך כלל גם אם אתם משתמשים במערכת הפעלה או בסביבה אחרת, אבל שימו לב שיכולים להיות הבדלים קלים.

דרישות

כדי להתחיל, מורידים גרסה של הספרייה. פרטים נוספים על ספריית PKCS #11 זמינים במדריך למשתמש.

לפני שמתחילים, מתקינים את חבילת libengine-pkcs11-openssl.

sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl

הגדרות אישיות

הגדרת משתנה הסביבה PKCS11_MODULE_PATH.

כדי ש-openssl ישתמש בספריית PKCS #11 שלנו, צריך להגדיר את משתנה הסביבה PKCS11_MODULE_PATH:

export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"

כדי להגדיר את משתנה הסביבה באופן קבוע, מוסיפים את export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" אל /etc/profile על ידי הרצת הפקודה הבאה:

echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile

הגדרת ספריית PKCS #11

הספרייה של PKCS #11 דורשת קובץ הגדרות YAML כדי לאתר משאבי Cloud KMS. קובץ ה-YAML חייב להגדיר לפחות אסימון PKCS #11 אחד.

אם אתם משתמשים ב-OpenSSL עם תהליך אחר שעשוי להסתיים בפיצול (לדוגמה, Apache או Nginx), אתם צריכים לוודא גם שהשדה refresh_interval_secs לא מוגדר או מוגדר ל-0.

קובץ הגדרה לדוגמה:

---
tokens:
  - key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"

במסגרת ההגדרה הזו, כל מפתחות החתימה והפענוח האסימטריים ב-my-keyring יהיו זמינים בספרייה.

צריך להגדיר את ההרשאות בקובץ התצורה כך שרק הבעלים של הקובץ יוכל לכתוב בו. מציינים את קובץ התצורה שלכם באמצעות KMS_PKCS11_CONFIG:

export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"

כדי שההגדרה הזו תהיה קבועה, אפשר להוסיף אותה ל-/etc/profile.

echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile

הרצת פקודות OpenSSL

אחרי שמגדירים את המנוע והספרייה בצורה נכונה, אפשר להשתמש במנוע בפקודות OpenSSL.

כשיוצרים חתימות אסימטריות, חשוב לזכור שמפתחות Cloud KMS מוגבלים לשימוש בגיבוב יחיד. לדוגמה, תמיד צריך להשתמש ב-CryptoKeyVersion עם האלגוריתם EC_SIGN_P256_SHA256 בשילוב עם תקציר SHA-256. הדגל הזה תואם לדגל -sha256 ב-OpenSSL. צריך להשתמש במקשים שדורשים תקצירים של SHA-384 או SHA-512 עם הדגלים -sha384 או -sha512.

יצירת חתימה חדשה

בהנחה שיש אוסף מפתחות מוגדר עם מפתח בשם foo, משתמשים בפקודה הבאה כדי ליצור חתימה על bar.txt:

openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt

הפלט של הפקודה הזו הוא בינארי לא מעוצב.

הפקודה הזו מניחה שאתם משתמשים במפתח שמשתמש בגיבוב SHA-256, ולכן נעשה שימוש בארגומנט -sha256. האפשרויות -sha384 או -sha512 מתאימות למפתחות Cloud HSM שמשתמשים בסוגי הגיבוב האלה.

אם משתמשים במפתח RSA-PSS, חשוב להשתמש באפשרויות -sigopt שצוינו קודם.

יצירת בקשת חתימה על אישור חדשה

אפשר גם ליצור בקשת חתימה על אישור (CSR) למפתח חתימה של Cloud HSM. זה שימושי אם רשות האישורים שלכם דורשת CSR כדי ליצור אישור חדש לחתימת קוד, או כדי להגן על סשנים של TLS באינטרנט.

‫
openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.csr
-sigopt

יצירת אישור חדש בחתימה עצמית

לצורכי פיתוח ובדיקות מקומיות, אפשר להשתמש באישור עם חתימה עצמית למפתח חתימה של Cloud HSM. אישורים בחתימה עצמית שימושיים גם לחתימה על טוקנים של SAML.

openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.crt

פתרון בעיות באמצעות PKCS #11 Spy

PKCS #11 Spy הוא כלי בקוד פתוח שמתעד את תוכן האינטראקציות בממשק PKCS #11. היא עושה את זה על ידי ישיבה בין האפליקציה לבין ספריית PKCS #11, ותיעוד של כל הקריאות שמתבצעות. הפעולה הזו יכולה לעזור בפתרון בעיות.

כדי להשתמש ב-PKCS #11 Spy, צריך להתקין את חבילת opensc. חבילת opensc מכילה את PKCS #11 Spy. כדי לוודא ש-opensc מותקן, מריצים את הפקודה הבאה:

sudo apt-get install opensc

לאחר מכן, מגדירים את משתנה הסביבה PKCS11_MODULE_PATH כך שיפנה את OpenSSL לספריית PKCS #11 Spy על ידי הרצת הפקודה הבאה:

export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so

לבסוף, מגדירים את משתני הסביבה PKCS11SPY ו-PKCS11SPY_OUTPUT כדי להפנות את PKCS #11 Spy לספריית PKCS #11 של Cloud HSM. כדי להגדיר את משתני הסביבה האלה, מריצים את הפקודות הבאות:

export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"