Verifikasi Hostname TLS di PHP - Enkripsi Bukan Identitas Endpoint
Sebuah request HTTPS bisa terenkripsi tetapi tetap mencapai endpoint yang salah jika client tidak memverifikasi siapa yang berada di ujung koneksi. Ini terdengar bertentangan hanya karena frasa “TLS sudah aktif” merangkum beberapa pemeriksaan berbeda menjadi satu. Bagi aplikasi PHP yang memanggil API, mengunduh feed, atau mengirim webhook, pertanyaan yang berguna bukan sekadar apakah koneksinya memakai enkripsi. Pertanyaannya adalah: server mana yang diautentikasi oleh client?
Perbedaan ini penting ketika muncul error sertifikat dan solusi yang menggoda adalah mematikan verifikasi. Request mungkin mulai berhasil, tetapi kegagalannya tidak benar-benar diperbaiki; client hanya berhenti mengajukan sebuah pertanyaan penting. Artikel ini memisahkan pemeriksaan yang terlibat, memetakannya ke opsi PHP cURL dan stream, serta sengaja menjaga kesimpulannya tetap terbatas. Koneksi TLS yang valid mengautentikasi identitas layanan berdasarkan model trust yang dikonfigurasi. Hal itu tidak membuktikan bahwa layanan tersebut jujur, aplikasinya aman, atau responsnya aman digunakan.
Enkripsi, trust sertifikat, dan identitas layanan adalah pemeriksaan yang berbeda
TLS yang dikonfigurasi dengan benar dapat menyediakan kerahasiaan, integritas, dan autentikasi server, seperti dirangkum dalam OWASP Transport Layer Security Cheat Sheet. Sifat-sifat tersebut bergantung pada lebih dari sekadar keberhasilan membuat channel terenkripsi. Untuk HTTPS berbasis sertifikat yang umum, client memerlukan setidaknya dua jawaban yang saling berkaitan tetapi berbeda:
- Apakah sertifikat ini dapat divalidasi sampai ke trust anchor yang diterima client? Ini adalah verifikasi certification path atau peer. Pemeriksaan ini menilai rantai tanda tangan, kondisi validitas, dan trust CA yang dikonfigurasi pada client.
- Apakah sertifikat tersebut mengidentifikasi layanan yang memang ingin dihubungi client? Ini adalah verifikasi identitas layanan atau hostname. Pemeriksaan ini membandingkan identifier yang diharapkan dengan identifier yang disajikan dalam sertifikat server.
Rantai yang dipercaya tanpa nama yang cocok belum cukup. Sertifikat untuk files.example.net tidak semestinya mengautentikasi billing.example.com hanya karena keduanya berakhir pada CA tepercaya. Kebalikannya juga belum lengkap: nama yang cocok dalam sertifikat tidak membantu jika client tidak dapat memastikan bahwa sertifikat tersebut merupakan bagian dari certification path yang dipercaya.
RFC 9525 saat ini menyebut identitas yang diharapkan client sebagai reference identifier dan identitas yang dibawa sertifikat sebagai presented identifier. Untuk request biasa ke https://api.example.com/, URL umumnya menyediakan reference DNS name api.example.com. Client kemudian mencari identifier yang diizinkan dan cocok di dalam sertifikat.
Nama dalam URL menjadi bagian dari keputusan keamanan
Untuk nama DNS, RFC 9525 menetapkan identifier di extension subjectAltName milik sertifikat dan menyatakan agar field Common Name yang bebas format tidak dipakai untuk mengidentifikasi layanan. Pencocokan tidak membedakan huruf besar-kecil untuk label DNS ASCII biasa. Wildcard, jika didukung, dibatasi sebagai keseluruhan label paling kiri dan hanya cocok dengan satu label. Jadi, *.example.com dapat cocok dengan api.example.com, tetapi tidak cocok dengan v1.api.example.com.
IP literal adalah tipe identifier yang berbeda. Jika kode meminta https://192.0.2.10/, reference identity-nya adalah alamat IP tersebut. RFC 9525 mewajibkan pencocokan persis dengan entri iPAddress di subjectAltName. Sertifikat yang hanya memuat nama DNS api.example.com tidak otomatis cocok hanya karena DNS saat ini memetakan nama tersebut ke 192.0.2.10.
Inilah salah satu alasan mengganti hostname dengan alamat IP untuk “mengakali DNS” sering menghasilkan error sertifikat. Error itu bisa saja tepat: client meminta autentikasi untuk alamat IP yang tidak pernah diklaim oleh sertifikat. Perbaikan yang masuk akal adalah memulihkan hostname yang dimaksud, atau menerbitkan sertifikat dengan identifier IP yang diperlukan ketika identitas berbasis IP memang dibutuhkan. Mematikan pemeriksaan nama mengubah keputusan trust, bukan memperbaikinya.
Apa yang sebenarnya dikendalikan oleh dua opsi cURL
Extension cURL PHP mengekspos dua kontrol verifikasi utama libcurl. Namanya yang mirip membuat keduanya mudah dianggap sebagai satu switch, tetapi dokumentasi verifikasi peer libcurl dan dokumentasi verifikasi host menjelaskan dua tugas berbeda:
CURLOPT_SSL_VERIFYPEERmemeriksa apakah sertifikat peer dapat diautentikasi melalui trust CA yang dikonfigurasi. Default libcurl adalah aktif.CURLOPT_SSL_VERIFYHOSTmemeriksa apakah identitas sertifikat cocok dengan hostname atau alamat dalam URL. Nilai ketat sekaligus default libcurl adalah2.
Kode modern sebaiknya membiarkan kedua pemeriksaan tetap aktif. Kebijakan itu dapat dibuat eksplisit ketika options array bersama, framework, atau refactor mendatang mungkin membuatnya tidak terlihat jelas:
<?php
$url = 'https://api.example.com/v1/status';
$handle = curl_init($url);
if ($handle === false) {
throw new RuntimeException('Unable to initialize cURL');
}
$optionsSet = curl_setopt_array($handle, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
]);
if (!$optionsSet) {
throw new RuntimeException('Unable to configure cURL');
}
$body = curl_exec($handle);
if ($body === false) {
throw new RuntimeException('HTTPS request failed: ' . curl_error($handle));
}
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
Contoh ini sengaja belum lengkap sebagai API client: kode tersebut belum menentukan status code mana yang dapat diterima, memvalidasi content type, membatasi ukuran respons, atau memeriksa schema. Semua itu adalah kontrol aplikasi yang terpisah. Pengaturan TLS di atas hanya menjawab apakah cURL dapat membuat koneksi terautentikasi berdasarkan konfigurasi trust saat ini.
Pengaturan eksplisit tidak otomatis lebih aman daripada default. Sebuah wrapper dapat menimpanya kemudian, dan sumber CA yang sebenarnya bergantung pada bagaimana curl serta TLS backend-nya dibangun. Panduan verifikasi sertifikat curl mendokumentasikan perilaku CA store yang berbeda menurut platform. Tinjau opsi akhir dan environment deployment, alih-alih menganggap kemunculan dua konstanta dalam satu file sudah membuktikan kebijakan runtime.
PHP stream memiliki model dua bagian yang sama
Layer stream PHP memakai nama berbeda untuk pemisahan konsep yang sama. Menurut dokumentasi SSL context PHP, verify_peer dan verify_peer_name sama-sama memiliki default true. Jika peer_name tidak diberikan, PHP menyimpulkannya dari hostname yang dipakai untuk membuka stream.
<?php
$context = stream_context_create([
'http' => [
'timeout' => 15,
'ignore_errors' => true,
],
'ssl' => [
'verify_peer' => true,
'verify_peer_name' => true,
],
]);
$body = file_get_contents(
'https://api.example.com/v1/status',
false,
$context
);
if ($body === false) {
throw new RuntimeException('HTTPS stream request failed');
}
Sekali lagi, contoh ini menunjukkan kebijakan koneksi, bukan abstraksi HTTP yang lengkap. Penanganan error untuk stream dapat memerlukan pemeriksaan warning atau penggunaan library yang mengekspos kegagalan dengan lebih jelas. Poin penting dalam review adalah memastikan verify_peer_name tidak diam-diam berubah menjadi false ketika kode berpindah antara development dan production.
Private CA adalah persoalan konfigurasi trust, bukan alasan melewati pemeriksaan
Layanan internal lazim memakai sertifikat yang tidak dikenali CA store publik. Itu tidak berarti verifikasi ketat mustahil dilakukan. Artinya, client memerlukan private trust anchor yang sesuai. curl dapat menerima CA bundle melalui CURLOPT_CAINFO (atau direktori CA yang sesuai melalui CURLOPT_CAPATH), sedangkan PHP stream menyediakan cafile dan capath.
curl_setopt_array($handle, [
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_CAINFO => '/etc/ssl/local-ca.pem',
]);
File pada contoh ini adalah input trust, sehingga asal, isi, kepemilikan, permission, dan proses pembaruannya penting. Mengunduh sertifikat apa pun yang kebetulan diberikan server lalu langsung mempercayainya akan menghapus perbedaan antara observasi dan trust. Private CA seharusnya didistribusikan melalui channel yang terkontrol, dan leaf certificate tetap memerlukan identifier yang cocok dengan nama layanan.
Leaf certificate self-signed dapat dipercaya secara eksplisit dalam sistem yang dikontrol ketat, tetapi itu adalah model trust berbeda dengan biaya provisioning dan rotasinya sendiri. Label “self-signed” tidak otomatis membuat sertifikat dapat diterima dan juga tidak menjelaskan bagaimana client memperoleh salinan yang tepercaya. Untuk banyak layanan internal, private CA kecil lebih mudah dikelola daripada melakukan pinning untuk setiap leaf certificate secara terpisah, tetapi pilihan yang tepat bergantung pada sistemnya.
Redirect dan alamat koneksi alternatif perlu dijelaskan dengan hati-hati
Jika client mengikuti redirect dari satu host ke host lain, koneksi HTTPS yang baru harus mengautentikasi host pada URL baru. Sertifikat server awal tidak menjamin redirect target yang tidak berkaitan. Kebijakan redirect juga memiliki persoalan di luar TLS, termasuk apakah credential diteruskan dan apakah tujuan tersebut diizinkan. Verifikasi hostname diperlukan, tetapi bukan sebuah allowlist.
Beberapa client dapat terhubung ke satu alamat jaringan sambil mempertahankan hostname URL yang berbeda. Ini dapat berguna untuk pengujian, service discovery, atau routing tanpa DNS, tetapi reference identity yang sensitif terhadap keamanan seharusnya tetap merupakan nama layanan yang dituju. Server Name Indication (SNI) dapat membantu server multi-tenant memilih sertifikat yang benar; SNI sendiri tidak memverifikasi sertifikat itu. Perilaku persisnya berbeda menurut client dan TLS backend, jadi gunakan fitur connection override yang terdokumentasi alih-alih sembarangan menulis ulang URL.
Kegagalan adalah informasi, bukan hambatan yang harus ditekan
RFC 9525 menyatakan bahwa aplikasi otomatis sebaiknya menghentikan upaya dengan bad-certificate error dan mencatat error ketika tidak ada presented identifier yang cocok dengan reference identifier. Pilihan katanya memberi ruang bagi konfigurasi eksplisit, tetapi verifikasi tidak boleh dimatikan secara default. Ini adalah prinsip operasional yang berguna: perlakukan kegagalan sebagai bukti yang perlu didiagnosis.
Investigasi praktis dapat menanyakan:
- Hostname atau alamat IP persis apa yang muncul pada URL akhir?
- DNS-ID atau IP-ID mana yang disajikan leaf certificate?
- CA store mana yang dipakai oleh build PHP/curl ini?
- Apakah server mengirim intermediate certificate yang diperlukan?
- Apakah proxy, redirect, container image, atau opsi khusus environment mengubah jalurnya?
- Apakah kode aplikasi menimpa verifikasi setelah default bersama diterapkan?
Logging sebaiknya menyimpan kategori error dan tujuan tanpa membocorkan credential, request body, atau query string sensitif. “Certificate verification failed” memang kurang nyaman dibanding request yang berhasil, tetapi lebih jujur daripada diam-diam mengubah client dari TLS terautentikasi menjadi enkripsi tanpa identitas endpoint yang dapat diandalkan.
Apa yang tetap tidak dibuktikan oleh verifikasi yang berhasil
Keberhasilan verifikasi path dan nama mendukung pernyataan yang terbatas: endpoint membuktikan kontrol atas private key yang sesuai dengan sertifikat valid untuk identitas layanan yang diharapkan, berdasarkan trust anchor dan aturan verifikasi yang diterima client. Hal itu tidak membuktikan siapa yang menulis aplikasi, apakah suatu akun berwenang, apakah server telah dikompromikan, atau apakah JSON yang dikembalikan benar secara makna.
Batasan ini bukan kelemahan verifikasi hostname; itulah batas yang semestinya. Autentikasi aplikasi, authorization, validasi respons, kontrol SSRF, kebijakan redirect, timeout, dan business rule tetap memiliki tugas masing-masing. Keamanan lebih mudah dipahami ketika setiap kontrol hanya membuat klaim yang memang mampu didukungnya.
Kesimpulan
“Gunakan HTTPS” adalah titik awal, bukan kebijakan client yang lengkap. Client PHP memerlukan certification path yang dipercaya dan identitas layanan yang cocok. cURL mengekspresikan pemeriksaan tersebut melalui CURLOPT_SSL_VERIFYPEER dan CURLOPT_SSL_VERIFYHOST; PHP stream memakai verify_peer dan verify_peer_name. Default amannya layak dipertahankan, sedangkan infrastruktur private seharusnya menambahkan trust anchor yang benar, bukan menghapus pemeriksaan.
Ketika error sertifikat berikutnya menghalangi outbound request, pertanyaan yang paling berguna mungkin adalah: klaim mana yang gagal—rantai trust, nama yang diharapkan, atau konfigurasi yang menghubungkan keduanya? Menjawabnya memang lebih lama daripada mengubah opsi menjadi false, tetapi cara itu memperbaiki model trust alih-alih menyembunyikan peringatan.
References
- RFC 9525: Service Identity in TLS — IETF / RFC Editor, November 2023.
- TLS Certificate Verification — curl project documentation.
- CURLOPT_SSL_VERIFYHOST explained — libcurl documentation.
- CURLOPT_SSL_VERIFYPEER explained — libcurl documentation.
- SSL context options — PHP Manual.
- Transport Layer Security Cheat Sheet — OWASP Cheat Sheet Series.
