1. 概述
1.1 版本
| FineDataLink 版本 | 功能说明 |
|---|---|
| - | - |
| 4.1.5.1 | 新增加密函数和解密函数 |
1.2 功能说明
「编码函数」、「加密函数」、「签名函数」等常用于进行API加密认证取数时的 Token 生成。
本文主要介绍 FineDataLink 中 SparkSQL 算子支持的编码函数、环境变量等。
文档使用示例详情参见：
2. 环境变量
注1：相关函数默认大写。
注2：如需要引入字符串，字符串不区分单双引号。
| 名称 | 说明 | 示例 |
|---|---|---|
| UUID | 随机字符串 | SELECT UUID() 注：不支持改变长度 |
| UNIX_TIMESTAMP | 时间戳（Timestamp） | SELECT unix_timestamp() |
示例：
例如，用户需要使用「沃丰接口」取数，接口鉴权方式需要使用 unix time，nonce 为请求的唯一标识，值是由调用者提供的任意字符串，15分钟内此字符串只能被使用一次；在这里我们使用 SQL 的 uuid 函数生成。因此需要使用上述两个环境变量。
直接将 SparkSQL 作为输入源，输入 SQL 语句：
SELECT UNIX_TIMESTAMP(now()) AS time_str, UUID() AS uuid_str;
即可使用环境变量，取出两个指定的值，如下图所示：
3. 编码解码函数
注1：相关函数默认大写。
注2：如需要引入字符串，字符串不区分单双引号:。
| 名称 | 函数 | 示例 |
|---|---|---|
| BASE16 | BASE16(expr) | SELECT BASE16('FineDataLink') |
| base64 | base64(expr) | 转换 expr 为 base 64 字符串 select base64(cast('abcd' as binary))
|
| unbase64 | unbase64(expr) 注：括号内的数据需要是 Base64 编码的字符串 | 以二进制形式返回已解码的 base64 字符串。 示例一： 「Spark SQL 算子」中输入：select unbase64('YWJjZA==')
示例二： 1）使用 base64 函数，编码字符串
编码后数据如下图所示：
2）再使用 unbase64 函数，解码使用 base64 函数编码后的字符串
效果如下图所示：
|
| URLENCODE | URLENCODE(expr) | SELECT URLENCODE('FineDataLink') |
unhex | unhex(expr) | select unhex('537061726B2053514C') 返回值：Spark SQL |
hex | hex(expr) | select hex('Spark SQL') 返回值：537061726B2053514C |
| encode | encode(str, charset) | SELECT encode('abc', 'utf-8'); 返回值：abc |
| decode | decode(bin, charset) | SELECT decode(encode('abc', 'utf-8'), 'utf-8'); 返回值：abc |
4. 加密函数
注1：相关函数默认大写。
注2：如需要引入字符串，字符串不区分单双引号:。
| 名称 | 函数 | 参数说明 | 格式与返回值 | FDL的SparkSQL算子内用法 |
|---|---|---|---|---|
| MD5 | MD5(expr) | - | 示例：SELECT MD5('FineDataLink') | |
| SHA | SHA(expr) | - | - | 示例：SELECT SHA('FineDataLink') |
| SHA1 | SHA1(expr) | - | - | 示例：SELECT SHA1('FineDataLink') |
| SHA2 | SHA2(expr, bitLength) | - | - | 注：bitLength为SHA2的位数，支持SHA-224、SHA-256、SHA-384和 SHA-512，默认为SHA256。 示例：SELECT SHA2('FineDataLink',256) |
| RSA | RSA(expr,secretKey,keyFormat) | - | - | 注：secretKey为输入的密钥、格式为base64编码，keyFormat为密钥格式、值为'PKCS1'和'PKCS8'（不区分格式的大小写），本函数返回值格式也为base64编码 示例：SELECT RSA( 'FineDataLink' , 'MIIBCgKCAQEAnLdoA3ba57YHBAenYbLGTcdC48VVvVVDXV6N/W+1FztBRjvNPV1D |
AES 注：4.1.5.1开始支持。 | aes_encrypt(expr, key[, mode[, padding[, iv[, aad]]]]) |
| SELECT hex(aes_encrypt('Spark', '0000111122223333')); | |
DES 注：4.1.5.1开始支持。 | des_encrypt(plainText, key, mode, padding, iv) | plainText：明文，需要加密的文本 | plainText：文本 key：文本格式或者byte数组格式，十六进制格式的密钥使用unhex、Base64格式的密钥使用unbase64。例如："miyao", unhex("123def"), unbase64("some_base64_string") 返回值：byte数组，若要可视化需要套一层hex或者base64，例如：hex(des_encrypt(...)), base64(des_encrypt(...)) | 示例： SELECT hex(des_encrypt(`Roxy@fanraun.com`,`my8bytky`,`ECB`,`PKCS5`,null)) |
| key：密钥 | ||||
| mode：加密模式，合法的值为ECB（默认）、CBC、CFB、OFB、CTR。如果传null，则为ECB加密，传非法值报错 | ||||
| padding：填充模式，合法的值为PKCS5（默认）、ISO10126、no。如果传null，则为PKCS5填充，传非法值报错，不区分大小写 | ||||
iv：初始向量，CBC、CFB、OFB模式必传，其他模式传null即可 | ||||
sm4 注：4.1.5.1开始支持。 | sm4_encrypt(plainText, key, mode, iv) | plainText：需要加密的文本 | plainText：文本 key：文本格式或者byte数组格式，十六进制格式的密钥使用unhex、Base64格式的密钥使用unbase64。例如："miyao", unhex("123def"), unbase64("some_base64_string") 返回值：byte数组，若要可视化需要套一层hex或者base64，例如：hex(sm4_encrypt(...)), base64(sm4_encrypt(...)) | 示例： SELECT BASE64(sm4_encrypt('spark', unhex('30303030313131313232323233333333'), 'ECB', null)); O6F0JI1MwSQkSbU9Bjgb4A== O6F0JI1MwSQkSbU9Bjgb4A== |
| key：密钥 | ||||
| mode：加密模式，合法的值为ECB（默认）、CBC、CFB、OFB、CTR。如果传null，则为ECB加密，传非法值报错 | ||||
iv：初始向量，CBC模式必传，若为ECB模式请传null | ||||
填充模式固定为PKCS7 | ||||
sm2 注：4.1.5.1开始支持。 | sm2_encrypt(plainText, publicKey) | plainText：需要加密的文本 publicKey：接收者的公钥 加密模式固定为新版C1C3C2 | publicKey：十六进制数据 返回值：Base64编码 | SELECT sm2_encrypt('spark', '04BDE0D3CBC2D3472AFAD7D020DDB3A8C3A8C22914E5E29753DF12EA91A199E2E1D9F0821EFEDB622D56DA4B719B62C7342852C0C42C84C4C83102761B678CF39F'); 返回值： BEucJcdQXwOxg7HRgZ8eWY00d2giXuEy6q5aI1w3QyVTH/np9LV4YrTfMOYCsQi3sGK6j/WP2UevXUb25g55Pri+Kqp97qfxxnxF655267XYBoHXyeWG/lCf1ZIzOk5GdHcz6UKh |
| sm2_encrypt_C1C2C3(plainText, publicKey) | plainText：需要明文 publicKey：公钥 加密模式固定为旧版C1C2C3 | publicKey：十六进制数据 返回值：Base64编码 | SELECT sm2_encrypt_C1C2C3('spark', '04BDE0D3CBC2D3472AFAD7D020DDB3A8C3A8C22914E5E29753DF12EA91A199E2E1D9F0821EFEDB622D56DA4B719B62C7342852C0C42C84C4C83102761B678CF39F'); 返回值： BJYqv1G2F7sSeC8/u2oHp5HBbg6KH9P0AmjtjT5hDcwXvBpLYLDVGZ8J7MvF8la3sMryd9hWTkxA/AOHlQLF5xa3Ko9X/+zgoNOR3pmY9P2pw9+hwO6e/xI4rgld1P2qdy9AAJ5W |
示例：
本文第三节中获取了timestamp、nonce 两个值，签名 sign 为 email 、open_api_token、timestamp、nonce、sign_version 共同组合生成 sign=SHA256(email&open_api_token×tamp&nonce&sign_version)，使用了加密函数。
紧接着本文第五节的算子，新增 SparkSQL 并输入
SELECT SHA2(CONCAT("email&open_api_token",time_str,"&",uuid_str,"&v2") ,256) as sign_str,time_str,uuid_str from SparkSQL
5. 解密函数
注：4.1.5.1开始支持。
| 名称 | 函数 | 参数说明 | 格式与返回值 | FDL的SparkSQL算子内用法 |
|---|---|---|---|---|
| AES | aes_decrypt(expr, key[, mode[, padding[, aad]]]) |
| SELECT aes_decrypt(unhex('83F16B2AA704794132802D248E6BFD4E380078182D1544813898AC97E709B28A94'), '0000111122223333'); | |
| DES | des_decrypt(cipherText, key, mode, padding, iv) | cipherText：需要解密的密文 | cipherText：文本或者byte数组格式，十六进制格式的密文使用unhex、Base64格式的密文使用unbase64。。例如："miwen", unhex("123def"), unbase64("some_base64_string") | 示例：SELECT des_decrypt(unhex('f0ecd50abef6bc01da5d0af7da1bdfb8879f8ec06c2d3837'),'my8bytky','CBC','PKCS5','12345678') 结果：user@example.com
|
| key：密钥 | ||||
| mode：模式，合法的值为ECB（默认）、CBC、CFB、OFB、CTR。如果传null，则为ECB加密，传非法值报错 | ||||
| padding：填充模式，合法的值为PKCS5（默认）、ISO10126、no。如果传null，则为PKCS5填充，传非法值报错，不区分大小写 | ||||
| SM4 | sm4_decrypt(cipherText, key, mode, iv) | expr：需要解密的文本 | cipherText：文本或者byte数组格式，十六进制格式的密文使用unhex、Base64格式的密文使用unbase64。例如："miwen", unhex("123def"), unbase64("some_base64_string") key：文本格式或者byte数组格式，十六进制格式的密钥使用unhex、Base64格式的密钥使用unbase64。例如："miyao", unhex("123def"), unbase64("some_base64_string") 返回值：文本 | SELECT sm4_decrypt(unbase64('O6F0JI1MwSQkSbU9Bjgb4A=='), unhex('30303030313131313232323233333333'), 'ECB', null); 返回值：spark SELECT sm4_decrypt(unbase64('O6F0JI1MwSQkSbU9Bjgb4A=='), '0000111122223333', 'ECB', null); 返回值：spark |
key：加密密钥 | ||||
| mode：加密模式，合法的值为ECB（默认），CBC。如果传null，则为ECB加密，传非法值报错 | ||||
iv：初始向量，CBC模式必传，若为ECB模式请传null | ||||
填充模式固定为PKCS7 | ||||
| SM2 | sm2_decrypt(cipherText, privateKey) | expr：需要解密的文本 key：接收者的私钥 | cipherText：Base64编码的文本 privateKey：十六进制数据 返回值：文本 | SELECT sm2_decrypt('BEucJcdQXwOxg7HRgZ8eWY00d2giXuEy6q5aI1w3QyVTH/np9LV4YrTfMOYCsQi3sGK6j/WP2UevXUb25g55Pri+Kqp97qfxxnxF655267XYBoHXyeWG/lCf1ZIzOk5GdHcz6UKh','160430D73E9284086AF3B0D4B1D2EB2E40E00637D5288B6B0A736B2EF78AAEC6'); 返回值：spark |
| sm2_decrypt_C1C2C3(cipherText, privateKey) | cipherText：需要解密的文本 privateKey：接收者的私钥 | cipherText：Base64编码的文本 privateKey：十六进制数据 返回值：文本 | SELECT sm2_decrypt_C1C2C3('BJYqv1G2F7sSeC8/u2oHp5HBbg6KH9P0AmjtjT5hDcwXvBpLYLDVGZ8J7MvF8la3sMryd9hWTkxA 返回值： spark | |
| RSA | rsa_decrypt(cipherText, privateKey, keyFormat) | cipherText：需要解密的密文 privateKey：私钥 keyFormat：密钥格式、值为'PKCS1'和'PKCS8'（不区分格式的大小写） | cipherText：Base64编码的文本 privateKey：Base64编码的密钥 返回值：文本 | SELECT 返回值： spark |
示例：例如使用解密函数，输入：SELECT des_decrypt(unhex('f0ecd50abef6bc01da5d0af7da1bdfb8879f8ec06c2d3837'),'my8bytky','CBC','PKCS5','12345678')，得到解密值如下图所示：
6. 签名函数
注1：相关函数默认大写。
注2：如需要引入字符串，字符串不区分单双引号:。
| 名称 | 函数 | 参数说明 | 格式与返回值 | FDL的SparkSQL算子内用法 |
|---|---|---|---|---|
| HMAC-MD5 | HMACMD5(expr,secretKey,format) |
| SELECT HMACMD5( 'FineDataLink' , 'Im a secret key' , 'HEX') | |
| HMAC-SHA1 | HMACSHA1(expr,secretKey,format) | secretKey为输入的密钥，format格式值可选为'HEX'或'BASE64'（不区分格式的大小写） | SELECT HMACSHA1( 'FineDataLink' , 'Im a secret key' , 'HEX') | |
| HMAC-SHA256 | HMACSHA256(expr,secretKey,format) | secretKey为输入的密钥，format格式值可选为'HEX'或'BASE64'（不区分格式的大小写） | SELECT HMACSHA256( 'FineDataLink' , 'Im a secret key' , 'HEX') | |
SM3 注：4.1.5.1开始支持。 | sm3(expr) | expr：要签名的文本 | 返回值：十六进制字符串 | 示例： SELECTsm3('spark'); 返回值： |
SM2 注：4.1.5.1开始支持。 | sm2_sign(data, privateKey) | data：要签名的数据 privateKey：私钥（十六进制数据） | 十六进制数据 | 示例： SELECT sm2_sign('FineDataLink' |
7. 附录
sm2 密钥在线生成网站：https://config.net.cn/tools/SM2.html
sm4 密钥在线生成网站：https://config.net.cn/tools/SM4.html
RSA 密钥在线生成网站：http://www.metools.info/code/c80.html
