全部产品
Search

搜索本产品

    Database Autonomy Service：Integrasi EncJDBC untuk enkripsi kolom

    文档中心

    Database Autonomy Service：Integrasi EncJDBC untuk enkripsi kolom

    更新时间：Aug 05, 2025

    Alibaba Cloud menyediakan EncJDBC, sebuah driver pembungkus JDBC yang menyederhanakan enkripsi sisi klien untuk aplikasi Java. Driver ini mendekripsi ciphertext secara transparan di latar belakang, membutuhkan perubahan minimal pada kode JDBC yang sudah ada. Panduan ini menjelaskan cara mengintegrasikan EncJDBC ke dalam proyek Maven Anda, mengonfigurasi koneksi database yang aman, dan menanyakan data.

    Driver EncJDBC menggunakan Master Encryption Key (MEK) untuk membangun koneksi terenkripsi yang aman dari ujung ke ujung. Klien secara otomatis mendekripsi dan mengembalikan data teks biasa, sehingga kode Anda dapat berinteraksi dengan data sensitif seolah-olah itu adalah teks biasa, hanya dengan perubahan minimal pada pengaturan koneksi.

    Prasyarat

    Sebelum memulai, pastikan pengaturan berikut telah dilakukan:

    • Anda telah menjalankan pemindaian deteksi data sensitif untuk mengidentifikasi kolom yang ingin dienkripsi. Untuk informasi lebih lanjut, lihat Deteksi Data Sensitif.

    • Anda telah mengaktifkan enkripsi kolom untuk database tujuan dan memberikan Ciphertext Permission (JDBC Decryption) kepada akun database tujuan. Untuk informasi lebih lanjut, lihat Enkripsi Kolom.

    • Informasi koneksi tentang instans RDS dengan fitur basis data selalu rahasia diaktifkan telah diperoleh. Informasi tersebut mencakup nama domain (host), nomor port (port), nama instans (dbname), nama pengguna (username), dan kata sandi (password).

    Hasilkan MEK

    MEK adalah kredensial root yang mengotorisasi aplikasi klien untuk mengakses data terenkripsi. Berikut cara kerjanya:

    Klien mentransmisikan kunci ke server database melalui protokol enkripsi kunci asimetris yang aman. Proses ini memungkinkan server dan klien berbagi kunci yang sama sehingga data dapat ditransmisikan secara aman menggunakan enkripsi simetris.

    Nilainya harus berupa string heksadesimal 32 karakter, mewakili 16 byte data.

    Peringatan

    MEK adalah kredensial root yang digunakan untuk mengotorisasi klien agar dapat mengakses data terenkripsi. Untuk memastikan keamanan, fitur basis data selalu rahasia tidak menghasilkan, menyimpan, atau mencadangkan MEK Anda. Anda harus menghasilkan MEK secara manual dan memastikan bahwa MEK disimpan dengan aman. Kami merekomendasikan pencadangan MEK untuk memastikan keamanan basis data yang memiliki fitur basis data selalu rahasia diaktifkan.

    Dalam konfigurasi enkripsi kolom untuk database, pilih Encryption Method, kemudian pilih KMS Key atau hasilkan Local Key sebagai Master Encryption Key (MEK) untuk mendekripsi database.

    Kunci KMS

    Penting

    Pastikan layanan KMS tersedia. Jika tidak, EncJDBC tidak dapat digunakan.

    Anda harus memperoleh titik akhir instans KMS tempat Kunci KMS tertentu milik, serta ID AccessKey dan Rahasia AccessKey dari akun Alibaba Cloud atau Pengguna RAM yang memiliki izin dekripsi KMS. Dengan cara ini, klien dapat membaca kunci KMS. Langkah-langkahnya adalah sebagai berikut:

    1. Masuk ke Konsol Manajemen Alibaba Cloud menggunakan Akun Alibaba Cloud atau Pengguna RAM.

    2. Jika Anda menggunakan Pengguna RAM, berikan izin dekripsi KMS kepada Pengguna RAM tersebut.

      1. Buat kebijakan kustom. Untuk informasi lebih lanjut, lihat Buat Kebijakan Kustom. Contoh isi kebijakan:

        {
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "KMS:Decrypt",
            "Resource": "*"
        }
    ]
}

      2. Lampirkan kebijakan kustom ke Pengguna RAM yang ditentukan. Untuk informasi lebih lanjut, lihat Berikan Izin kepada Pengguna RAM.

    3. Peroleh Titik Akhir Instans KMS.

      • Secara default, kunci dalam instans KMS hanya dapat diakses dari jaringan virtual private cloud (VPC). Untuk melihat titik akhir VPC dari instans KMS: Pergi ke Konsol KMS. Di halaman Instans, temukan instans KMS yang diperlukan dan klik Details di kolom Actions. Di tab Instance, lihat bidang Titik Akhir VPC Instans.

        image

      • Untuk mengakses kunci melalui Internet, pergi ke tab Share Resources, aktifkan Status Akses Internet, dan lihat bidang Public Endpoint.

        image

    4. Peroleh Pasangan AccessKey.

      Saat membuat Pasangan AccessKey untuk akun Alibaba Cloud atau Pengguna RAM, simpan ID AccessKey dan Rahasia AccessKey. Untuk informasi lebih lanjut, lihat Buat AccessKey.

    Kunci lokal

    Jika Anda mengatur parameter Encryption Method ke Local Key, Anda harus menghasilkan MEK. Contoh: 00112233445566778899aabbccddeeff.

    Anda dapat menggunakan generator kata sandi atau fungsi random() yang disediakan oleh bahasa pemrograman untuk menghasilkan MEK.

    Contoh:

    Konfigurasikan klien

    Penting

    Gunakan JDK 1.8 atau versi lebih baru.

    Di sisi klien, ubah driver koneksi database menjadi EncJDBC, perbarui URL koneksi database, dan tentukan MEK untuk mengakses data teks biasa dari kolom terenkripsi di database yang diperlukan.

    1. Tambahkan dependensi

    Tambahkan dependensi berikut ke file pom.xml proyek Anda di Maven.

    <dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-cls-jdbc</artifactId>
    <version>1.0.10-1</version>
</dependency>

    2. Konfigurasikan MEK untuk terhubung ke database

    Anda dapat menggunakan metode berikut untuk mengonfigurasi MEK: Konfigurasi properti JDBC, file konfigurasi, dan konfigurasi URL. Jika Anda ingin menggunakan lebih dari satu metode, prioritasnya adalah sebagai berikut: Konfigurasi properti JDBC, file konfigurasi, dan konfigurasi URL.

    Catatan

    • Jika menggunakan metode konfigurasi URL, gunakan ampersand (&) untuk menggabungkan beberapa parameter.

    • Dalam metode berikut, MEK dikonfigurasi pada klien lokal dan didistribusikan ke server menggunakan enkripsi amplop untuk memastikan bahwa MEK tidak bocor.

    Gunakan kunci KMS atau kunci lokal berdasarkan metode enkripsi yang Anda tentukan selama konfigurasi enkripsi.

    Kunci KMS

    Penting

    • Jika menggunakan kredensial akses sementara yang disediakan oleh Layanan Token Keamanan (STS) untuk mendapatkan MEK yang dikelola KMS, gunakan SDK STS untuk mendapatkan token STS sementara. Untuk informasi lebih lanjut, lihat Ikhtisar SDK STS.

    • Jangan mengkodekan pasangan AccessKey dalam kode bisnis. Contoh ini menjelaskan cara mengonfigurasi variabel lingkungan sistem untuk mengelola pasangan AccessKey. Untuk informasi lebih lanjut, lihat Konfigurasikan Variabel Lingkungan di Linux, macOS, dan Windows.

    Konfigurasi properti JDBC

    Saat terhubung ke instans dari JDBC standar, konfigurasikan pengaturan Properties. Contoh kode:

    // Perbarui informasi koneksi seperti titik akhir (hostname), nomor port (port), nama instans (dbname), nama pengguna (username), dan kata sandi (password) berdasarkan skenario aktual.
// ...

String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";

// Dapatkan ID AccessKey dan Rahasia AccessKey dari variabel lingkungan.
String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// Jika Anda menggunakan kredensial akses sementara STS untuk membaca kunci KMS, Anda juga perlu mengisi token keamanan STS (SecurityToken) yang diperoleh.
// String stsToken= "yourSecurityToken";

// Titik akhir instans KMS, gunakan titik akhir publik untuk akses jaringan publik. Untuk akses jaringan VPC, gunakan titik akhir VPC instans.
String kmsEndpoint = "kms.cn-hangzhou.aliyuncs.com";

Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("ALIBABA_CLOUD_ACCESS_KEY_ID", accessKeyId);
props.setProperty("ALIBABA_CLOUD_ACCESS_KEY_SECRET", accessKeySecret);
props.setProperty("ALIBABA_CLOUD_KMS_ENDPOINT", kmsEndpoint);
// props.setProperty("ALIBABA_CLOUD_STS_TOKEN","stsToken");



// Format URL koneksi untuk database MySQL "jdbc:mysql:encdb://%s:%s/%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);

// Muat driver EncJDBC untuk database MySQL.
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// Dapatkan koneksi database.
Connection connection = DriverManager.getConnection(dbUrl, props);

// ... Mulai kueri ...
    Konfigurasi URL

    Anda dapat menentukan MEK dalam URL. Contoh kode:

    // Perbarui informasi koneksi seperti titik akhir (hostname), nomor port (port), nama instans (dbname), nama pengguna (username), dan kata sandi (password) berdasarkan skenario aktual.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";

// Dapatkan ID AccessKey dan Rahasia AccessKey dari variabel lingkungan.
String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// Jika Anda menggunakan kredensial akses sementara STS untuk membaca kunci KMS, Anda juga perlu mengisi token keamanan STS (SecurityToken) yang diperoleh.
// String stsToken= "yourSecurityToken";

// Titik akhir instans KMS, gunakan titik akhir publik untuk akses jaringan publik. Untuk akses jaringan VPC, gunakan titik akhir VPC instans.
String kmsEndpoint = "kms.cn-hangzhou.aliyuncs.com";

// Format URL koneksi untuk database MySQL.
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?ALIBABA_CLOUD_ACCESS_KEY_ID=%s&ALIBABA_CLOUD_ACCESS_KEY_SECRET=%s&ALIBABA_CLOUD_KMS_ENDPOINT=%s", hostname, port, dbname, accessKeyId,accessKeySecret,kmsEndpoint);
// Gunakan Token STS.
// String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?ALIBABA_CLOUD_ACCESS_KEY_ID=%s&ALIBABA_CLOUD_ACCESS_KEY_SECRET=%s&ALIBABA_CLOUD_KMS_ENDPOINT=%s&ALIBABA_CLOUD_STS_TOKEN=%s", hostname, port, dbname, accessKeyId,accessKeySecret,kmsEndpoint,stsToken);

// Muat driver EncJDBC untuk database MySQL.
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// Dapatkan koneksi database.
Connection connection = DriverManager.getConnection(dbUrl, username, password);

// ... Mulai kueri ...

    Kunci lokal

    Konfigurasi properti JDBC

    JDBC standar dapat mengatur properti yang ditentukan pengguna melalui Properties saat terhubung. Berikut adalah contoh konfigurasi properti JDBC dan menjalankan JDBC dengan cara ini:

    // Siapkan informasi koneksi seperti alamat koneksi (hostname), port (port), nama instans basis data (dbname), nama pengguna (username), kata sandi (password), dll.
// ...

String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
// Kunci utama.
String mek = "00112233445566778899aabbccddeeff"; 

Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", mek);

// Berikut adalah format URL koneksi untuk database MySQL "jdbc:mysql:encdb://%s:%s/%s". Untuk database PostgreSQL, format URL koneksi perlu diganti dengan "jdbc:postgresql:encdb://%s:%s/%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);

// Berikut adalah memuat driver EncJDBC untuk database MySQL. Untuk database PostgreSQL, pemuatan driver EncJDBC harus diganti dengan "com.aliyun.encdb.postgresql.jdbc.EncDriver".
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// Dapatkan koneksi database.
Connection connection = DriverManager.getConnection(dbUrl, props);

// ... Mulai kueri ...
    Konfigurasi file

    Parameter dapat diimpor melalui file konfigurasi, mengonfigurasi MEK yang diperlukan dan parameter lainnya.

    Catatan

    Metode konfigurasi file hanya cocok untuk mengonfigurasi MEK kunci lokal.

    Atur property bernama encJdbcConfigFile di proyek Anda dan atur nilainya ke jalur file konfigurasi (secara default, ia menggunakan file encjdbc.conf). Isi file konfigurasi adalah sebagai berikut:

    MEK=00112233445566778899aabbccddeeff

    Anda dapat meletakkan file konfigurasi dengan dua cara berikut:

    • Letakkan file di direktori resources proyek Anda, seperti yang ditunjukkan di bawah ini:

      image

    • Letakkan file di direktori root proyek, yaitu direktori runtime program.

    Dengan metode konfigurasi file, setelah menyelesaikan konfigurasi file, Anda tidak perlu melakukan konfigurasi tambahan di program Anda, seperti yang ditunjukkan di bawah ini:

    // Siapkan informasi koneksi seperti alamat koneksi (hostname), port (port), nama instans basis data (dbname), nama pengguna (username), kata sandi (password), dll.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";

// Berikut adalah format URL koneksi untuk database MySQL "jdbc:mysql:encdb://%s:%s/%s". Untuk database PostgreSQL, format URL koneksi perlu diganti dengan "jdbc:postgresql:encdb://%s:%s/%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);

// Berikut adalah memuat driver EncJDBC untuk database MySQL. Untuk database PostgreSQL, pemuatan driver EncJDBC harus diganti dengan "com.aliyun.encdb.postgresql.jdbc.EncDriver".
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// Dapatkan koneksi database.
Connection connection = DriverManager.getConnection(dbUrl, username, password);

// ... Mulai kueri ...
    Konfigurasi URL

    Parameter seperti MEK dapat disematkan dalam tautan URL. Seperti yang ditunjukkan di bawah ini:

    // Siapkan informasi koneksi seperti alamat koneksi (hostname), port (port), nama instans basis data (dbname), nama pengguna (username), kata sandi (password), dll.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
 // Kunci utama.
String mek = "00112233445566778899aabbccddeeff";

// Berikut adalah format URL koneksi untuk database MySQL "jdbc:mysql:encdb://%s:%s/%s?MEK=%s". Untuk database PostgreSQL, format URL koneksi perlu diganti dengan "jdbc:postgresql:encdb://%s:%s/%s?MEK=%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?MEK=%s", hostname, port, dbname, mek);

// Berikut adalah memuat driver EncJDBC untuk database MySQL. Untuk database PostgreSQL, pemuatan driver EncJDBC harus diganti dengan "com.aliyun.encdb.postgresql.jdbc.EncDriver".
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");

// Dapatkan koneksi database.
Connection connection = DriverManager.getConnection(dbUrl, username, password);

// ... Mulai kueri ...

    3. Kueri data teks biasa dari kolom terenkripsi

    Setelah terhubung ke database yang diperlukan, Anda dapat menanyakan database dengan cara yang sama seperti dengan JDBC standar. EncJDBC secara otomatis mendekripsi kolom terenkripsi dan mengembalikan data teks biasa.

    Contoh kode:

    // Mulai kueri.

// Buat pernyataan kueri.
Statement statement = connection.createStatement();
ResultSet resultSet = statement.executeQuery("SELECT * FROM your_table_name");

// Telusuri set hasil.
while (resultSet.next()) {
    for (int i = 0; i < rs.getMetaData().getColumnCount(); i++) {
        System.out.print(rs.getString(i + 1));
        System.out.print("\t");
    }
    System.out.print("\n");
}

    FAQ

    • Apa yang harus saya lakukan jika pesan kesalahan Exception in thread "main" java.lang.IllegalAccessError: class com.alibaba.encdb.common.SymCrypto (in unnamed module @0x5c0369c4) cannot access class com.sun.crypto.provider.SunJCE (in module java.base) because module java.base does not export com.sun.crypto.provider to unnamed module @0x5c0369c4 ditampilkan saat menjalankan program?

      Pesan kesalahan ini mungkin muncul karena masalah izin antar-modul ketika versi JDK lebih baru dari versi yang diperlukan. Untuk menyelesaikan kesalahan, tambahkan opsi VM --add-exports=java.base/com.sun.crypto.provider=ALL-UNNAMED saat menjalankan program untuk mengekspor com.sun.crypto.provider ke modul Unnamed.

    • Apa yang harus saya lakukan jika pesan kesalahan failed in mek provision: you might have an incorrect mek setting. Detail:gcmEncrypt error ditampilkan saat menjalankan program?

      Kesalahan ini merupakan kesalahan umum di Oracle JDK. Untuk menyelesaikan kesalahan, gunakan salah satu metode berikut:

      • Gunakan Amazon Corretto sebagai gantinya.

      • Jika menggunakan Oracle JDK, lakukan langkah-langkah berikut untuk mengonfigurasi penyedia keamanan:

        1. Temukan jalur instalasi JDK.

        2. Di direktori Installation path/conf/security/, temukan file java.security.

        3. Edit file java.security. Di bagian Daftar penyedia dan urutan preferensi mereka (lihat di atas):, tambahkan konten berikut:

          security.provider.14=org.bouncycastle.jce.provider.BouncyCastleProvider