Menggunakan kunci Cloud HSM dengan OpenSSL

Panduan ini memberikan petunjuk untuk menyiapkan OpenSSL guna menggunakan kunci Cloud HSM di Debian 11 (Bullseye). Petunjuk ini umumnya berlaku meskipun Anda menggunakan OS atau lingkungan lain, tetapi perhatikan bahwa mungkin ada sedikit perbedaan.

Persyaratan

Download rilis library untuk memulai. Untuk mengetahui detail tambahan tentang library PKCS #11, lihat panduan pengguna.

Sebelum memulai, instal paket libengine-pkcs11-openssl.

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

Konfigurasi

Menetapkan variabel lingkungan PKCS11_MODULE_PATH.

Agar openssl dapat menggunakan library PKCS #11, tetapkan variabel lingkungan PKCS11_MODULE_PATH:

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

Untuk menetapkan variabel lingkungan secara permanen, tambahkan export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" ke /etc/profile dengan menjalankan perintah berikut:

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

Konfigurasi library PKCS #11

Library PKCS #11 memerlukan file konfigurasi YAML untuk menemukan resource Cloud KMS. YAML minimal harus mengonfigurasi satu token PKCS #11.

Jika Anda menggunakan OpenSSL dengan proses lain yang mungkin berakhir dengan forking (misalnya, Apache atau Nginx), Anda juga harus memastikan bahwa kolom refresh_interval_secs tetap tidak ditetapkan, atau ditetapkan ke 0.

Contoh file konfigurasi:

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

Dengan konfigurasi ini, semua kunci penandatanganan dan dekripsi asimetris di my-keyring akan tersedia di library.

Anda harus menetapkan izin pada file konfigurasi agar hanya dapat ditulis oleh pemilik file. Arahkan KMS_PKCS11_CONFIG ke file konfigurasi Anda:

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

Sekali lagi, Anda dapat membuat setelan ini permanen dengan menambahkannya ke /etc/profile.

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

Menjalankan perintah OpenSSL

Dengan mesin dan library yang dikonfigurasi dengan benar, Anda kini dapat menggunakan mesin dalam perintah OpenSSL.

Saat membuat tanda tangan asimetris, perlu diingat bahwa kunci Cloud KMS dibatasi untuk menggunakan satu ringkasan. Misalnya, CryptoKeyVersion dengan algoritma EC_SIGN_P256_SHA256 harus selalu digunakan bersama dengan ringkasan SHA-256. Hal ini sesuai dengan flag -sha256 di OpenSSL. Kunci yang memerlukan ringkasan SHA-384 atau SHA-512 harus digunakan dengan flag -sha384 atau -sha512.

Catatan: Saat membuat tanda tangan asimetris menggunakan kunci Cloud KMS dengan algoritma yang dimulai dengan RSA_PSS, opsi tambahan biasanya diperlukan oleh OpenSSL: -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest.

Membuat tanda tangan baru

Dengan asumsi ada kunci bernama foo di key ring yang dikonfigurasi, gunakan perintah berikut untuk membuat tanda tangan di bar.txt:

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

Output perintah ini adalah biner yang tidak diformat.

Perintah tersebut mengasumsikan bahwa Anda menggunakan kunci yang menggunakan ringkasan SHA-256, sehingga argumen -sha256 digunakan. Opsi -sha384 atau -sha512 akan sesuai untuk kunci Cloud HSM yang menggunakan jenis ringkasan tersebut.

Untuk kunci RSA-PSS, jangan lupa untuk menggunakan opsi -sigopt yang telah dibahas sebelumnya.

Membuat permintaan penandatanganan sertifikat baru

Anda juga dapat membuat permintaan penandatanganan sertifikat (CSR) untuk kunci penandatanganan Cloud HSM. Hal ini berguna jika otoritas sertifikat Anda memerlukan CSR untuk membuat sertifikat baru untuk penandatanganan kode, atau untuk melindungi sesi web TLS.

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

Catatan: Hanya buat CSR untuk CryptoKey Cloud KMS dengan tujuan ASYMMETRIC_SIGN. Selain itu, pastikan untuk menggunakan algoritma ringkasan dan opsi -sigopt yang benar untuk jenis kunci.

Membuat sertifikat yang ditandatangani sendiri baru

Untuk pengembangan dan pengujian lokal, Anda dapat menggunakan sertifikat yang ditandatangani sendiri untuk kunci penandatanganan Cloud HSM. Sertifikat yang ditandatangani sendiri juga berguna untuk penandatanganan token SAML.

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

Catatan: Sertifikat yang ditandatangani sendiri untuk Cloud KMS CryptoKey hanya digunakan untuk tujuan ASYMMETRIC_SIGN. Selain itu, berhati-hatilah untuk menggunakan algoritma ringkasan dan opsi -sigopt yang benar untuk jenis kunci.

Memecahkan masalah dengan PKCS #11 Spy

PKCS #11 Spy adalah alat open source yang mencatat konten interaksi melalui antarmuka PKCS #11. Library ini melakukannya dengan berada di antara aplikasi dan library PKCS #11, serta mencatat semua panggilan yang dilakukan. Hal ini dapat membantu pemecahan masalah.

Perhatian: Jangan gunakan PKCS #11 Spy dengan workload sensitif. Jika dikonfigurasi, PKCS #11 Spy dapat mengamati semua interaksi dengan HSM.

Untuk menggunakan PKCS #11 Spy, Anda harus menginstal paket opensc. Paket opensc berisi Spy PKCS #11. Untuk memastikan opensc diinstal, jalankan perintah berikut:

sudo apt-get install opensc

Kemudian, tetapkan variabel lingkungan PKCS11_MODULE_PATH untuk mengarahkan OpenSSL ke library Spy PKCS #11 dengan menjalankan perintah berikut:

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

Terakhir, arahkan PKCS #11 Spy ke library PKCS #11 Cloud HSM dengan menetapkan variabel lingkungan PKCS11SPY dan PKCS11SPY_OUTPUT. Untuk menetapkan variabel lingkungan ini, jalankan perintah berikut:

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