Menggunakan kunci Cloud HSM dengan OpenSSL

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

Persyaratan

Download rilis library untuk memulai. Untuk 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 kami, 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 setidaknya harus mengonfigurasi satu token PKCS #11.

Jika Anda menggunakan OpenSSL dengan proses lain yang mungkin melakukan fork (misalnya, Apache atau Nginx), Anda juga harus memastikan kolom refresh_interval_secs tidak disetel, atau disetel 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 sehingga file 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 tersebut dalam perintah OpenSSL.

Saat membuat tanda tangan asimetris, perhatikan bahwa kunci Cloud KMS dibatasi untuk menggunakan satu ringkasan. Sebagai contoh, BigtableVersion 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 algoritme yang dimulai dengan RSA_PSS, opsi tambahan biasanya diperlukan oleh OpenSSL: -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest.

Buat tanda tangan baru

Dengan asumsi ada kunci bernama foo dalam key ring yang dikonfigurasi, gunakan perintah berikut untuk membuat tanda tangan melalui 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 digest 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 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 certificate authority Anda memerlukan CSR agar dapat 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 Cloud KMS Bigtable dengan tujuan ASYMMETRIC_SIGN. Selain itu, pastikan untuk menggunakan algoritma ringkasan dan opsi -sigopt yang benar untuk jenis kunci.

Membuat sertifikat baru yang ditandatangani sendiri

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 Bigtable hanya digunakan untuk tujuan ASYMMETRIC_SIGN. Selain itu, berhati-hatilah dalam menggunakan algoritma ringkasan dan opsi -sigopt yang benar untuk jenis kunci.

Memecahkan masalah dengan Spy PKCS #11

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

Perhatian: Jangan gunakan PKCS #11 Spy dengan beban kerja yang sensitif. Saat dikonfigurasi, Spy PKCS #11 dapat mengamati semua interaksi dengan HSM.

Untuk menggunakan Spy PKCS #11, Anda harus menginstal paket opensc. Paket opensc berisi Spy PKCS #11. Untuk memastikan bahwa opensc sudah terinstal, 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 Cloud HSM PKCS #11 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"