瓦片加密全流程使用指南

为防止瓦片数据爬取并进一步增强使用安全性，SuperMap 11i(2024) 系列产品中提供了从服务端加密到客户端解密的全流程瓦片加密能力。同时对于加密算法，也支持了符合国家标准的 SM4 国密算法。

本章将从如何在 SuperMap iServer 中对瓦片数据加密和在 SuperMap Web 客户端中对瓦片数据解密浏览两个方面进行详细的使用介绍，助力实际业务中瓦片数据的安全使用。

一、在 SuperMap iServer 中对瓦片数据加密

1、SuperMap iServer 支持的加密算法

1）SM4

SM4 算法，全称为 SM4 分组密码算法，是由中国国家密码管理局发布的商用密码算法标准。在 SuperMap iServer 中内置该算法，在对瓦片数据加密时使用的模式和密钥长度默认如下：

• 支持 CTR 模式算法。当使用缺省值，即 SM4 时，代表使用 SM4/CTR 加解密
• 密钥长度：128位

2）AES

AES（Advanced Encryption Standard）算法，最常见的对称加密算法，是美国联邦政府采用的一种区块加密标准。在 SuperMap iServer 中内置该算法，在对瓦片数据加密时使用的模式和密钥长度默认如下：

• 支持 CTR 模式算法。当使用缺省值，即 AES 时，代表使用 AES/CTR 加解密
• 密钥长度：256位

2、SuperMap iServer 中的瓦片加密

SuperMap iServer 通过对不同服务中获取瓦片的服务接口进行动态加密来实现瓦片加密的目的。以下对加密配置及验证方法进行介绍。

1）加密算法配置

加密算法及规格通过 <encryption> 节点配置，位于 iserver-system.xml（（【SuperMap iServer 安装目录】\webapps\iserver\WEB-INF下）的 <security> 节点中，具体示例如下：

      <!-- iServer 加密算法及规格配置 -->                
      <encryption class="com.supermap.server.config.EncryptionSetting">           
        <serviceKeySettings>
          <serviceKeySetting>   
            <keyID>keyID1</keyID>  
            <version>1.1</version>                     
            <algorithm>SM4</algorithm>                     
            <keyLength>128</keyLength>                     
          </serviceKeySetting>
        </serviceKeySettings>
        <keyProviderSettings>
           <keyProvider>com.supermap.model.util.SM4SecretKeyProvider</keyProvider>
        </keyProviderSettings> 
      </encryption> 

其中，

• <serviceKeySettings>：GIS 服务动态加密算法设置节点。此节点中可为多个服务组件配置加密算法，每个在 <serviceKeySetting> 节点中设置，以配置项 <keyID> 作为标识。具体包含以下配置项：

• <keyID>：【必选参数】每种服务组件加密算法的标识，只支持字母和数字,例如：keyID1。需与 GIS 服务动态加密配置文件（【SuperMap iServer 安装目录】\webapps\iserver\WEB-INF\config\iserver-svcworkkeymappings.xml）中的 <keyID> 对应，以保证生效。注意：不同服务组件的keyID不能一致
• <algorithm>：【必选参数】加密算法名。算法名支持两段写法，例如：SM4/CTR；也支持缺省写法，例如：SM4。
• <keyLength>：密钥长度，单位为b。当使用 SM4 算法时可设置为128，AES 时可设置为256。默认值见：SuperMap iServer 支持的加密算法。
• <version>：密钥版本信息，例如：1.1。

• <keyProviderSettings>：密钥设置节点。若您需要配置外置密钥，可在此节点中进行自定义密钥配置。此节点中可配置多个扩展密钥，每个在 <keyProvider> 节点中设置，iServer将依次尝试获取密钥。若不设置将使用 iServer 内置的密钥，包含以下配置项：

• <keyProvider>：扩展密钥类名。该类名为 jar 包的包路径，例如：com.supermap.model.util.SM4SecretKeyProvider。在实际项目使用中，您需要先将 jar 包编译为 class 文件，然后将文件按包路径存放在【SuperMap iServer 安装目录】\webapps\iserver\WEB-INF\classes 文件夹下。在上文例子中，对应的 class 文件存放路径为：【SuperMap iServer 安装目录】\webapps\iserver\WEB-INF\classes\com\supermap\model\util\SM4SecretKeyProvider.class。扩展自定义外置密钥的实现方法详见：扩展加密密钥

2）GIS 服务动态加密配置（含矢量瓦片、三维模型瓦片等瓦片加密）

为了对瓦片使用期望的加密方式，还需要在 iserver-svcworkkeymappings.xml（【SuperMap iServer 安装目录】\webapps\iserver\WEB-INF\config下）文件中对能够获取该类型瓦片的服务进行 GIS 服务的动态加密配置。以下分别对三维、地图和数据服务能够进行瓦片加密的接口进行配置的举例说明：

 <?xml version="1.0" encoding="UTF-8"?>                
 <svcworkkeymappings>          
     <!-- 三维服务组件加密配置（以后缀为.s3m的模型瓦片为例）-->
     <serviceType>   
         <typeName>com.supermap.services.components.impl.RealspaceImpl</typeName>  
         <keyID>keyID1</keyID>                     
         <urls>                     
            <string>/iserver/services/.*?/rest/realspace/datas/.*?/data/path/.*?/.*?\.s3m.*</string>                     
         </urls>
     </serviceType>
     <!-- 地图服务组件加密配置（以后缀为.mvt的矢量瓦片为例）-->
     <serviceType>
         <typeName>com.supermap.services.components.impl.MapImpl</typeName>
             <keyID>keyID2</keyID>
             <urls>
                 <string>/iserver/services/.*?/rest/maps/.*?/tileFeature\.mvt.*</string>
                 <string>/iserver/services/.*?/restjsr/v1/vectortile/maps/.*?/tiles/.*?/.*?/.*?\.mvt.*</string>
             </urls>
     </serviceType>
     <!-- 数据服务组件加密配置（以后缀为.mvt的矢量瓦片为例）-->
     <serviceType>
         <typeName>com.supermap.services.components.impl.DataImpl</typeName>
         <keyID>keyID3</keyID>
         <urls>
             <string>/iserver/services/.*?/rest/data/datasources/.*?/datasets/.*?/tileFeature\.mvt.*</string>
         </urls>
     </serviceType>
</svcworkkeymappings>

其中，

• <typeName>：服务组件名称，可在服务配置文件（【SuperMap iServer 安装目录】\webapps\iserver\WEB-INF\iserver-services.xml）中查看。
• <keyID>：加密算法标识，需与系统配置文件（【SuperMap iServer 安装目录】\webapps\iserver\WEB-INF\iserver-system.xml）中的 <keyID> 对应。注意：一类服务组件只能对应一个 keyID，且不同服务组件的 keyID 不能一致。
• <urls>：需要加密的服务接口。此节点中可配置同个服务组件的多个接口，每个在 <string> 节点中设置，需能够与实际的请求 url 匹配。有如下规则：

• 应包含除完整的资源 url 请求路径
• 对于非固定值使用“ .*?”来代替，例如服务组件名 map-world
• 资源后、文件后缀前，由“\”分割

例如：对矢量瓦片服务 tiles 接口 （示例 url：http://localhost:8090/iserver/services/map-world/restjsr/v1/vectortile/maps/World/tiles/0/0/0.mvt）进行加密，则 <string> 节点中需配置为 /iserver/services/.*?/restjsr/v1/vectortile/maps/.*?/tiles/.*?/.*?/.*?\.mvt.*

3）加密配置生效验证

完成上述配置后重启SuperMap iServer再发布服务，瓦片加密配置即可生效。您可以通过如下两个方面来验证是否生效。

• 使用 iServer 内置二维表述（iClient for openlayers3 (with MVT) ,for MapboxGL）浏览矢量瓦片地图、三维表述（WebGL3D、Cesium）浏览三维模型数据或场景时不显示
• 请求被加密服务的 service 资源，响应体中能够返回加密信息。例如：对 localhost:8090/iserver/services/map-China100.json 执行 get 请求，响应体如下：

{

    ...

    "serviceEncryptInfo":

    {

        "encrptSpec":

        {

            "keyLength":128,

            "attributes":null,

            "version":"1.1",

            "algorithm":"SM4"

         }

         "updateTime":"Fri Sep 06 10:07:15 CST 2024",

         "encrptKeyID":"keyID1"

    }

    ...

    "url": "http://localhost:8090/iserver/services/map-China100/restjsr"

}

二、在 SuperMap Web 客户端中对瓦片数据解密浏览

经 SuperMap iServer 加密后的瓦片数据仅能通过客户端解密进行浏览。以下将从 SuperMap 二维客户端和三维客户端两个方面进行介绍如何对加密的瓦片数据进行加载显示。

1、二维客户端解密

SuperMap iClient 11i(2024)中提供了 OpenLayers 和 MapboxGL 用于解密浏览矢量瓦片数据的 API，详情请参考 SuperMap iClient 官网帮助文档。以下提供简要示例代码来说明具体的应用方式：

1）for OpenLayers

在常规代码中增加 decrypt 参数，当为 true 时表示对瓦片进行解密请求。执行代码后，iServer 发布的服务即可解密并进行矢量瓦片出图。

<script type="text/javascript">

      const styleURL =

        "http://localhost:8090/iserver/services/map-China100/restjsr/v1/vectortile/maps/China_4326/style.json";

      ...

      style.on('styleloaded', function () {

        const vectorLayer = new ol.layer.VectorTile({

          declutter: true,

          source: new ol.source.VectorTileSuperMapRest({

            style: styleURL,

            projection: 'EPSG:4326',

            format: format,

            decrypt: true   //解密参数

          }),

          style: style.getStyleFunction()

        });

        map.addLayer(vectorLayer);

      });

 </script>

2）for MapboxGL

在常规代码中增加 decryptSources 类，并配置 style 中的 source 值，如 China。执行代码后，iServer 发布的服务即可解密并进行矢量瓦片出图。

<script type="text/javascript">

      mapboxgl.supermap.decryptSources.set(["China"]);   //解密参数

      var map = new mapboxgl.Map({

        container: "map",

        renderWorldCopies: false,

        style: "http://172.16.15.94:8090/iserver/services/map-China100/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true",

        center: [106, 35],

        zoom: 4

      });

 </script>

2、三维客户端解密

SuperMap iClient3D for WebGL/WebGPU 11i(2024) SP1 中支持对 S3M 三维模型瓦片进行解密浏览，无需在代码中增加更多参数，引入 SuperMap iServer 使用三维模型瓦片发布的三维服务地址后，即可执行代码进行浏览。以下提供简要示例代码来说明具体的应用方式：

<script type="text/javascript">

function init(SuperMap3D, scene, viewer) {

    ...

    try{

           var promise = scene.open("http://localhost:8090/iserver/services/3D-CBD/rest/realspace");

            SuperMap3D.when(promise,function(layers){

                var layer = scene.layers.find('Config');

                sceneLayer = layer;

            },function(){

                var title = '加载SCP失败，请检查网络连接状态或者url地址是否正确？';

                widget.showErrorPanel(title, undefined, e);

            });

        }

        catch(e){

            if (widget._showRenderLoopErrors) {

                var title = '渲染时发生错误，已停止渲染。';

                widget.showErrorPanel(title, undefined, e);

            }

    }

    ...

 }    

 </script>