Cryptographic functions

Some cryptographic functions are available in Texis. The data parameters of these functions accept any type; base types other than char, byte, strlst, blob, or indirect are converted to varbyte first. Optional arguments may be given as empty string to indicate "no argument" when later arguments are specified. Problems that occur before a function can complete its main task - e.g. key not found, unknown algorithm, etc. - may result in SQL failure (and error message) and no return value, instead of the documented return type/value.

• createDigest(data, algorithm)

  Creates a message digest of data using algorithm, returned as a hexadecimal varchar string. The varchar algorithm argument must be a digest algorithm supported by the OpenSSL version used by Texis, e.g. sha1, sha224, sha256, sha384, sha512, md5. Added in version 8.01.1677277640 20230224.

• createDigestFromFile(file, algorithm)

  Same as createDigest(), but reads data from varchar file file instead. Added in version 8.01.1677277640 20230224.

• createDigitalSignature(data, privateKey[, keyId][, password][, algorithm])

  Creates a digital signature of data, returned as a base64url-encoded varchar string. The signature is signed by varchar private key privateKey using optional varchar digest algorithm algorithm (e.g. sha1, sha256; default defers to OpenSSL). The privateKey must be in PEM, JWK (JSON Web Key), or JWKS format. The optional varchar argument keyId specifies the id of the key in the JWK/JWKS privateKey set to use; the default is the first key. It is an error to give a key id for a PEM key, as the format does not support them. The optional varchar password is the password to decode the privateKey, if needed. Added in version 8.01.1679520426 20230322.

• createDigitalSignatureFromFile(file, privateKey[, keyId][, password][, algorithm])

  Same as createDigitalSignature(), but reads data from varchar file file instead. Added in version 8.01.1679520426 20230322.

• verifyDigitalSignature(data, signature, publicKey[, keyId][, password][, algorithm])

  Verifies that varchar base64url-encoded signature is a valid digital signature of data, using varchar public key publicKey. The publicKey must be in PEM, JWK, or JWKS format. Optional keyId, password, and algorithm arguments behave as with createDigitalSignature(). Returns int 1 if signature verified successfully; 0 if not; other values (e.g. negative) indicate a more serious verification failure. Added in version 8.01.1680108794 20230329.

• verifyDigitalSignatureFromFile(file, signature, publicKey[, keyId][, password][, algorithm])

  Same as verifyDigitalSignature(), but reads data from varchar file file instead. Added in version 8.01.1680108794 20230329.

• encryptWithPublicKey(data, publicKey[, keyId][, password])

  Encrypts data with public key publicKey, returning the crypt text as a base64url-encoded varchar string. The publicKey, keyId, and password arguments are supported as in verifyDigitalSignature(). Added in version 8.01.1680212739 20230330.

• decryptWithPrivateKey(data, privateKey[, keyId][, password])

  Decrypts base64url-encoded varchar data using private key privateKey. The privateKey, keyId, and password arguments are supported as in createDigitalSignature(). Added in version 8.01.1680212739 20230330.

• encrypt(data, algorithm, password[, digest][, iterations][, salt])

  Encrypts data using varchar symmetric-key cipher algorithm and varchar password password. Because arbitrarily large output is possible with symmetric-key ciphers, the ciphertext output is returned as unencoded varbyte data, unlike other Texis cryptographic functions that return relatively small fixed-size data (and thus base64url- or hex-encode it for convenience). Encoding to e.g. base64url is possible by stringformat('%pB')'ing (here) encrypt() output. The encrypt() return value format is also compatible with the openssl enc command for decryption outside of Texis if needed, with appropriate options.

  The varchar algorithm argument is a symmetric-key cipher algorithm supported by the OpenSSL version used by Texis, e.g. aes256 or des3. The symmetric key is derived from the varchar password argument using the PBKDF2 method. The optional varchar digest argument is the digest algorithm to use during key generation. It must be a value supported by the OpenSSL version used by Texis, e.g. sha256 or md5, and defaults to sha256. The optional int argument iterations is the number of iterations to use during key generation; it defaults to 10000. The optional varchar argument salt is the base64url-encoded 8-byte salt to use; the default is to generate a random salt and prepend it (with a token) to the output. Added in version 8.01.1681148317 20230410.

• encryptFile(inFile, outFile, algorithm, password[, digest][, iterations][, salt])

  Same as encrypt(), but reads plaintext from varchar file inFile and writes ciphertext output to varchar file outFile instead. Returns int 1 on success, 0 on error. Added in version 8.01.1681148317 20230410.

• decrypt(data, algorithm, password[, digest][, iterations][, salt])

  Decrypts ciphertext data using varchar symmetric-key cipher algorithm and varchar password password, returning unencoded varchar plaintext. The optional digest, iterations, and salt arguments are supported as in encrypt(). Added in version 8.01.1681148317 20230410.

• decryptFile(inFile, outFile, algorithm, password[, digest][, iterations][, salt])

  Same as decrypt(), but reads ciphertext from varchar file inFile and writes plaintext output to varchar file outFile instead. Returns int 1 on success, 0 on error. Added in version 8.01.1681148317 20230410.