Documentation Home
MySQL 8.4 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 39.8Mb
PDF (A4) - 39.9Mb
Man Pages (TGZ) - 257.9Kb
Man Pages (Zip) - 364.9Kb
Info (Gzip) - 4.0Mb
Info (Zip) - 4.0Mb


MySQL 8.4 Reference Manual  /  ...  /  MySQL Enterprise Encryption Component Function Descriptions

8.6.5 MySQL 企业加密组件函数描述

MySQL 企业加密函数具有这些一般特征:

  • 如果参数类型错误或参数数量不正确,每个函数都返回错误。

  • 如果参数不可用以执行请求操作,它返回NULL或0,例如,如果函数不支持指定算法、密钥长度太短或长,或者字符串期望是PEM格式的密钥字符串不是有效密钥。

  • 底层SSL库负责随机数初始化。

组件函数只支持RSA加密算法。

对于更多示例和讨论,见第8.6.3节,“MySQL 企业加密使用和示例”

  • asymmetric_decrypt(algorithm, data_str, priv_key_str)

    使用指定算法和密钥字符串对加密字符串进行解密,并将结果作为二进制字符串返回。如果解密失败,结果为NULL

    在MySQL 8.0.29之前的legacy版本中使用该函数,请见MySQL 企业加密 legacy 函数描述

    默认情况下,component_enterprise_encryption 函数假设加密文本使用 RSAES-OAEP 填充方案。该函数支持对旧的 openssl_udf 共享库函数加密内容进行解密,如果系统变量enterprise_encryption.rsa_support_legacy_padding 设置为 ON(默认是 OFF)。当该变量设置为 ON 时,函数还支持 RSAES-PKCS1-v1_5 填充方案,用于旧的 openssl_udf 共享库函数。否则加密内容无法解密,函数返回 null 输出。

    algorithm 是创建密钥所用的加密算法。支持的算法值是 'RSA'.

    data_str 是要解密的加密字符串,使用asymmetric_encrypt() 加密。

    priv_key_str 是一个有效的PEM编码RSA私钥。为了成功解密,关键字符串必须与asymmetric_encrypt()使用的公钥字符串相符。asymmetric_encrypt()组件函数只支持使用公钥加密,所以解密将使用对应的私钥。

    使用示例,请查看asymmetric_encrypt()的描述。

  • asymmetric_encrypt(algorithm, data_str, pub_key_str)

    使用给定的算法和密钥字符串加密字符串,并返回结果的二进制字符串。如果加密失败,结果为NULL

    在MySQL 8.0.29之前的遗留版本,请查看MySQL Enterprise Encryption Legacy Function Descriptions

    algorithm 是创建密钥使用的加密算法。支持的算法值为'RSA'

    data_str 是要加密的字符串。这串字符串的长度不能超过密钥字符串字节长度,减去42(考虑填充)。

    pub_key_str 是一个有效的PEM编码的RSA公共密钥。asymmetric_encrypt() 组件函数仅支持使用公共密钥进行加密。

    要恢复原始未加密的字符串,请将加密后的字符串传递给 asymmetric_decrypt(),并且带上用于加密的其他密钥对的一部分,如以下示例所示:

    -- Generate private/public key pair
    SET @priv = create_asymmetric_priv_key('RSA', 2048);
    SET @pub = create_asymmetric_pub_key('RSA', @priv);
    
    -- Encrypt using public key, decrypt using private key
    SET @ciphertext = asymmetric_encrypt('RSA', 'The quick brown fox', @pub);
    SET @plaintext = asymmetric_decrypt('RSA', @ciphertext, @priv);

    假设:

    SET @s = a string to be encrypted
    SET @priv = a valid private RSA key string in PEM format
    SET @pub = the corresponding public RSA key string in PEM format

    然后这些身份关系成立:

    asymmetric_decrypt('RSA', asymmetric_encrypt('RSA', @s, @pub), @priv) = @s
  • asymmetric_sign(algorithm, text, priv_key_str, digest_type)

    使用私钥对摘要字符串或数据字符串进行签名,并返回二进制字符串。如果签名失败,结果为 NULL

    对于在MySQL 8.0.29之前的遗留版本,请见MySQL Enterprise Encryption Legacy Function Descriptions

    algorithm 是创建密钥时使用的加密算法。支持的算法值为 'RSA'

    text 是数据字符串或摘要字符串。该函数接受摘要,但不需要它们,因为它也可以处理任意长度的数据字符串。可以通过调用create_digest()生成摘要字符串。

    priv_key_str 是用于签名摘要字符串的私钥字符串。它必须是有效的PEM编码RSA私钥。

    digest_type 是用于签名数据的算法。支持的digest_type值包括 'SHA224''SHA256''SHA384''SHA512',当使用 OpenSSL 1.0.1 时。如果使用 OpenSSL 1.1.1,则还可以使用额外的digest_type'SHA3-224''SHA3-256''SHA3-384''SHA3-512'

    使用示例,请查看asymmetric_verify() 的描述。

  • asymmetric_verify(algorithm, text, sig_str, pub_key_str, digest_type)

    验证签名字符串是否与摘要字符串匹配,并返回1或0以指示验证是否成功或失败。如果验证失败,结果为 NULL

    默认情况下,component_enterprise_encryption 函数假设签名使用 RSASSA-PSS 签名方案。该函数支持对由旧的 openssl_udf 共享库函数生成的签名进行验证,如果系统变量enterprise_encryption.rsa_support_legacy_padding 设置为 ON(默认是 OFF),函数还支持 RSASSA-PKCS1-v1_5 签名方案,用于旧的 openssl_udf 共享库函数生成的签名;当它为 OFF 时,legacy 函数生成的签名无法验证,函数返回空结果。

    algorithm 是创建密钥时使用的加密算法。支持的算法值为 'RSA'

    text 是数据字符串或摘要字符串。组件函数接受摘要,但不需要它们,因为它也可以处理任意长度的数据字符串。可以通过调用create_digest()生成摘要字符串。

    sig_str 是要验证的签名字符串。可以通过调用asymmetric_sign()生成签名字符串。

    pub_key_str 是签名者的公钥字符串。它对应于asymmetric_sign()中传递的私钥。必须是有效的PEM编码RSA公钥。

    digest_type 是用来签名数据的算法。支持的digest_type值为 'SHA224''SHA256''SHA384''SHA512',当使用 OpenSSL 1.0.1 时。如果使用 OpenSSL 1.1.1,则可用额外的digest_type'SHA3-224''SHA3-256''SHA3-384''SHA3-512'

    -- Set the encryption algorithm and digest type
    SET @algo = 'RSA';
    SET @dig_type = 'SHA512';
    
    -- Create private/public key pair
    SET @priv = create_asymmetric_priv_key(@algo, 2048);
    SET @pub = create_asymmetric_pub_key(@algo, @priv);
    
    -- Generate digest from string
    SET @dig = create_digest(@dig_type, 'The quick brown fox');
    
    -- Generate signature for digest and verify signature against digest
    SET @sig = asymmetric_sign(@algo, @dig, @priv, @dig_type);
    SET @verf = asymmetric_verify(@algo, @dig, @sig, @pub, @dig_type);
  • create_asymmetric_priv_key(algorithm, key_length)

    使用给定的算法和密钥长度创建私钥,并将其作为PEM格式的二进制字符串返回。如果密钥生成失败,结果为 NULL

    对于在 MySQL 8.0.29 之前使用的 legacy 版本函数,请参阅MySQL Enterprise Encryption Legacy Function Descriptions

    algorithm 是用于创建密钥的加密算法。支持的算法值是 'RSA'

    key_length 是密钥长度,以位为单位。如果您超过允许的最大密钥长度或指定小于最小值,密钥生成失败,结果为空。最小允许的密钥长度以位是 2048。最大允许的密钥长度是enterprise_encryption.maximum_rsa_key_size 系统变量的值,缺省为 4096。该变量的最大设置值为 16384,这是 RSA 算法允许的最大密钥长度。请参阅第8.6.2节,“配置 MySQL Enterprise Encryption”

    Note

    生成更长的密钥可能会消耗大量 CPU 资源。使用enterprise_encryption.maximum_rsa_key_size 系统变量限制密钥长度,允许您根据需求提供安全性,同时平衡资源使用。

    以下示例创建了 2048 位 RSA 私钥,然后从私钥派生公钥:

    SET @priv = create_asymmetric_priv_key('RSA', 2048);
    SET @pub = create_asymmetric_pub_key('RSA', @priv);
  • create_asymmetric_pub_key(算法, 私钥字符串)

    使用给定的算法从给定的私钥中派生公钥,并将其作为PEM格式的二进制字符串返回。如果密钥派生失败,结果为 NULL

    对于在MySQL 8.0.29之前使用的legacy版本,请参阅MySQL Enterprise Encryption Legacy Function Descriptions

    算法 是用于创建密钥的加密算法。支持的算法值为 'RSA'

    私钥字符串 是一个有效的PEM编码的RSA私钥。

    请参阅create_asymmetric_priv_key() 的使用示例描述。

  • create_digest(摘要类型, 字符串)

    使用给定的摘要类型对给定的字符串进行摘要,并将其作为二进制字符串返回。如果摘要生成失败,结果为 NULL

    对于在MySQL 8.0.29之前使用的legacy版本,请参阅MySQL Enterprise Encryption Legacy Function Descriptions

    生成的摘要字符串适用于与asymmetric_sign()asymmetric_verify()一起使用。这些函数的组件版本接受摘要,但不需要,因为它们可以处理任意长度的数据。

    digest_type 是用于生成摘要字符串的摘要算法。支持的digest_type值是 'SHA224''SHA256''SHA384''SHA512',当使用 OpenSSL 1.0.1 时。如果使用 OpenSSL 1.1.1,则可用的额外digest_type值是 'SHA3-224''SHA3-256''SHA3-384''SHA3-512'

    str 是要生成摘要的非空数据字符串。

    SET @dig = create_digest('SHA512', 'The quick brown fox');