שימוש במפתח Cloud HSM כדי להציג תנועה ב-Apache

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

גרסה של המדריך הזה שמבוססת על Terraform זמינה במאגר GitHub של kms-solutions.

לפני שמתחילים

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

אחרי שמסיימים את ההגדרה של OpenSSL, מוודאים שמותקנת גרסה עדכנית של Apache:

sudo apt-get update
sudo apt-get install apache2

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

יצירת מפתח חתימה שמתארח ב-Cloud KMS

יוצרים מפתח חתימה של Cloud KMS בEC-P256-SHA256פרויקטGoogle Cloud , באוסף המפתחות שהגדרתם קודם ל-OpenSSL:

gcloud kms keys create "KEY_NAME" --keyring "KEY_RING" \
  --project "PROJECT_ID" --location "LOCATION" \
  --purpose "asymmetric-signing" --default-algorithm "ec-sign-p256-sha256" \
  --protection-level "hsm"

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

יוצרים אישור עם חתימה עצמית באמצעות מפתח החתימה שמתארח ב-Cloud KMS. אפשר להשתמש ב-OpenSSL כדי להשתמש ב-URI של PKCS #11 במקום בנתיב קובץ, ולזהות את המפתח לפי התווית שלו. בספריית Cloud KMS PKCS #11, תווית המפתח היא השם של CryptoKey.

openssl req -new -x509 -days 3650 -subj '/CN=CERTIFICATE_NAME/' \
  DIGEST_FLAG -engine pkcs11 -keyform engine \
  -key PKCS_KEY_TYPE=KEY_IDENTIFIER > PATH_TO_CERTIFICATE

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CERTIFICATE_NAME: שם לאישור.
  • ‫DIGEST_FLAG: אלגוריתם הגיבוב שבו נעשה שימוש במפתח החתימה האסימטרי. משתמשים ב--sha256, ב--sha384 או ב--sha512 בהתאם למקש.
  • ‫PKCS_KEY_TYPE: סוג המזהה שמשמש לזיהוי המפתח. כדי להשתמש בגרסה העדכנית ביותר של המפתח, משתמשים בפונקציה pkcs11:object עם שם המפתח. כדי להשתמש בגרסה ספציפית של מפתח, משתמשים ב-pkcs11:id עם מזהה המשאב המלא של גרסת המפתח.
  • ‫KEY_IDENTIFIER: מזהה של המפתח. אם אתם משתמשים ב-pkcs11:object, צריך להשתמש בשם המפתח – לדוגמה, KEY_NAME. אם אתם משתמשים ב-pkcs11:id, צריך להשתמש במזהה המשאב המלא של המפתח או של גרסת המפתח – לדוגמה, projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION.
  • ‫PATH_TO_CERTIFICATE: הנתיב שבו רוצים לשמור את קובץ האישור.

אם הפקודה הזו נכשלת, יכול להיות שהאילוץ PKCS11_MODULE_PATH הוגדר בצורה שגויה, או שאין לכם את ההרשאות הנכונות לשימוש במפתח החתימה של Cloud KMS.

עכשיו אמור להיות לכם אישור שנראה כך:

-----BEGIN CERTIFICATE-----
...
...
...
-----END CERTIFICATE-----

הגדרת שרת Apache

  1. יוצרים ספרייה ב-/etc/apache2 לאחסון האישור בחתימה עצמית:

    sudo mkdir /etc/apache2/ssl
sudo mv ca.cert /etc/apache2/ssl

  2. עורכים את קובצי התצורה של המארח הווירטואלי 000-default.conf שנמצאים ב-/etc/apache2/sites-available כדי לספק את נתיב קובץ האישור ולוודא שה-SSLEngine מופעל.

    הנה דוגמה להגדרה של האזנה ביציאה 443:

      <VirtualHost *:443>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
        SSLEngine on
        SSLCertificateFile /etc/apache2/ssl/ca.cert
        SSLCertificateKeyFile "PKCS_KEY_TYPE=KEY_IDENTIFIER"
  </VirtualHost>

  3. כדי לוודא ש-Apache מייצא את משתני הסביבה בצורה נכונה, מוסיפים אותם לקובץ /etc/apache2/envvars באמצעות עורך הטקסט הרצוי. יכול להיות שתצטרכו לערוך את הקובץ כמשתמש root באמצעות sudo. מוסיפים את השורות הבאות לסוף הקובץ:

    export PKCS11_MODULE_PATH="<var>PATH_TO_LIBKMSP11</var>"
export KMS_PKCS11_CONFIG="<var>PATH_TO_PKCS11_CONFIG</var>"
export GRPC_ENABLE_FORK_SUPPORT=1

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PATH_TO_LIBKMSP11: הנתיב אל libkmsp11.so.
    • ‫PATH_TO_PKCS11_CONFIG: הנתיב אל pkcs11-config.yaml.

    ‫GRPC_ENABLE_FORK_SUPPORT נדרש כדי ש-gRPC יכלול תמיכה בפיצול (fork) ויריץ בצורה תקינה את ספריית PKCS #11 של Cloud KMS כחלק משרת Apache.

    אם רוצים לבצע אימות באמצעות מפתח של חשבון שירות, צריך גם לייצא ערך למשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.

הפעלת השרת

מפעילים את מודול ה-SSL של Apache, מפעילים את ההגדרה של ה-virtualhost ומוסיפים דף אינטרנט לבדיקה בתיקייה DocumentRoot:

sudo a2enmod ssl
sudo a2ensite 000-default.conf
echo '<!doctype html><html><body><h1>Hello World!</h1></body></html>' | \
  sudo tee /var/www/html/index.html

מפעילים מחדש את שרת Apache ובודקים באמצעות curl שההגדרה פועלת כמצופה. צריך להשתמש בדגל --insecure כדי להתעלם מבדיקות של אישורים בחתימה עצמית.

sudo systemctl restart apache2
curl -v --insecure https://127.0.0.1

אם נתקלתם בשגיאות, כדאי להתחיל עם יומן השגיאות של Apache כדי לראות מה השתבש. בעיות באימות הן מקור נפוץ לשגיאות. אם מופיעות שגיאות PERMISSION_DENIED, צריך לוודא שעברתם אימות מלא ושלקובץ פרטי הכניסה יש את ההרשאות הנכונות. כדי לוודא שהאימות הושלם, מריצים את הפקודה הבאה:

gcloud auth application-default login

כדי לוודא שהאימות בוצע בהצלחה, הפלט צריך לכלול את השורה Credentials saved to file: [/path/to/credentials.json].