Securing Data with Pluggable Cryptography

This chapter provides overviews of data security, pluggable cryptography, and the supported algorithms, and discusses how to:

Click to jump to parent topicUnderstanding Data Security

To understand pluggable cryptography, it's first necessary to understand the types of data security that cryptography in general can provide.

Data security comprises the following elements:

Privacy is normally implemented with some type of encryption. Integrity can be accomplished with simple checksums, or better, with more complex cryptographic checksums known as one-way hashes. Many times, this is combined with a type of asymmetric cryptography to produce digital signatures. These signatures, when verified, assure you that the data has not changed. Authentication can also be accomplished using digital signatures, which makes them an obvious choice for data security.

Click to jump to top of pageClick to jump to parent topicPrivacy Through Encryption

Encryption is the scrambling of information such that no one can read it unless they have a piece of data known as a key. Using the key, the sender encrypts plaintext to produce ciphertext. The recipient also uses a key to decrypt the ciphertext, producing the original plaintext. The type of key at either end of this transaction, and the way it's applied, constitute an encryption algorithm. In all cases, the security of an encryption algorithm should not rely on its secrecy. Rather, it should rely on how well the operations involved affect the input data.

Data encryption algorithms come in two major forms: Symmetric cryptography and asymmetric cryptography. Symmetric cryptography falls into two categories: Block ciphers and stream ciphers. The bulk of cryptographic research has gone into block ciphers, which are employed by PeopleSoft pluggable cryptography.

Symmetric Encryption

Symmetric encryption involves both encrypting and decrypting a piece of data using the same key. To make it a bit harder to crack symmetric encryption schemes, they can be applied in a number of encryption modes. These modes provide ways of applying encryption sequentially to blocks of data, such that each block is encrypted by a combination of the encryption key and the previously encrypted block. Of course, when encrypting the first block, a previously encrypted block isn't available, so the encryption software applies a random initialization vector (IV) to get the process started. This IV does not have to be secret.

The most popular symmetric encryption modes currently in use are:

There's a drawback with symmetric cryptography: The recipient of symmetrically encrypted ciphertext must posess the same key to decrypt it that you used to encrypt it. Because of this, you'll need a secure method of transmitting the key. This can be done a number of ways. You can send the key electronically over a private line that cannot be tapped; you can personally hand the key to your recipient; or you can use a courier to deliver the key. None of these approaches is foolproof or very efficient. A partial solution to this problem is asymmetric encryption.

Asymmetric Encryption

Asymmetric encryption involves the use of a pair of complementary keys, in which one key is used to encrypt a piece of data and the other key is used to decrypt it. This system uses public key encryption technology. The encryption key is called the public key and is widely distributed. The decryption key is the private key, which its owner must never reveal or transmit. Asymmetrically encrypted ciphertext is readable only by the owner of the private key. Anyone who wants to send ciphertext to that party needs only to have a copy of the recipient's freely available public key to perform the encryption.

Although asymmetric encryption is by design an excellent way for strangers to exchange data, it requires more computing power and capacity than symmetric encryption. Because of this, symmetric and asymmetric encryption are typically used in combination, to take advantage of the strengths of each system.

You apply the more efficient symmetric encryption to your data using a randomly generated symmetric key, which leaves only the problem of transmitting your symmetric key (also known as the content encryption key) to the recipient, who can use it to decrypt the ciphertext. You use the recipient's public key as a key encryption key, to apply asymmetric encryption to your symmetric key, not to your already encrypted ciphertext. The ciphertext and your symmetric key can now both be transmitted to the recipient. The recipient's private key is used to decrypt your symmetric key, which in turn is used to efficiently decrypt the ciphertext.

Click to jump to top of pageClick to jump to parent topicIntegrity Through Hashing

Integrity can be provided with a cryptographic hash. There are several well-known hash types, including MD2, MD4, MD5, SHA1, and RIPEMD160. These hash types have the following properties in common:

To use hashing, you generate a hash value from your data and include it when you transmit the data. The recipient uses the same hash algorithm to generate a hash value from the received data. If the result matches the transmitted hash, the data wasn't altered in transit.

Click to jump to top of pageClick to jump to parent topicAuthentication Using Digital Signatures

Authentication can be accomplished in a number of ways. These include:

Digital signatures are by far the most popular and most reliable method of authentication. Digital signatures usually combine a hash with another cryptographic operation (typically asymmetric encryption) to produce a type of check that not only verifies that the data was not altered in transit, but also assures that the named sender is, in fact, the actual sender of the data.

For example, if we provide a digital signature based on SHA1 with RSA encryption, this means that an SHA1 hash of the message was encrypted with the private key of the sender. Because the SHA1 hash is very collision resistant, and assuming the private key of the sender is known only by the sender, then verifying such a signature indicates that the message was not altered and that it was sent by the named sender.

Click to jump to parent topicUnderstanding Pluggable Cryptography

Pluggable cryptography provides a way for you to secure critical PeopleSoft data and communicate securely with other businesses. It enables you to extend and improve cryptographic support for your data in PeopleTools, giving you strong cryptography with the flexibility to change and grow, by incrementally acquiring stronger and more diverse algorithms for encrypting data. In PeopleTools, pluggable cryptography capability is provided by PeopleSoft pluggable encryption technology (PET).

Click to jump to top of pageClick to jump to parent topicPluggable Cryptography Features

You can encrypt any data used in your application by invoking PeopleCode to apply your preferred encryption algorithms. You can obtain these algorithms from various vendors' cryptographic libraries, using the capabilities you want from each library.

The features of pluggable cryptography include:

Click to jump to top of pageClick to jump to parent topicPluggable Cryptography Development

The functional elements of pluggable cryptography are:

To develop and use an encryption profile:

  1. Obtain an encryption library.

    The current release of PeopleTools includes the OpenSSL encryption library.

  2. Develop API glue code to access the encryption library's algorithms.

    PeopleTools includes glue code already developed to support the delivered OpenSSL encryption library, as well as glue code to support the PGP encryption library, which you can license from PGP Corporation to enable its functionality.

    The glue code combines with each library to create a plug-in accessible from PeopleCode. The plug-in can be an independent DLL file, or it can be incorporated into the encryption library file, which is the case with the delivered OpenSSL library.

    You can develop glue code to produce plug-in wrappers for other encryption libraries of your choice. The plug-ins make their APIs accessible to PeopleCode, and the new algorithms become as easily available as the delivered algorithms. You can find development information and examples of glue source code in PS_HOME\src\pspetssl and PS_HOME\src\pspetpgp.

  3. Load the encryption library's algorithms into the PET database, generate accompanying encryption keys, and insert them into the PET keystore.

  4. Define a chain of algorithms by selecting from the algorithms in the database.

    Because all algorithms are accessed from PeopleCode, you can combine algorithms from different libraries regardless of their source.

  5. Define an encryption profile, which is an instance of an algorithm chain applicable to a specific encryption task.

    With an encryption profile you can apply parameter values that differ from the default values.

  6. Test the encryption profile using the Test Encryption Profile page.

  7. Write PeopleCode to invoke the encryption profile.

    With the delivered glue code, you can take advantage of the capabilities of these libraries through a single PeopleCode object. The PeopleCode crypt class provides an interface into all algorithms loaded from the underlying encryption libraries.

Note. This documentation discusses how to use an encryption library for which glue code has already been developed and compiled, such as OpenSSL and PGP.

Click to jump to top of pageClick to jump to parent topicOpenSSL Library Considerations

The OpenSSL toolkit is delivered with its command line program installed and ready to use. The delivered OpenSSL encryption library supports a subset of the encryption algorithms that are included with the OpenSSL toolkit.

Note. As installed, the OpenSSL toolkit doesn't support the PKCS7 algorithms from the delivered OpenSSL encryption library. To use those algorithms, you must further configure the OpenSSL toolkit. Refer to the PeopleTools OpenSSL Setup Red Paper, located in PS_HOME\src\OpenSSL.

See Also

http://www.openssl.org/

Click to jump to top of pageClick to jump to parent topicPGP Library Considerations

If you license the PGP encryption library, you must ensure that its installed location is included in the paths used by both the application server and PeopleSoft Process Scheduler, as follows:

Note. PGP operations are supported only on platforms where the PGP SDK is supported: Windows, Solaris, and Red Hat Linux.

Click to jump to parent topicUnderstanding 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 is comprised of 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 the encryption profile, and they're 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.

See Also

Defining Encryption Profiles

Crypt Class

Click to jump to top of pageClick to jump to parent topicInternal Algorithms

Support for the following algorithms is provided by the PeopleCode crypt class. They're 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).

Click to jump to top of pageClick to jump to parent topicOpenSSL 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. They're available when you load the OpenSSL encryption library into the PET database.

Encoding

Following are the supported OpenSSL encoding algorithms.

Algorithm

Description

base64_encode

Encode data in base64 format.

base64_decode

Decode data from base64 format.

Hashing

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.

Symmetric Encryption

Following are 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.

Most of these algorithms use the same two parameters:

Digital Signature Handling

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:

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:

Secure Messaging — pkcs7_signed_sign

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

Secure Messaging — pkcs7_signed_verify

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

Secure Messaging — pkcs7_encrypted_encrypt

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_decrypt

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

Secure Messaging — pkcs7_signandencrypt_signandencrypt

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

Secure Messaging — pkcs7_signandencrypt_decryptandverify

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

Click to jump to top of pageClick to jump to parent topicPGP 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.

pgp_signed_sign

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

pgp_signed_verify

The pgp_signed_verify algorithm verifies a signed PGP message.

This algorithm has one parameter: SIGNERPUBLICKEY, which is 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-----".

pgp_encrypted_encrypt

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

pgp_encrypted_decrypt

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

pgp_signedandencrypted_signandencrypt

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

pgp_signedandencrypted_decryptandverify

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

See Also

Loading Encryption Libraries

Click to jump to top of pageClick to jump to parent topicAlgorithm 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, and the last algorithm must be PSAsciiToUnicode.

Click to jump to parent topicLoading Encryption Libraries

Select PeopleTools, Security, Encryption, Load Encryption Libraries to access the Load Encryption Libraries page.

Library File

Enter the filename of the selected encryption library for your operating system platform. The names of the delivered OpenSSL and PGP library files depend on the operating system platform where your application is installed.

Following are the encryption library filenames for each supported platform:

  • Microsoft Windows

    OpenSSL: pspetssl.dll

    PGP: pspetpgp.dll

  • Red Hat Linux

    OpenSSL: libpspetssl.so

    PGP: libpspetpgp.so

  • Sun Solaris

    OpenSSL: libpspetssl.so

    PGP: libpspetpgp.so

  • HP Tru64 Unix

    OpenSSL: libpspetssl.so

  • HP-UX

    OpenSSL: libpspetssl.sl

  • IBM AIX

    OpenSSL: libpspetssl.a

Load Library

Click to load the specified encryption library.

Each algorithm provided by the library appears in its own row with its algorithm ID. Its parameters each appear in a row, displaying the parameter's name and its default value.

If the From Keyset check box is selected, the parameter represents an encryption key. The pluggable cryptography facility uses the parameter's value to access the encryption key from the PET keystore.

Important! If the library you specified fails to load, you must sign out of your application, then shut down and restart the application server before signing back in.

Click to jump to parent topicDefining Algorithm Chains

Select PeopleTools, Security, Encryption, Algorithm Chain to access the Algorithm Chain page.

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, and the last algorithm must be PSAsciiToUnicode.

To define an algorithm chain:

  1. Open an existing algorithm chain or create a new one.

  2. Select the algorithm IDs of the algorithms you want to use in your chain.

    Add a new row for each algorithm. The available algorithms depend on the encryption libraries you previously loaded. You can select the algorithms in any order.

  3. Specify the operation sequence for your algorithm chain.

    Enter a number in the Sequence box for each algorithm. The lowest number designates the first algorithm, and the highest number designates the last. When you save the chain, the rows are resorted according to their sequence numbers.

  4. Save your algorithm chain definition.

Delivered Algorithm Chains

PeopleSoft delivers pluggable cryptography with the following predefined algorithm chains:

Algorithm Chain

Algorithms

3DES CBC B64 ENCRYPT

PSUnicodeToAscii

3des_ks168_cbc_encrypt

base64_encode

PSAsciiToUnicode

3DES CBC B64 DECRYPT

PSUnicodeToAscii

base64_decode

3des_ks168_cbc_decrypt

PSAsciiToUnicode

3DES CBC HEX ENCRYPT

PSUnicodeToAscii

3des_ks168_cbc_encrypt

PSHexEncode

PSAsciiToUnicode

3DES CBC HEX DECRYPT

PSUnicodeToAscii

PSHexDecode

3des_ks168_cbc_decrypt

PSAsciiToUnicode

PKCS7_ENCRYPTED

PSUnicodeToAscii

pkcs7_encrypted_encrypt

PSAsciiToUnicode

PKCS7_DECRYPTED

PSUnicodeToAscii

pkcs7_encrypted_decrypt

PSAsciiToUnicode

PKCS7_ENCRYPTED_SIGNED

PSUnicodeToAscii

pkcs7_signedandencrypted_signandencrypt

PSAsciiToUnicode

PKCS7_DECRYPTED_VERIFY

PSUnicodeToAscii

pkcs7_signedandencrypted_decryptandverify

PSAsciiToUnicode

PGP_ENCRYPTED

PSUnicodeToAscii

pgp_encrypted_encrypt

PSAsciiToUnicode

PGP_DECRYPTED

PSUnicodeToAscii

pgp_encrypted_decrypt

PSAsciiToUnicode

PGP_ENCRYPTED_SIGNED

PSUnicodeToAscii

pgp_signedandencrypted_signandencrypt

PSAsciiToUnicode

PGP_DECRYPTED_VERIFY

PSUnicodeToAscii

pgp_signedandencrypted_decryptandverify

PSAsciiToUnicode

Click to jump to parent topicDefining Algorithm Keysets

Select PeopleTools, Security, Encryption, Algorithm Keyset to access the Algorithm Keyset page.

Specify an algorithm ID or description to view the keyset of any algorithm in the PET database. Each row displays a key value. You can add, modify, or remove key values.

Keyset ID

Enter a name for the key value in the current row. each row must have a unique keyset ID for this algorithm.

Use Certificate Store Value

This option enables you to take advantage of key values already stored in the PeopleSoft keystore. Select a certificate alias from the keystore, then indicate whether the alias represents a certificate (for encryption) or a private key (for signing).

Warning! Certificates in the PeopleSoft keystore are in standard X.509 format, which is compatible for use with the internal and OpenSSL algorithms, but is not compatible with the PGP encryption library. If you're defining the keyset for a PGP algorithm, you must select the Use Entered Value radio button.

Use Entered Value

Select this option to use key values that aren't in the PeopleSoft keystore. Enter a key value that's formatted appropriately for the algorithm that you're configuring. This value will be entered into the PET keyset table, not the PeopleSoft keystore.

The value that you enter has a length that depends on the keysize of the cipher. For triple DES with keysize 112, this is 16 bytes. For a keysize of 168, this is 24 bytes. This value should be represented in hex notation.

You must generate the key value that you enter here. You can use any key generation utility capable of producing hex encoded keys of the required length. PeopleSoft delivers the core OpenSSL command line program precompiled and ready to use. You can use it to generate key values and perform other encryption-related tasks. The executable program is PS_HOME\bin\server\WINX86\openssl.exe on Windows, and PS_HOME/bin/openssl on Unix and Linux platforms.

Note. The key value that you enter here is stored in the PET keyset table using a combination of the algorithm ID and the keyset ID as its identifier. Because this combination is unique for each algorithm, you can create identically defined keyset rows for multiple algorithms.

See Also

OpenSSL Library Considerations

http://www.openssl.org/

Click to jump to parent topicDefining Encryption Profiles

Select PeopleTools, Security, Encryption, Encryption Profile to access the Encryption Profile page.

To define a new encryption profile, specify a new profile ID, then select an algorithm chain ID. Each algorithm in the chain appears in order, in its own row with its algorithm ID and chain sequence number. Its parameters each appear in a row, displaying the parameter's name and default value, and indicating whether the parameter represents a key. You can override a parameter's default value by editing it in the Parameter Value edit box.

Deleting an Encryption Profile

To delete an encryption profile, select PeopleTools, Security, Encryption, Delete Encryption Profile. Select the profile you want to delete, and click Delete on the Delete Encryption Profile page.

Click to jump to parent topicTesting Encryption Profiles

Select PeopleTools, Security, Encryption, Test Encryption Profile to access the Encryption Demo page.

Use this page ensure that your encryption profiles produce the expected results.

To test an encryption profile:

  1. Select the profile's encryption profile ID.

  2. In the Text to be Encrypted field, enter or paste the input text.

  3. Click Run Encryption Profile.

    The resulting output text appears in the Encrypted Text field.

You can use this page to test decryption as well. You can also test complementary pairs of profiles — one to encrypt, and the other to decrypt. By copying the result of the encryption profile test and pasting it as input to the decryption profile test, you can determine whether the text you get out is the same as the text you put in.

Click to jump to parent topicInvoking Encryption Profiles from PeopleCode

You access the encryption profile using the PeopleCode crypt class.

Following is an example of PET PeopleCode:

&cry = CreateObject("Crypt");
&bar = QE_CRYPT_WRK.CRYPT_PRFL_ID;
&cry.Open(&bar);
&cry.UpdateData(QE_CRYPT_WRK.DESCRLONG);
QE_CRYPT_WRK.LARGECHAR = &cry.Result;

See Also

Crypt Class