8.6.5 MySQL Enterprise Encryption Component Function Descriptions (original) (raw)

8.6.5 MySQL Enterprise Encryption Component Function Descriptions

In releases from MySQL 8.0.30, MySQL Enterprise Encryption's functions are provided by the MySQL componentcomponent_enterprise_encryption. This reference describes those functions.

For information on upgrading to the new component functions provided by the MySQL componentcomponent_enterprise_encryption, and a list of the behavior differences between the legacy functions and the component functions, seeUpgrading MySQL Enterprise Encryption.

The reference for the legacy functions in releases before MySQL 8.0.30 based on the openssl_udf shared library is Section 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.

MySQL Enterprise Encryption functions have these general characteristics:

• For arguments of the wrong type or an incorrect number of arguments, each function returns an error.
• If the arguments are not suitable to permit a function to perform the requested operation, it returnsNULL or 0 as appropriate. This occurs, for example, if a function does not support a specified algorithm, a key length is too short or long, or a string expected to be a key string in PEM format is not a valid key.
• The underlying SSL library takes care of randomness initialization.

The component functions only support the RSA encryption algorithm.

For additional examples and discussion, seeSection 8.6.3, “MySQL Enterprise Encryption Usage and Examples”.

• asymmetric_decrypt(algorithm,data_str,priv_key_str)
  Decrypts an encrypted string using the given algorithm and key string, and returns the resulting plaintext as a binary string. If decryption fails, the result isNULL.
  For the legacy version of this function in use before MySQL 8.0.29, seeSection 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.
  By default, thecomponent_enterprise_encryption function assumes that encrypted text uses the RSAES-OAEP padding scheme. The function supports decryption for content encrypted by the legacy openssl_udf shared library functions if the system variableenterprise_encryption.rsa_support_legacy_padding is set to ON (the default isOFF). When ON is set, the function also supports the RSAES-PKCS1-v1_5 padding scheme, as used by the legacy openssl_udf shared library functions. When OFF is set, content encrypted by the legacy functions cannot be decrypted, and the function returns null output for such content.
  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.
  datastr is the encrypted string to decrypt, which was encrypted withasymmetric_encrypt().
  privkeystr is a valid PEM encoded RSA private key. For successful decryption, the key string must correspond to the public key string used withasymmetric_encrypt() to produce the encrypted string. Theasymmetric_encrypt() component function only supports encryption using a public key, so decryption takes place with the corresponding private key.
  For a usage example, see the description ofasymmetric_encrypt().
• asymmetric_encrypt(algorithm,data_str,pub_key_str)
  Encrypts a string using the given algorithm and key string, and returns the resulting ciphertext as a binary string. If encryption fails, the result is NULL.
  For the legacy version of this function in use before MySQL 8.0.29, seeSection 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.
  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.
  datastr is the string to encrypt. The length of this string cannot be greater than the key string length in bytes, minus 42 (to account for the padding).
  pubkeystr is a valid PEM encoded RSA public key. Theasymmetric_encrypt() component function only supports encryption using a public key.
  To recover the original unencrypted string, pass the encrypted string to asymmetric_decrypt(), along with the other part of the key pair used for encryption, as in the following example:

-- 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);  

Suppose that:

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  

Then these identity relationships hold:

asymmetric_decrypt('RSA', asymmetric_encrypt('RSA', @s, @pub), @priv) = @s  

• asymmetric_sign(algorithm,text,priv_key_str,digest_type)
  Signs a digest string or data string using a private key, and returns the signature as a binary string. If signing fails, the result is NULL.
  For the legacy version of this function in use before MySQL 8.0.29, seeSection 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.
  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.
  text is a data string or digest string. The function accepts digests but does not require them, as it is also capable of handling data strings of an arbitrary length. A digest string can be generated by callingcreate_digest().
  privkeystr is the private key string to use for signing the digest string. It must be a valid PEM encoded RSA private key.
  digesttype is the algorithm to be used to sign the data. The supported_digesttype_ values are'SHA224', 'SHA256','SHA384', and 'SHA512' when OpenSSL 1.0.1 is in use. If OpenSSL 1.1.1 is in use, the additional digesttype values'SHA3-224', 'SHA3-256','SHA3-384', and'SHA3-512' are available.
  For a usage example, see the description ofasymmetric_verify().
• asymmetric_verify(algorithm,text,sig_str,pub_key_str,digest_type)
  Verifies whether the signature string matches the digest string, and returns 1 or 0 to indicate whether verification succeeded or failed. If verification fails, the result isNULL.
  For the legacy version of this function in use before MySQL 8.0.29, seeSection 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.
  By default, thecomponent_enterprise_encryption function assumes that signatures use the RSASSA-PSS signature scheme. The function supports verification for signatures produced by the legacy openssl_udf shared library functions if the system variableenterprise_encryption.rsa_support_legacy_padding is set to ON (the default isOFF). When ON is set, the function also supports the RSASSA-PKCS1-v1_5 signature scheme, as used by the legacy openssl_udf shared library functions. When OFF is set, signatures produced by the legacy functions cannot be verified, and the function returns null output for such content.
  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.
  text is a data string or digest string. The component function accepts digests but does not require them, as it is also capable of handling data strings of an arbitrary length. A digest string can be generated by calling create_digest().
  sigstr is the signature string to be verified. A signature string can be generated by callingasymmetric_sign().
  pubkeystr is the public key string of the signer. It corresponds to the private key passed to asymmetric_sign() to generate the signature string. It must be a valid PEM encoded RSA public key.
  digesttype is the algorithm that was used to sign the data. The supported_digesttype_ values are'SHA224', 'SHA256','SHA384', and 'SHA512' when OpenSSL 1.0.1 is in use. If OpenSSL 1.1.1 is in use, the additional digesttype values'SHA3-224', 'SHA3-256','SHA3-384', and'SHA3-512' are available.

-- 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)
  Creates a private key using the given algorithm and key length, and returns the key as a binary string in PEM format. The key is in PKCS #8 format. If key generation fails, the result is NULL.
  For the legacy version of this function in use before MySQL 8.0.29, seeSection 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.
  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.
  keylength is the key length in bits. If you exceed the maximum allowed key length or specify less than the minimum, key generation fails and the result is null output. The minimum allowed key length in bits is 2048. The maximum allowed key length is the value of theenterprise_encryption.maximum_rsa_key_size system variable, which defaults to 4096. It has a maximum setting of 16384, which is the maximum key length allowed for the RSA algorithm. SeeSection 8.6.2, “Configuring MySQL Enterprise Encryption”.
  Note
  Generating longer keys can consume significant CPU resources. Limiting the key length using theenterprise_encryption.maximum_rsa_key_size system variable lets you provide adequate security for your requirements while balancing this with resource usage.
  This example creates a 2048-bit RSA private key, then derives a public key from the private key:

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

• create_asymmetric_pub_key(algorithm,priv_key_str)
  Derives a public key from the given private key using the given algorithm, and returns the key as a binary string in PEM format. The key is in PKCS #8 format. If key derivation fails, the result is NULL.
  For the legacy version of this function in use before MySQL 8.0.29, seeSection 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.
  algorithm is the encryption algorithm used to create the key. The supported algorithm value is 'RSA'.
  privkeystr is a valid PEM encoded RSA private key.
  For a usage example, see the description ofcreate_asymmetric_priv_key().
• create_digest(digest_type,str)
  Creates a digest from the given string using the given digest type, and returns the digest as a binary string. If digest generation fails, the result is NULL.
  For the legacy version of this function in use before MySQL 8.0.29, seeSection 8.6.6, “MySQL Enterprise Encryption Legacy Function Descriptions”.
  The resulting digest string is suitable for use withasymmetric_sign() andasymmetric_verify(). The component versions of these functions accept digests but do not require them, as they are capable of handling data of an arbitrary length.
  digesttype is the digest algorithm to be used to generate the digest string. The supported_digesttype_ values are'SHA224', 'SHA256','SHA384', and 'SHA512' when OpenSSL 1.0.1 is in use. If OpenSSL 1.1.1 is in use, the additional digesttype values'SHA3-224', 'SHA3-256','SHA3-384', and'SHA3-512' are available.
  str is the non-null data string for which the digest is to be generated.

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