Documentation Home
MySQL 8.3 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 40.8Mb
PDF (A4) - 40.9Mb
Man Pages (TGZ) - 294.0Kb
Man Pages (Zip) - 409.0Kb
Info (Gzip) - 4.0Mb
Info (Zip) - 4.0Mb
Excerpts from this Manual

MySQL 8.3 Reference Manual  /  ...  /  MySQL Enterprise Encryption Legacy Function Descriptions

8.6.6 MySQL 企业加密遗留函数描述

在 MySQL 8.0.30 之前的版本中,MySQL 企业加密的函数基于 openssl_udf 共享库。该参考描述了这些函数。这些函数在后续版本中仍然可用,但已弃用。

有关升级到由 MySQL 组件 component_enterprise_encryption 提供的新组件函数的信息,以及遗留函数和组件函数之间行为差异的列表,请参阅 升级 MySQL 企业加密

组件函数的参考是 第 8.6.5 节,“MySQL 企业加密组件函数描述”

MySQL 企业加密函数具有以下一般特征:

  • 对于类型错误或参数数量错误的参数,每个函数返回错误。

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

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

一些遗留函数采用加密算法参数。以下表格总结了每个函数支持的算法。

表 8.52 每个函数支持的算法

Function Supported Algorithms
asymmetric_decrypt() RSA
asymmetric_derive() DH
asymmetric_encrypt() RSA
asymmetric_sign() RSA, DSA
asymmetric_verify() RSA, DSA
create_asymmetric_priv_key() RSA, DSA, DH
create_asymmetric_pub_key() RSA, DSA, DH
create_dh_parameters() DH

Note

尽管您可以使用 RSA、DSA 或 DH 加密算法创建密钥,但其他遗留函数可能只接受特定类型的密钥。例如,asymmetric_encrypt()asymmetric_decrypt() 只接受 RSA 密钥。

有关其他示例和讨论,请参阅 第 8.6.3 节,“MySQL 企业加密使用和示例”

  • asymmetric_decrypt(algorithm, crypt_str, key_str)

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

    无法使用 openssl_udf 共享库函数解密由 component_enterprise_encryption 函数生成的内容,该函数从 MySQL 8.0.30 开始可用。

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

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

    key_str 是有效的 PEM 编码 RSA 公钥或私钥字符串。为了成功解密,密钥字符串必须对应于使用 asymmetric_encrypt() 生成加密字符串的公钥或私钥字符串。

    有关使用示例,请参阅 asymmetric_encrypt() 的描述。

  • asymmetric_derive(pub_key_str, priv_key_str)

    使用私钥和公钥派生对称密钥,并返回结果密钥作为二进制字符串。如果密钥派生失败,结果为 NULL

    pub_key_strpriv_key_str 是有效的 PEM 编码密钥字符串,使用 DH 算法创建。

    假设您有两个公钥和私钥对:

    SET @dhp = create_dh_parameters(1024);
    SET @priv1 = create_asymmetric_priv_key('DH', @dhp);
    SET @pub1 = create_asymmetric_pub_key('DH', @priv1);
    SET @priv2 = create_asymmetric_priv_key('DH', @dhp);
    SET @pub2 = create_asymmetric_pub_key('DH', @priv2);

    假设您使用一个对的私钥和另一个对的公钥来创建对称密钥字符串。然后,这个对称密钥身份关系成立:

    asymmetric_derive(@pub1, @priv2) = asymmetric_derive(@pub2, @priv1)

    该示例需要使用 DH 私钥和公钥作为输入,使用共享对称秘密创建秘密。使用 create_dh_parameters() 传递密钥长度,然后将秘密传递给 create_asymmetric_priv_key()

    -- Generate DH shared symmetric secret
    SET @dhp = create_dh_parameters(1024);
    -- Generate DH key pairs
    SET @algo = 'DH';
    SET @priv1 = create_asymmetric_priv_key(@algo, @dhp);
    SET @pub1 = create_asymmetric_pub_key(@algo, @priv1);
    SET @priv2 = create_asymmetric_priv_key(@algo, @dhp);
    SET @pub2 = create_asymmetric_pub_key(@algo, @priv2);
    
    -- Generate symmetric key using public key of first party,
    -- private key of second party
    SET @sym1 = asymmetric_derive(@pub1, @priv2);
    
    -- Or use public key of second party, private key of first party
    SET @sym2 = asymmetric_derive(@pub2, @priv1);
  • asymmetric_encrypt(algorithm, str, key_str)

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

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

    str 是要加密的字符串。该字符串的长度不能大于密钥字符串的长度减去 11(以 account for the padding)。

    key_str 是一个有效的 PEM 编码的 RSA 公钥或私钥。

    要恢复原始未加密的字符串,请将加密后的字符串传递给 asymmetric_decrypt(),连同用于加密的密钥对的另一部分。

    -- Generate private/public key pair
    SET @priv = create_asymmetric_priv_key('RSA', 1024);
    SET @pub = create_asymmetric_pub_key('RSA', @priv);
    
    -- Encrypt using private key, decrypt using public key
    SET @ciphertext = asymmetric_encrypt('RSA', 'The quick brown fox', @priv);
    SET @plaintext = asymmetric_decrypt('RSA', @ciphertext, @pub);
    
    -- 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, @priv), @pub) = @s
    asymmetric_decrypt('RSA', asymmetric_encrypt('RSA', @s, @pub), @priv) = @s
  • asymmetric_sign(algorithm, digest_str, priv_key_str, digest_type)

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

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

    digest_str 是摘要字符串。可以通过调用 create_digest() 生成摘要字符串。

    priv_key_str 是用于签名摘要字符串的私钥字符串。它可以是有效的 PEM 编码的 RSA 私钥或 DSA 私钥。

    digest_type 是用于签名数据的算法。支持的 digest_type 值是 'SHA224', 'SHA256', 'SHA384', 和 'SHA512'

    有关使用示例,请参阅 asymmetric_verify() 的描述。

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

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

    openssl_udf 共享库函数无法验证由 MySQL 8.0.30 中的 component_enterprise_encryption 函数生成的内容。

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

    digest_str 是摘要字符串。摘要字符串是必需的,可以通过调用 create_digest() 生成。

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

    pub_key_str 是签名者的公钥字符串。它对应于私钥,用于生成签名字符串。它必须是有效的 PEM 编码的 RSA 公钥或 DSA 公钥。

    digest_type 是用于签名数据的算法。支持的 digest_type 值是 'SHA224', 'SHA256', 'SHA384', 和 'SHA512'

    -- Set the encryption algorithm and digest type
    SET @algo = 'RSA';
    SET @dig_type = 'SHA224';
    
    -- Create private/public key pair
    SET @priv = create_asymmetric_priv_key(@algo, 1024);
    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_len|dh_secret})

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

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

    key_len 是 RSA 和 DSA 密钥的密钥长度(以位为单位)。如果您超过了最大允许的密钥长度或指定了小于最小的密钥长度,密钥生成将失败,结果为 null 输出。最小允许的密钥长度是 1,024 位,最大允许的密钥长度是 16,384 位对于 RSA 算法或 10,000 位对于 DSA 算法。这些密钥长度限制是 OpenSSL 强加的约束。服务器管理员可以通过设置 MYSQL_OPENSSL_UDF_RSA_BITS_THRESHOLD, MYSQL_OPENSSL_UDF_DSA_BITS_THRESHOLD, 和 MYSQL_OPENSSL_UDF_DH_BITS_THRESHOLD 环境变量来施加额外的限制。见 第 8.6.2 节,“配置 MySQL Enterprise Encryption”

    Note

    生成更长的密钥可能会消耗大量 CPU 资源。使用环境变量限制密钥长度可以在提供足够的安全性同时平衡资源使用。

    dh_secret 是一个共享的 DH 私钥,必须传递给 DH 密钥,而不是密钥长度。要创建秘密,请将密钥长度传递给 create_dh_parameters()

    这个示例创建了一个 2,048 位的 DSA 私钥,然后从私钥派生出公钥:

    SET @priv = create_asymmetric_priv_key('DSA', 2048);
    SET @pub = create_asymmetric_pub_key('DSA', @priv);

    有关 DH 密钥生成的示例,请参阅 asymmetric_derive() 的描述。

  • create_asymmetric_pub_key(algorithm, priv_key_str)

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

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

    priv_key_str 是一个有效的 PEM 编码的 RSA、DSA 或 DH 私钥。

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

  • create_dh_parameters(key_len)

    创建一个共享秘密以生成 DH 私钥/公钥对,并将其作为二进制字符串返回给 create_asymmetric_priv_key()。如果秘密生成失败,结果为 NULL

    key_len 是密钥长度。最小和最大密钥长度分别为 1,024 位和 10,000 位。这些密钥长度限制是 OpenSSL 强加的约束。服务器管理员可以通过设置 MYSQL_OPENSSL_UDF_RSA_BITS_THRESHOLDMYSQL_OPENSSL_UDF_DSA_BITS_THRESHOLDMYSQL_OPENSSL_UDF_DH_BITS_THRESHOLD 环境变量来施加额外的限制。请参阅 第 8.6.2 节,“配置 MySQL 企业加密”

    有关如何使用返回值生成对称密钥的示例,请参阅 asymmetric_derive() 的描述。

    SET @dhp = create_dh_parameters(1024);
  • create_digest(digest_type, str)

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

    生成的摘要字符串适合与 asymmetric_sign()asymmetric_verify() 一起使用。摘要是这些函数所需的。

    digest_type 是用于生成摘要字符串的摘要算法。支持的 digest_type 值为 'SHA224''SHA256''SHA384''SHA512'

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

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