MariaDB 10.6自定义加密插件安装API版本不兼容问题

问题 #

编译生成JISA_Enc_Plugin.so共享库后，执行安装命令：

INSTALL PLUGIN JISA_Encryption_Plugin SONAME 'JISA_Enc_Plugin.so';

触发错误：

ERROR 1126 (HY000): Can't open shared library 'JISA_Enc_Plugin.so' (errno: 8, API version for ENCRYPTION plugin JISA_Encryption_Plugin not supported by this version of the server)

原因 #

MariaDB 10.6的加密插件接口与代码中实现的结构不匹配，核心问题有两点：

1. 插件结构成员缺失：当前代码仅实现加密逻辑，但MariaDB 10.6要求st_mariadb_encryption结构必须包含解密相关函数指针。
2. 接口版本不匹配：编译时使用的插件接口版本常量或头文件与MariaDB 10.6不对应。

解决步骤 #

1. 补充解密逻辑函数 #

代码中缺少解密对应的上下文操作函数，这是API版本不兼容的核心原因，添加以下函数：

// 解密上下文初始化
int decrypt_ctx_init(void *ctx, const unsigned char *key, unsigned int klen,
                     const unsigned char *iv, unsigned int ivlen, int flags,
                     unsigned int key_id, unsigned int key_version) {
   EVP_CIPHER_CTX *context = (EVP_CIPHER_CTX *)ctx;
   const EVP_CIPHER *cipher;

   switch (mode(flags)) {
       case MY_AES_CBC:
           cipher = EVP_aes_256_cbc();
           break;
       case MY_AES_CTR:
           cipher = EVP_aes_256_ctr();
           break;
       default:
           return -1;
   }

   EVP_CIPHER_CTX_init(context);
   if (EVP_DecryptInit_ex(context, cipher, NULL, key, iv) != 1) {
       return -1;
   }

   return 0;
}

// 解密上下文更新
int decrypt_ctx_update(void *ctx, const unsigned char *src, unsigned int slen,
                       unsigned char *dst, unsigned int *dlen) {
   EVP_CIPHER_CTX *context = (EVP_CIPHER_CTX *)ctx;
   int len;

   if (EVP_DecryptUpdate(context, dst, &len, src, slen) != 1) {
       return -1;
   }

   *dlen = len;
   return 0;
}

// 解密上下文完成
int decrypt_ctx_finish(void *ctx, unsigned char *dst, unsigned int *dlen) {
   EVP_CIPHER_CTX *context = (EVP_CIPHER_CTX *)ctx;
   int len;

   if (EVP_DecryptFinal_ex(context, dst, &len) != 1) {
       return -1;
   }

   *dlen = len;
   EVP_CIPHER_CTX_cleanup(context);
   return 0;
}

2. 更新加密插件结构定义 #

修改st_mariadb_encryption实例，补充解密函数指针及预留成员，确保结构与MariaDB 10.6头文件定义完全一致：

struct st_mariadb_encryption JISA_Enc_plugin = {
   MARIA_PLUGIN_INTERFACE_VERSION,
   get_latest_key_version,
   get_key,
   crypt_ctx_size,
   crypt_ctx_init,
   crypt_ctx_update,
   crypt_ctx_finish,
   decrypt_ctx_init,  // 新增解密初始化函数
   decrypt_ctx_update, // 新增解密更新函数
   decrypt_ctx_finish, // 新增解密完成函数
   encrypted_length,
   NULL, // 预留成员1
   NULL  // 预留成员2
};

3. 确保编译环境匹配 #

• 必须使用MariaDB 10.6的开发头文件和库文件编译，避免混用其他版本的mysql/plugin_encryption.h。
• 编译命令示例（替换路径为你的MariaDB 10.6安装路径）：

g++ -fPIC -shared -o JISA_Enc_Plugin.so your_plugin_code.cpp \
-I/usr/include/mariadb/server \
-L/usr/lib/mariadb/plugin \
-lmariadbclient -lcrypto -lcurl

4. 验证插件安装 #

将编译后的.so文件放到MariaDB插件目录（可通过SHOW VARIABLES LIKE 'plugin_dir';查询路径），重新执行安装命令即可。

额外检查点 #

• 确认代码中HAVE_EncryptAes128Ctr等宏在MariaDB 10.6头文件中已定义，避免条件编译导致功能缺失。
• 对比mysql/plugin_encryption.h中的st_mariadb_encryption结构，确保代码中成员顺序、数量完全一致，这是API版本匹配的关键。

内容的提问来源于stack exchange，提问作者Ankit