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.
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. |
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 feedback mode. |
|
3des_ks112_cfb_decrypt |
Decrypt data using a key size of 112 bits, in cipher feedback mode. |
|
3des_ks112_ofb_encrypt |
Encrypt data using a key size of 112 bits, in output feedback mode. |
|
3des_ks112_ofb_decrypt |
Decrypt data using a key size of 112 bits, in output feedback 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 feedback mode. |
|
3des_ks168_cfb_decrypt |
Decrypt data using a key size of 168 bits, in cipher feedback mode. |
|
3des_ks168_ofb_encrypt |
Encrypt data using a key size of 168 bits, in output feedback mode. |
|
3des_ks168_ofb_decrypt |
Decrypt data using a key size of 168 bits, in output feedback 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 feedback mode. |
|
aes_ks128_cfb_encrypt |
Encrypt data using a key size of 128 bits, in cipher feedback 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 feedback mode. |
|
aes_ks128_ofb_encrypt |
Encrypt data using a key size of 128 bits, in output feedback 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 cipher block chaining mode. |
|
aes_ks192_cbc_encrypt |
Encrypt data using a key size of 192 bits, in cipher block chaining mode. |
|
aes_ks192_cfb_decrypt |
Decrypt data using a key size of 192 bits, in cipher feedback mode. |
|
aes_ks192_cfb_encrypt |
Encrypt data using a key size of 192 bits, in cipher feedback 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 feedback mode. |
|
aes_ks1928_ofb_encrypt |
Encrypt data using a key size of 192 bits, in output feedback 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 cipher block chaining mode. |
|
aes_ks256_cbc_encrypt |
Encrypt data using a key size of 256 bits, in cipher block chaining mode. |
|
aes_ks256_cfb_decrypt |
Decrypt data using a key size of 256 bits, in cipher feedback mode. |
|
aes_ks256_cfb_encrypt |
Encrypt data using a key size of 256 bits, in cipher feedback 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 feedback mode. |
|
aes_ks2568_ofb_encrypt |
Encrypt data using a key size of 256 bits, in output feedback 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 the “Symmetric Encryption Algorithms” section earlier in this topic for more information.
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 the “Symmetric Encryption Algorithms” section earlier in this topic for more information.
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.
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.
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.
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.