從零開始實現一個MyBatis加解密外掛

vivo網際網路技術發表於2022-08-23
MyBatis解密
作者：vivo 網際網路伺服器團隊- Li Gang

本篇文章介紹使用MyBatis外掛來實現資料庫欄位加解密的過程。

一、需求背景

公司出於安全合規的考慮，需要對明文儲存在資料庫中的部分欄位進行加密，防止未經授權的訪問以及個人資訊洩漏。

由於專案已停止迭代，改造的成本太大，因此我們選用了MyBatis外掛來實現資料庫加解密，保證往資料庫寫入資料時能對指定欄位加密，讀取資料時能對指定欄位解密。

二、思路解析

2.1 系統架構

  1. 對每個需要加密的欄位新增密文欄位（對業務有侵入），修改資料庫、mapper.xml以及DO物件，透過外掛的方式把針對明文/密文欄位的加解密進行收口。
  2. 自定義Executor對SELECT/UPDATE/INSERT/DELETE等操作的明文欄位進行加密並設定到密文欄位。
  3. 自定義外掛ResultSetHandler負責針對查詢結果進行解密，負責對SELECT等操作的密文欄位進行解密並設定到明文欄位。

2.2 系統流程

圖片

  1. 新增加解密流程控制開關，分別控制寫入時是隻寫原欄位/雙寫/只寫加密後的欄位，以及讀取時是讀原欄位還是加密後的欄位。
  2. 新增歷史資料加密任務，對歷史資料批次進行加密，寫入到加密後欄位。
  3. 出於安全上的考慮，流程裡還會有一些校驗/補償的任務，這裡不再贅述。

三、方案制定

3.1 MyBatis外掛簡介

MyBatis 預留了 org.apache.ibatis.plugin.Interceptor 介面，透過實現該介面，我們能對MyBatis的執行流程進行攔截，介面的定義如下:

public interface Interceptor {
  Object intercept(Invocation invocation) throws Throwable;
  Object plugin(Object target);
  void setProperties(Properties properties);
}

其中有三個方法:

  • 【intercept】：外掛執行的具體流程，傳入的Invocation是MyBatis對被代理的方法的封裝。
  • 【plugin】：使用當前的Interceptor建立代理，通常的實現都是 Plugin.wrap(target, this)，wrap方法內使用 jdk 建立動態代理物件。
  • 【setProperties】：參考下方程式碼，在MyBatis配置檔案中配置外掛時可以設定引數，在setProperties函式中呼叫 Properties.getProperty("param1") 方法可以得到配置的值。
<plugins>
    <plugin interceptor="com.xx.xx.xxxInterceptor">
        <property name="param1" value="value1"/>
    </plugin>
</plugins>

在實現intercept函式對MyBatis的執行流程進行攔截前，我們需要使用@Intercepts註解指定攔截的方法。

@Intercepts({ @Signature(type = Executor.class, method = "update", args = { MappedStatement.class, Object.class }),
        @Signature(type = Executor.class, method = "query", args = { MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class }) })

參考上方程式碼，我們可以指定需要攔截的類和方法。當然我們不能對任意的物件做攔截，MyBatis件可攔截的類為以下四個。

  1. Executor
  2. StatementHandler
  3. ParameterHandler
  4. ResultSetHandler

回到資料庫加密的需求，我們需要從上面四個類裡選擇能用來實現入參加密和出參解密的類。在介紹這四個類之前，需要對MyBatis的執行流程有一定的瞭解。

3.2 Spring-MyBatis執行流程

（1）Spring透過sqlSessionFactoryBean建立sqlSessionFactory，在使用sqlSessionFactoryBean時，我們通常會指定configLocation和mapperLocations，來告訴sqlSessionFactoryBean去哪裡讀取配置檔案以及去哪裡讀取mapper檔案。

（2）得到配置檔案和mapper檔案的位置後，分別呼叫XmlConfigBuilder.parse()和XmlMapperBuilder.parse()建立Configuration和MappedStatement，Configuration類顧名思義，存放的是MyBatis所有的配置，而MappedStatement類存放的是每條SQL語句的封裝，MappedStatement以map的形式存放到Configuration物件中，key為對應方法的全路徑。

（3）Spring透過ClassPathMapperScanner掃描所有的Mapper介面，為其建立BeanDefinition物件，但由於他們本質上都是沒有被實現的介面，所以Spring會將他們的BeanDefinition的beanClass屬性修改為MapperFactorybean。

（4）MapperFactoryBean也實現了FactoryBean介面，Spring在建立Bean時會呼叫FactoryBean.getObject()方法獲取Bean，最終是透過mapperProxyFactory的newInstance方法為mapper介面建立代理，建立代理的方式是JDK，最終生成的代理物件是MapperProxy。

（5）呼叫mapper的所有介面本質上呼叫的都是MapperProxy.invoke方法，內部呼叫sqlSession的insert/update/delete等各種方法。

MapperMethod.java
public Object execute(SqlSession sqlSession, Object[] args) {
  Object result;
  if (SqlCommandType.INSERT == command.getType()) {
    Object param = method.convertArgsToSqlCommandParam(args);
    result = rowCountResult(sqlSession.insert(command.getName(), param));
  } else if (SqlCommandType.UPDATE == command.getType()) {
    Object param = method.convertArgsToSqlCommandParam(args);
    result = rowCountResult(sqlSession.update(command.getName(), param));
  } else if (SqlCommandType.DELETE == command.getType()) {
    Object param = method.convertArgsToSqlCommandParam(args);
    result = rowCountResult(sqlSession.delete(command.getName(), param));
  } else if (SqlCommandType.SELECT == command.getType()) {
    if (method.returnsVoid() && method.hasResultHandler()) {
      executeWithResultHandler(sqlSession, args);
      result = null;
    } else if (method.returnsMany()) {
      result = executeForMany(sqlSession, args);
    } else if (method.returnsMap()) {
      result = executeForMap(sqlSession, args);
    } else {
      Object param = method.convertArgsToSqlCommandParam(args);
      result = sqlSession.selectOne(command.getName(), param);
    }
  } else if (SqlCommandType.FLUSH == command.getType()) {
      result = sqlSession.flushStatements();
  } else {
    throw new BindingException("Unknown execution method for: " + command.getName());
  }
  if (result == null && method.getReturnType().isPrimitive() && !method.returnsVoid()) {
    throw new BindingException("Mapper method '" + command.getName()
        + " attempted to return null from a method with a primitive return type (" + method.getReturnType() + ").");
  }
  return result;
}

（6）SqlSession可以理解為一次會話，SqlSession會從Configuration中獲取對應MappedStatement，交給Executor執行。

DefaultSqlSession.java
@Override
public <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds) {
  try {
    // 從configuration物件中使用被呼叫方法的全路徑，獲取對應的MappedStatement
    MappedStatement ms = configuration.getMappedStatement(statement);
    return executor.query(ms, wrapCollection(parameter), rowBounds, Executor.NO_RESULT_HANDLER);
  } catch (Exception e) {
    throw ExceptionFactory.wrapException("Error querying database.  Cause: " + e, e);
  } finally {
    ErrorContext.instance().reset();
  }
}

（7）Executor會先建立StatementHandler，StatementHandler可以理解為是一次語句的執行。

（8）然後Executor會獲取連線，具體獲取連線的方式取決於Datasource的實現，可以使用連線池等方式獲取連線。

（9）之後呼叫StatementHandler.prepare方法，對應到JDBC執行流程中的Connection.prepareStatement這一步。

（10）Executor再呼叫StatementHandler的parameterize方法，設定引數，對應到JDBC執行流程的StatementHandler.setXXX()設定引數，內部會建立ParameterHandler方法。

SimpleExecutor.java
@Override
public <E> List<E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException {
  Statement stmt = null;
  try {
    Configuration configuration = ms.getConfiguration();
    // 建立StatementHandler，對應第7步
    StatementHandler handler = configuration.newStatementHandler(wrapper, ms, parameter, rowBounds, resultHandler, boundSql);
    // 獲取連線，再呼叫conncetion.prepareStatement建立prepareStatement，設定引數
    stmt = prepareStatement(handler, ms.getStatementLog());
    // 執行prepareStatement
    return handler.<E>query(stmt, resultHandler);
  } finally {
    closeStatement(stmt);
  }
}

（11）再由ResultSetHandler處理返回結果，處理JDBC的返回值，將其轉換為Java的物件。

3.3 MyBatis外掛的建立時機

在Configuration類中，我們能看到newExecutor、newStatementHandler、newParameterHandler、newResultSetHandler這四個方法，外掛的代理類就是在這四個方法中建立的，我以StatementHandeler的建立為例：

Configuration.java
public StatementHandler newStatementHandler(Executor executor, MappedStatement mappedStatement, Object parameterObject, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
  StatementHandler statementHandler = new RoutingStatementHandler(executor, mappedStatement, parameterObject, rowBounds, resultHandler, boundSql);
  // 使用責任鏈的形式建立代理
  statementHandler = (StatementHandler) interceptorChain.pluginAll(statementHandler);
  return statementHandler;
}
 
InterceptorChain.java
public Object pluginAll(Object target) {
  for (Interceptor interceptor : interceptors) {
    target = interceptor.plugin(target);
  }
  return target;
}

interceptor.plugin對應到我們自己實現的interceptor裡的方法，通常的實現是 Plugin.wrap(target, this); ，該方法內部建立代理的方式為JDK。

3.4 MyBatis外掛可攔截類選擇

圖片

Mybatis本質上是對JDBC執行流程的封裝。結合上圖我們簡要概括下Mybatis這幾個可被代理類的職能。

  • 【Executor】: 真正執行SQL語句的物件，呼叫sqlSession的方法時，本質上都是呼叫executor的方法，還負責獲取connection，建立StatementHandler。
  • 【StatementHandler】: 建立並持有ParameterHandler和ResultSetHandler物件，操作JDBC的statement與進行資料庫操作。
  • 【ParameterHandler】: 處理入參，將Java方法上的引數設定到被執行語句中。
  • 【ResultSetHandler】: 處理SQL語句的執行結果，將返回值轉換為Java物件。

對於入參的加密，我們需要在ParameterHandler呼叫prepareStatement.setXXX()方法設定引數前，將引數值修改為加密後的引數，這樣一看好像攔截Executor/StatementHandler/ParameterHandler都可以。

但實際上呢？由於我們的並不是在原始欄位上做加密，而是新增了一個加密後欄位，這會帶來什麼問題？請看下面這條mapper.xml檔案中加了加密後欄位的動態SQL：

<select id="selectUserList" resultMap="BaseResultMap" parameterType="com.xxx.internet.demo.entity.UserInfo">
        SELECT
        *
        FROM
        `t_user_info`
        <where>
            <if test="phone != null">
                `phone` = #{phone}
            </if>
<!--            明文欄位-->
            <if test="secret != null">
                AND `secret` = #{secret}
            </if>
<!--            加密後欄位-->
            <if test="secretCiper != null">
                AND `secret_ciper` = #{secretCiper}
            </if>
            <if test="name">
                AND `name` = #{name}
            </if>
        </where>
        ORDER BY `update_time` DESC
    </select>

可以看到這條語句帶了動態標籤，那肯定不能直接交給JDBC建立prepareStatement，需要先將其解析成靜態SQL，而這一步是在Executor在呼叫StatementHandler.parameterize()前做的，由MappedStatementHandler.getBoundSql(Object parameterObject)函式解析動態標籤，生成靜態SQL語句，這裡的parameterObject我們可以暫時先將其看成一個Map，鍵值分別為引數名和引數值。

那麼我們來看下用StatementHandler和ParameterHandler做引數加密會有什麼問題，在執行MappedStatementHandler.getBoundSql時，parameterObject中並沒有寫入加密後的引數，在判斷標籤時必定為否，最後生成的靜態SQL必然不包含加密後的欄位，後續不管我們在StatementHandler和ParameterHandler中怎麼處理parameterObject，都無法實現入參的加密。

因此，在入參的加密上我們只能選擇攔截Executor的update和query方法。

那麼返回值的解密呢？參考流程圖，我們能對ResultSetHandler和Executor做攔截，事實也確實如此，在處理返回值這一點上，這兩者是等價的，ResultSetHandler.handleResultSet()的返回值直接透傳給Executor，再由Executor透傳給SqlSession，所以兩者任選其一就可以。

四、方案實施

在知道需要攔截的物件後，就可以開始實現加解密外掛了。首先定義一個方法維度的註解。

/**
 * 透過註解來表明，我們需要對那個欄位進行加密
 */
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface TEncrypt {
    /**
     * 加密時從srcKey到destKey
     * @return
     */
    String[] srcKey() default {};
 
    /**
     * 解密時從destKey到srcKey
     * @return
     */
    String[] destKey() default {};
}

將該註解打在需要加解密的DAO層方法上。

UserMapper.java
public interface UserMapper {
    @TEncrypt(srcKey = {"secret"}, destKey = {"secretCiper"})
    List<UserInfo> selectUserList(UserInfo userInfo);
    }

修改xxxMapper.xml檔案

<mapper namespace="com.xxx.internet.demo.mapper.UserMapper">
    <resultMap id="BaseResultMap" type="com.xxx.internet.demo.entity.UserInfo">
        <id column="id" jdbcType="BIGINT" property="id" />
        <id column="phone" jdbcType="VARCHAR" property="phone"/>
        <id column="secret" jdbcType="VARCHAR" property="secret"/>
<!--        加密後對映-->
        <id column="secret_ciper" jdbcType="VARCHAR" property="secretCiper"/>
        <id column="name" jdbcType="VARCHAR" property="name" />
    </resultMap>
 
    <select id="selectUserList" resultMap="BaseResultMap" parameterType="com.xxx.internet.demo.entity.UserInfo">
        SELECT
        *
        FROM
        `t_user_info`
        <where>
            <if test="phone != null">
                `phone` = #{phone}
            </if>
<!--            明文欄位-->
            <if test="secret != null">
                AND `secret` = #{secret}
            </if>
<!--            加密後欄位-->
            <if test="secretCiper != null">
                AND `secret_ciper` = #{secretCiper}
            </if>
            <if test="name">
                AND `name` = #{name}
            </if>
        </where>
        ORDER BY `update_time` DESCv
    </select>
</mapper>

做完上面的修改，我們就可以編寫加密外掛了

@Intercepts({ @Signature(type = Executor.class, method = "update", args = { MappedStatement.class, Object.class }),
        @Signature(type = Executor.class, method = "query", args = { MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class }) })
public class ExecutorEncryptInterceptor implements Interceptor {
    private static final ObjectFactory        DEFAULT_OBJECT_FACTORY         = new DefaultObjectFactory();
 
    private static final ObjectWrapperFactory DEFAULT_OBJECT_WRAPPER_FACTORY = new DefaultObjectWrapperFactory();
 
    private static final ReflectorFactory     REFLECTOR_FACTORY              = new DefaultReflectorFactory();
 
    private static final List<String>         COLLECTION_NAME  = Arrays.asList("list");
 
    private static final String               COUNT_SUFFIX                   = "_COUNT";
 
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
 
        // 獲取攔截器攔截的設定引數物件DefaultParameterHandler
        final Object[] args = invocation.getArgs();
        MappedStatement mappedStatement = (MappedStatement) args[0];
        Object parameterObject = args[1];
 
        // id欄位對應執行的SQL的方法的全路徑，包含類名和方法名
        String id = mappedStatement.getId();
        String className = id.substring(0, id.lastIndexOf("."));
        String methodName = id.substring(id.lastIndexOf(".") + 1);
 
        // 分頁外掛會生成一個count語句，這個語句的引數也要做處理
        if (methodName.endsWith(COUNT_SUFFIX)) {
            methodName = methodName.substring(0, methodName.lastIndexOf(COUNT_SUFFIX));
        }
 
        // 動態載入類並獲取類中的方法
        final Method[] methods = Class.forName(className).getMethods();
 
        // 遍歷類的所有方法並找到此次呼叫的方法
        for (Method method : methods) {
            if (method.getName().equalsIgnoreCase(methodName) && method.isAnnotationPresent(TEncrypt.class)) {
 
                // 獲取方法上的註解以及註解對應的引數
                TEncrypt paramAnnotation = method.getAnnotation(TEncrypt.class);
 
                // 支援加密的操作，這裡只修改引數
                if (parameterObject instanceof Map) {
                    List<String> paramAnnotations = findParams(method);
                    parameterMapHandler((Map) parameterObject, paramAnnotation, mappedStatement.getSqlCommandType(), paramAnnotations);
                } else {
                    encryptParam(parameterObject, paramAnnotation, mappedStatement.getSqlCommandType());
                }
            }
        }
 
        return invocation.proceed();
    }
}

加密的主體流程如下：

  1. 判斷本次呼叫的方法上是否註解了@TEncrypt。
  2. 獲取註解以及在註解上配置的引數。
  3. 遍歷parameterObject，找到需要加密的欄位。
  4. 呼叫加密方法，得到加密後的值。
  5. 將加密後的欄位和值寫入parameterObject。

難點主要在parameterObject的解析，到了Executor這一層，parameterObject已經不再是簡單的Object[]，而是由MapperMethod.convertArgsToSqlCommandParam(Object[] args)方法建立的一個物件，既然要對這個物件做處理，我們肯定得先知道它的建立過程。

圖片

參考上圖parameterObject的建立過程，加密外掛對parameterObject的處理本質上是一個逆向的過程。如果是list，我們就遍歷list裡的每一個值，如果是map，我們就遍歷map裡的每一個值。

得到需要處理的Object後，再遍歷Object裡的每個屬性，判斷是否在@TEncrypt註解的srcKeys引數中，如果是，則加密再設定到Object中。

解密外掛的邏輯和加密外掛基本一致，這裡不再贅述。

五、問題挑戰

5.1 分頁外掛自動生成count語句

業務程式碼裡很多地方都用了 com.github.pagehelper 進行物理分頁，參考下面的demo，在使用PageRowBounds時，pagehelper外掛會幫我們獲取符合條件的資料總數並設定到rowBounds物件的total屬性中。

PageRowBounds rowBounds = new PageRowBounds(0, 10);
List<User> list = userMapper.selectIf(1, rowBounds);
long total = rowBounds.getTotal();

那麼問題來了，表面上看，我們只執行了userMapper.selectIf(1, rowBounds)這一條語句，而pagehelper是透過改寫SQL增加limit、offset實現的物理分頁，在整個語句的執行過程中沒有從資料庫裡把所有符合條件的資料讀出來，那麼pagehelper是怎麼得到資料的總數的呢？

答案是pagehelper會再執行一條count語句。先不說額外一條執行count語句的原理，我們先看看加了一條count語句會導致什麼問題。

參考之前的selectUserList介面，假設我們想選擇secret為某個值的資料，那麼經過加密外掛的處理後最終執行的大致是這樣一條語句 "select * from t\_user\_info where secret\_ciper = ? order by update\_time limit ?, ?"。

但由於pagehelper還會再執行一條語句，而由於該語句並沒有 @TEncrypt 註解，所以是不會被加密外掛攔截的，最終執行的count語句是類似這樣的: "select count(*) from t\_user\_info where secret = ? order by update_time"。

可以明顯的看到第一條語句是使用secret_ciper作為查詢條件，而count語句是使用secret作為查詢條件，會導致最終得到的資料總量和實際的資料總量不一致。

因此我們在加密外掛的程式碼裡對count語句做了特殊處理，由於pagehelper新增的count語句對應的mappedStatement的id固定以"\_COUNT"結尾，而這個id就是對應的mapper裡的方法的全路徑，舉例來說原始語句的id是"com.xxx.internet.demo.entity.UserInfo.selectUserList"，那麼count語句的id就是"com.xxx.internet.demo.entity.UserInfo.selectUserList\_COUNT"，去掉"_COUNT"後我們再判斷對應的方法上有沒有註解就可以了。

六、總結

本文介紹了使用 MyBatis 外掛實現資料庫欄位加解密的探索過程，實際開發過程中需要注意的細節比較多，整個流程下來我對 MyBatis 的理解也加深了。總的來說，這個方案比較輕量，雖然對業務程式碼有侵入，但能把影響面控制到最小。

相關文章