Skip to Main Content
Return to Navigation

Understanding the Supported Algorithms

This section discusses the minimum set of encryption algorithms supported by PeopleTools. Support for these algorithms is provided through the OpenSSL and PGP plug-ins, and internally through the PeopleCode crypt class.

Note: You use the crypt class to open an encryption profile, which comprises the chain of algorithms that you want to invoke. The crypt class then invokes the algorithms and applies their parameters as specified by the profile.

Some algorithms have accompanying parameters, some with default values, which are stored along with the algorithms in the PET database. You supply appropriate parameter values in an encryption profile, and they are used when the algorithm is invoked.

Each algorithm returns data appropriate to its purpose, using properties provided by the crypt class. The Result property is used to make output data available from algorithms that produce or transform data by encoding, decoding, encryption, decryption, generating hash values, or generating signatures. The Verified property conveys the success or failure of algorithms that verify the input data.

Internal Algorithms

Support for the following algorithms is provided by the PeopleCode crypt class. They are automatically available for inclusion in your algorithm chains.

Algorithm

Description

PSUnicodeToAscii

Convert Unicode text to ASCII.

PSAsciiToUnicode

Convert ASCII text to Unicode.

PSHexEncode

Convert octets (bytes) into ASCII hex nibbles.

PSHexDecode

Convert ASCII hex nibbles (with a leading 0x) into binary octets (bytes).

PSUnicodeToAscii_Generic_ENC

 

Convert Unicode text to ASCII

Note: Use when encrypting data across multiple platforms where one platform is OS390. This algorithm functions the same as PSUnicodeToAscii on all platforms other than OS390.

PSAsciiToUnicode_Generic_DEC

 

Convert ASCII text to Unicode

Note: Use when performing cross-platform decryption where one platform is OS390. This algorithm functions the same as PSAsciiToUnicode on all platforms other than .OS390.

OpenSSL Algorithms

This section describes the algorithms supported by the OpenSSL plug-in, including encoding algorithms, hashing algorithms, symmetric encryption algorithms, digital signature algorithms, and the individual secure messaging algorithms. These algorithms are available when you load the OpenSSL encryption library into the PET database.

Encoding Algorithms

Following are the supported OpenSSL encoding algorithms.

Algorithm

Description

base64_encode

Encode data in base64 format.

base64_decode

Decode data from base64 format.

Hashing Algorithms

Following are the supported OpenSSL hashing algorithms.

Algorithm

Description

md2_generate

Generate an MD2 hash value from the input data.

md4_generate

Generate an MD4 hash value.

md5_generate

Generate an MD5 hash value.

sha1_generate

Generate an SHA1 hash value.

ripemd160_generate

Generate a RIPEMD160 hash value.

hmac_sha1_generate

Generate a hash message authentication code SHA1 hash value.

HMAC encryption takes a SECRETKEY parameter. The parameter is not required, but if supplied it must be defined in the keyset (similar to SYMMETRIC_KEY for other algorithms). The value specified must begin with 0x. The value should be at least eight bytes (64 bits). It should be random but its secrecy isn't critical. For example: 0x0102030405060708. The longer the value the more secure the hash output.

Symmetric Encryption Algorithms

This table describes the supported OpenSSL symmetric encryption algorithms, which implement triple Data Encryption Standard (DES) encryption with various key sizes and modes.

Algorithm Name

Description

3des_ks112_ecb_encrypt

Encrypt data using a key size of 112 bits, in electronic code book mode.

3des_ks112_ecb_decrypt

Decrypt data using a key size of 112 bits, in electronic code book mode.

3des_ks112_cbc_encrypt

Encrypt data using a key size of 112 bits, in cipher block chaining mode.

3des_ks112_cbc_decrypt

Decrypt data using a key size of 112 bits, in cipher block chaining mode.

3des_ks112_cfb_encrypt

Encrypt data using a key size of 112 bits, in cipher feed back mode.

3des_ks112_cfb_decrypt

Decrypt data using a key size of 112 bits, in cipher feed back mode.

3des_ks112_ofb_encrypt

Encrypt data using a key size of 112 bits, in output feed back mode.

3des_ks112_ofb_decrypt

Decrypt data using a key size of 112 bits, in output feed back mode.

3des_ks168_ecb_encrypt

Encrypt data using a key size of 168 bits, in electronic code book mode.

3des_ks168_ecb_decrypt

Decrypt data using a key size of 168 bits, in electronic code book mode.

3des_ks168_cbc_encrypt

Encrypt data using a key size of 168 bits, in cipher block chaining mode.

3des_ks168_cbc_decrypt

Decrypt data using a key size of 168 bits, in cipher block chaining mode.

3des_ks168_cfb_encrypt

Encrypt data using a key size of 168 bits, in cipher feed back mode.

3des_ks168_cfb_decrypt

Decrypt data using a key size of 168 bits, in cipher feed back mode.

3des_ks168_ofb_encrypt

Encrypt data using a key size of 168 bits, in output feed back mode.

3des_ks168_ofb_decrypt

Decrypt data using a key size of 168 bits, in output feed back mode.

The following tables describe the supported OpenSSL symmetric encryption algorithms which implement Advanced Encryption Security (AES) encryption with various key sizes and modes. The information is divided by key size for ease of use.

The following table describes AES encryption algorithms that use a key size of 128 bits:

Algorithm Name

Description

aes_ks128_cbc_decrypt

Decrypt data using a key size of 128 bits, in cipher block chaining mode.

aes_ks128_cbc_encrypt

Encrypt data using a key size of 128 bits, in cipher block chaining mode.

aes_ks128_cfb_decrypt

Decrypt data using a key size of 128 bits, in cipher feed back mode.

aes_ks128_cfb_encrypt

Encrypt data using a key size of 128 bits, in cipher feed back mode.

aes_ks128_ecb_decrypt

Decrypt data using a key size of 128 bits, in electronic code book mode.

aes_ks128_ecb_encrypt

Encrypt data using a key size of 128 bits, in electronic code book mode.

aes_ks128_ofb_decrypt

Decrypt data using a key size of 128 bits, in output feed back mode.

aes_ks128_ofb_encrypt

Encrypt data using a key size of 128 bits, in output feed back mode.

The following table describes AES encryption algorithms that use a key size of 192 bits:

Algorithm Name

Description

aes_ks192_cbc_decrypt

Decrypt data using a key size of 192 bits, in electronic code book mode.

aes_ks192_cbc_encrypt

Encrypt data using a key size of 192 bits, in electronic code book mode.

aes_ks192_cfb_decrypt

Decrypt data using a key size of 192 bits, in cipher feed back mode.

aes_ks192_cfb_encrypt

Encrypt data using a key size of 192 bits, in cipher feed back mode.

aes_ks192_ecb_decrypt

Decrypt data using a key size of 192 bits, in electronic code book mode.

aes_ks192_ecb_encrypt

Encrypt data using a key size of 192 bits, in electronic code book mode.

aes_ks192_ofb_decrypt

Decrypt data using a key size of 192 bits, in output feed back mode.

aes_ks1928_ofb_encrypt

Encrypt data using a key size of 192 bits, in output feed back mode.

The following table describes AES encryption algorithms that use a key size of 256 bits:

Algorithm Name

Description

aes_ks256_cbc_decrypt

Decrypt data using a key size of 256 bits, in electronic code book mode.

aes_ks256_cbc_encrypt

Encrypt data using a key size of 256 bits, in electronic code book mode.

aes_ks256_cfb_decrypt

Decrypt data using a key size of 256 bits, in cipher feed back mode.

aes_ks256_cfb_encrypt

Encrypt data using a key size of 256 bits, in cipher feed back mode.

aes_ks256_ecb_decrypt

Decrypt data using a key size of 256 bits, in electronic code book mode.

aes_ks256_ecb_encrypt

Encrypt data using a key size of 256 bits, in electronic code book mode.

aes_ks256_ofb_decrypt

Decrypt data using a key size of 256 bits, in output feed back mode.

aes_ks2568_ofb_encrypt

Encrypt data using a key size of 256 bits, in output feed back mode.

Most of these algorithms use the same two parameters:

  • IV (Initialization Vector)

    This parameter isn't used by the listed ECB mode algorithms. Specify a hex encoded value to use to alter the first plaintext block of data before it's encrypted. This value serves as an encryption seed value, which must be applied for both encryption and decryption. The value must be the length of the cipher's blocksize — eight bytes for triple DES. It should be random but its secrecy isn't critical. For example: 0x0102030405060708

  • SYMMETRIC_KEY

    Specify as a string the keyset ID of the symmetric encryption key to be used with this algorithm. This parameter must identify a key that's stored in the PET keyset database.

Note: All algorithm chains that use 3 DES encryption algorithms must include either the base64_encode or PSHexEncode algorithm as a step in the encryption algorithm chain. All algorithm chains that use 3 DES decryption algorithms must include the corresponding base64_decode or PSHexDecode algorithm as a step in the decryption algorithm chain.

Digital Signature Handling Algorithms

Following are the supported OpenSSL algorithms for generating signatures.

Algorithm Name

Description

rsa_md5_sign

Generate an RSA signature using an MD5 hash.

rsa_sha1_sign

Generate an RSA signature using an SHA1 hash.

dsa_sha1_sign

Generate a DSA signature.

The signing algorithms all use the same parameters:

  • SIGNERPRIVATEKEY

    Specify, as a string, the keyset ID that represents the signer's private key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN xxx PRIVATE KEY-----" where xxx is either RSA or DSA, depending on the algorithm.

  • SIGNERPKPASSPHRASE

    Specify the pass phrase used to decrypt and unlock the signer's private key. This parameter's value is the actual pass phrase.

Note: The output of these algorithms must be a hex encoded signature if it is going to be used as the SIGNATURE parameter value for the Verify routine. To generate a Hex value a PSHexEncode algorithm must be the second to the last step in the chain.

Following are the supported OpenSSL algorithms for verifying signatures.

Algorithm Name

Description

rsa_md5_verify

Verify an RSA signature based on an MD5 hash.

rsa_sha1_verify

Verify an RSA signature based on an SHA1 hash.

dsa_sha1_verify

Verify a DSA-hashed signature.

The verifying algorithms all use the same parameters:

  • SIGNERCERT

    Specify, as a string, the keyset ID that represents the signer's certificate in the PET keyset database. The actual certificate stored in the keyset database is an X.509 certificate. Its value should begin "-----BEGIN CERTIFICATE-----".

    Note: The API implementation of the rsa_sha1_verify algorithm requires that the Public Key be certified.

  • SIGNATURE

    Specify, as a string, the hex encoded signature that's delivered with the input data or that's returned as the result of invoking a signing algorithm.

    Note: The system expects all hex encoded values to begin with 0x. If the hex encoded signature value does not begin with these two characters, you must manually prepend 0x to it or the signature will be invalid.

Secure Messaging — pkcs7_signed_sign

The pkcs7_signed_sign algorithm generates a signed PKCS7 message. The parameters are:

  • SIGNERCERT

    Specify, as a string, the keyset ID that represents the signer's certificate in the PET keyset database. The actual certificate stored in the keyset database is an X.509 certificate. Its value should begin "-----BEGIN CERTIFICATE-----".

  • SIGNERPRIVATEKEY

    Specify, as a string, the keyset ID that represents the signer's private key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN xxx PRIVATE KEY-----" where xxx is either RSA or DSA.

  • SIGNERPKPASSPHRASE

    Specify the pass phrase used to decrypt and unlock the signer's private key. This parameter's value is the actual pass phrase.

Secure Messaging — pkcs7_signed_verify

The pkcs7_encrypted_encrypt algorithm generates an encrypted PKCS7 message.

This algorithm has one parameter: SIGNERCERT, which is the keyset ID that represents the signer's X.509 certificate in the PET keyset database. The value stored in the keyset database should begin with the line "-----BEGIN CERTIFICATE-----".

Secure Messaging — pkcs7_encrypted_encrypt

The pkcs7_signed_verify algorithm verifies a signed PKCS7 message. The parameters are:

  • RECIPIENT

    Specify, as a string, the keyset ID that represents the recipient's certificate in the PET keyset database. The actual certificate stored in the keyset database is an X.509 certificate. Its value should begin "-----BEGIN CERTIFICATE-----".

  • SYMMETRIC_ALGORITHM

    Specify the name of the symmetric algorithm used for content encryption. This must be a symmetric encryption algorithm supported by an encryption plug-in.

    See Symmetric Encryption Algorithms.

Secure Messaging — pkcs7_encrypted_decrypt

The pkcs7_encrypted_decrypt algorithm decrypts an encrypted PKCS7 message. The parameters are:

  • RECIPIENTCERT

    Specify, as a string, the keyset ID that represents the recipient's certificate in the PET keyset database. The actual certificate in the keyset database should begin with the line "-----BEGIN CERTIFICATE-----"

  • RECIPIENTPRIVATEKEY

    Specify, as a string, the keyset ID that represents the recipient's private key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN xxx PRIVATE KEY-----" where xxx is either RSA or DSA.

  • RECIPIENTPKPASSPHRASE

    Specify the pass phrase used to decrypt and unlock the recipient's private key. This parameter's value is the actual pass phrase.

Secure Messaging — pkcs7_signandencrypt_signandencrypt

The pkcs7_signandencrypt_signandencrypt algorithm generates a signed and encrypted PKCS7 message. The parameters are:

  • SIGNERCERT

    Specify, as a string, the keyset ID that represents the signer's certificate in the PET keyset database. The actual certificate stored in the keyset database is an X.509 certificate. Its value should begin "-----BEGIN CERTIFICATE-----".

  • SIGNERPRIVATEKEY

    Specify, as a string, the keyset ID that represents the signer's private key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN xxx PRIVATE KEY-----" where xxx is either RSA or DSA.

  • SIGNERPKPASSPHRASE

    Specify the pass phrase used to decrypt and unlock the signer's private key. This parameter's value is the actual pass phrase.

  • RECIPIENT

    Specify, as a string, the keyset ID that represents the recipient's certificate in the PET keyset database. The actual certificate stored in the keyset database is an X.509 certificate. Its value should begin "-----BEGIN CERTIFICATE-----".

  • SYMMETRIC_ALGORITHM

    Specify the name of the symmetric algorithm used for content encryption. This must be a symmetric encryption algorithm supported by an encryption plug-in.

    See Symmetric Encryption Algorithms.

Secure Messaging — pkcs7_signandencrypt_decryptandverify

The pkcs7_signandencrypt_decryptandverify algorithm decrypts and verifies an encrypted PKCS7 message. The parameters are:

  • SIGNERCERT

    Specify, as a string, the keyset ID that represents the signer's certificate in the PET keyset database. The actual certificate stored in the keyset database is an X.509 certificate. Its value should begin "-----BEGIN CERTIFICATE-----".

  • RECIPIENTCERT

    Specify, as a string, the keyset ID that represents the recipient's certificate in the PET keyset database. The actual certificate in the keyset database should begin with the line "-----BEGIN CERTIFICATE-----".

  • RECIPIENTPRIVATEKEY

    Specify, as a string, the keyset ID that represents the recipient's private key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN xxx PRIVATE KEY-----" where xxx is either RSA or DSA.

  • RECIPIENTPKPASSPHRASE

    Specify the pass phrase used to decrypt and unlock the recipient's private key. This parameter's value is the actual pass phrase.

PGP Algorithms

This section describes the secure messaging algorithms supported by the delivered PGP glue code. The messaging algorithms are available when you license the PGP encryption library from PGP Corporation, compile the glue code, and load the library into the PET database.

Note that the delivered PGP glue code has been tested on the Microsoft Windows environment only.

pgp_signed_sign

The pgp_signed_sign algorithm generates a signed PGP message. The parameters are:

  • SIGNERPRIVATEKEY

    Specify, as a string, the keyset ID that represents the signer's private key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN PGP PRIVATE KEY BLOCK-----".

  • SIGNERKID

    Specify, as a string, the PGP key ID for the signer's key. It's a hex encoded 32 bit value, for example, 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

  • SIGNERPKPASSPHRASE

    Specify the pass phrase used to decrypt the signer's private key. This parameter's value is the actual pass phrase.

  • CLEARSIGN

    Specify a numeric value indicating whether the message is to be clearsigned. A clearsigned message should remain readable. If you specify a value of 1, the message remains as is and a radix 64 armored signature block is appended to the message. If you specify a value of 0, the signature block is appended and the entire message is radix 64 armored.

pgp_signed_verify

The pgp_signed_verify algorithm verifies a signed PGP message. The parameters are:

  • SIGNERPUBLICKEY

    Specify the keyset ID that represents the signer's PGP Public key in the PET keyset database. The value stored in the keyset database should begin with the line "-----BEGIN PGP PUBLIC KEY BLOCK-----".

  • SIGNERKID

    Specify, as a string, the PGP key ID for the signer's key. It's a hex encoded 32 bit value, for example, 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

pgp_encrypted_encrypt

The pgp_encrypted_encrypt algorithm generates an encrypted PGP message. The parameters are:

  • RECIPIENTPUBLICKEY

    Specify, as a string, the keyset ID that represents the recipient's public key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN PGP PUBLIC KEY BLOCK-----".

  • RECIPIENTKID

    Specify, as a string, the PGP key ID for the recipient's key. It's a hex encoded 32 bit value, for example 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

pgp_encrypted_decrypt

The pgp_encrypted_decrypt algorithm decrypts an encrypted PGP message. The parameters are:

  • RECIPIENTPRIVATEKEY

    Specify, as a string, the keyset ID that represents the recipient's private key in the PET keyset database. The actual value in the keyset database should begin "-----BEGIN PGP PRIVATE KEY BLOCK-----".

  • RECIPIENTPKPASSPHRASE

    Specify the pass phrase used to decrypt the recipient's private key. This parameter's value is the actual pass phrase.

  • RECIPIENTPUBLICKEY

    Specify, as a string, the keyset ID that represents the recipient's public key in the PET keyset database. The actual value in the keyset database should begin "-----BEGIN PGP PUBLIC KEY BLOCK-----".

  • RECIPIENTKID

    Specify, as a string, the PGP key ID for the recipient's key. It's a hex encoded 32 bit value, for example 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

pgp_signedandencrypted_signandencrypt

The pgp_signedandencrypted_signandencrypt algorithm generates a signed and encrypted PGP message. The parameters are:

  • SIGNERPRIVATEKEY

    Specify, as a string, the keyset ID that represents the signer's private key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN PGP PRIVATE KEY BLOCK-----".

  • SIGNERKID

    Specify, as a string, the PGP key ID for the signer's key. It's a hex encoded 32 bit value, for example 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

  • SIGNERPKPASSPHRASE

    Specify the pass phrase used to decrypt the signer's private key. This parameter's value is the actual pass phrase.

  • RECIPIENTPUBLICKEY

    Specify, as a string, the keyset ID that represents the recipient's public key in the PET keyset database. The actual value in the keyset database should begin "-----BEGIN PGP PUBLIC KEY BLOCK-----".

  • RECIPIENTKID

    Specify, as a string, the PGP key ID for the recipient's key. It's a hex encoded 32 bit value, for example 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

  • CLEARSIGN

    Specify a numeric value indicating whether the message is to be clearsigned. A clearsigned message should remain readable. If you specify a value of 1, the message remains as is and a radix 64 armored signature block is appended to the message. If you specify a value of 0, the signature block is appended and the entire message is radix 64 armored.

pgp_signedandencrypted_decryptandverify

The pgp_signedandencrypted_decryptandverify algorithm decrypts and verifies a signed and encrypted PGP message. The parameters are as follows:

  • RECIPIENTPRIVATEKEY

    Specify, as a string, the keyset ID that represents the recipient's private key in the PET keyset database. The actual value in the keyset database should begin "-----BEGIN PGP PRIVATE KEY BLOCK-----".

  • RECIPIENTPKPASSPHRASE

    Specify the pass phrase used to decrypt the recipient's private key. This parameter's value is the actual pass phrase.

  • RECIPIENTPUBLICKEY

    Specify, as a string, the keyset ID that represents the recipient's public key in the PET keyset database. The actual value in the keyset database should begin "-----BEGIN PGP PUBLIC KEY BLOCK-----".

  • RECIPIENTKID

    Specify, as a string, the PGP key ID for the recipient's key. It's a hex encoded 32 bit value, for example 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

  • SIGNERPUBLICKEY

    Specify, as a string, the keyset ID that represents the signer's public key in the PET keyset database. The actual key value in the keyset database should begin "-----BEGIN PGP PUBLIC KEY BLOCK-----".

  • SIGNERKID

    Specify, as a string, the PGP key ID for the signer's key. It's a hex encoded 32 bit value, for example 0xAB01D6A5. You can obtain this value from the PGP-based tool that created the key.

Algorithm Chain Considerations

Although you can select any sequence of algorithms to define a chain, many possible sequences don't work because the cumulative effect of the algorithms doesn't make any sense. You must define sequences of compatible algorithms.

To apply any of the supported algorithms for symmetric encryption, hashing, encoding, or secure messaging, the input data must be in ASCII text format. Because PeopleSoft stores data in Unicode format, the first algorithm in most chains must be PSUnicodeToAscii or PSUnicodeToAscii_Generic_ENC, and the last algorithm must be PSAsciiToUnicode or PSAsciiToUnicode_Generic_DEC.

Cross Platform Algorithm Chain Considerations

When encrypting and decrypting data across multiple platforms where OS390 is one of two or more platforms, the PSUnicodeToAscii_Generic_ENC algorithm must be the first algorithm in the encrypting algorithm chain. Conversely, PSAsciiToUnicode_Generic_DEC must be the last algorithm in the decrypting algorithm chain.

Note: If all participating encrypting and decrypting systems are on the OS390 platform, it is not necessary to use the generic algorithms. If none of the encrypting and decrypting systems in a cross platforms scenario are on the OS390 platform, the PSUnicodeToAscii_Generic_ENC algorithm functions exactly like the PSUnicodeToAscii algorithm and the PSAsciiToUnicode_Generic_DEC algorithm functions exactly like the PSAsciiToUnicode algorithm.

Important! If you modify current algorithm chains by replacing the PSUnicodeToAscii or the PSAsciiToUnicode algorithms with the PSUnicodeToAscii_Generic_ENC or the PSAsciiToUnicode_Generic_DEC algorithms, respectively, currently stored encrypted data on the OS390 DB must be unencrypted using the original decryption chain and reencrypted with the new encryption chain.