Pretty Good Privacy

The Pretty Good Privacy (PGP) connector provides a set of built-in PGP services, which can be used to encrypt, decrypt, sign, and verify the stream or bytes of data.

Actions

  • decrypt: Decrypts the encrypted data and returns plain data as a stream object or a byte array.

    Input Parameters

    • data: Document - The data that you want to decrypt must be in one of the following formats. If multiple input parameters are supplied for data, the service throws an exception stating that only one parameter must be passed.

    • string: String Optional - The string that you want to decrypt.

    • stream: java.io.InputStream Optional - The stream data that you want to decrypt.

    • bytes: byte[ ] Optional - The byte array that you want to decrypt.

    • loadAs: String Optional - The format in which the service returns the output. By default, the type is set to bytes. Set this parameter to: bytes to return the output as a byte array, or stream to return the output as a stream object.

    • secretKey: The secret key used to extract the private key necessary for decrypting the data. You must provide either secretKeyBytes or secretKeyAlias. secretKeyBytes (byte[]): Optional - The secret key file in byte format. secretKeyPassphrase (String): The password required to extract the private key from the secret key, typically provided during the key's generation.

      Note: Secret key files have a .asc extension.

    Output Parameters

    • stream: java.io.OutputStream Conditional - Decrypted data in the form of an output stream, when the stream input parameter is provided.

    • bytes: byte[ ] Conditional - Decrypted data in bytes, when the bytes input parameter is provided.

    • status: String - Indicates whether the data is successfully decrypted or not. If successful, status is success. Otherwise, status contains failure along with an error message.

    Usage Notes

    Prerequisites to use the decrypt service:

    • Generate a public-secret key pair for IBM® webMethods Integration.

    • Make sure that the external system that sends the encrypted data has access to the IBM webMethods Integration public key to encrypt the data.

    • Authentication keys used in this service must be in the PGP format and generated using the RSA encryption algorithm.

    Decryption works as follows:

    1. The external system sends the data encrypted with the IBM webMethods Integration public key.

    2. IBM webMethods Integration receives the data and passes it to the decrypt service.

    3. The decrypt service uses the private key to decrypt the data.

    4. The service returns the decrypted data.

  • decryptAndVerify: Decrypts the encrypted data and verifies the associated digital signature.

    Input Parameters

    • data: Document - The data that you want to decrypt and verify must be in one of the following formats. If multiple input parameters are supplied for data, the service throws an exception stating that only one parameter must be passed.

      • string: String Optional - The string that you want to decrypt and verify.

      • stream: java.io.InputStream Optional - The stream data that you want to decrypt and verify.

      • bytes: byte[ ] Optional - The byte array that you want to decrypt and verify.

    • loadAs: String Optional - The format in which the service returns the output. Set to:

      • bytes to return the output as a byte array. This is the default.

      • stream to return the output as a stream object.

    • secretKey: Document - The secret key to extract the private key required to decrypt the data. Provide either secretKeyBytes or secretKeyAlias.

      • secretKeyBytes: byte[ ] Optional - The secret key file in bytes.

        Note: Secret key files have a .asc extension.

      • secretKey ​Passphrase: String - Password required to extract the private key from the secret key. This is the password provided while generating the secret key.

    • publicKey: Document - The public key required to verify the digital signature associated with the data.

      • publicKeyBytes: byte[ ] Optional - The public key file in bytes.

      Note: Public key files have a .asc extension.

    Output Parameters

    • stream: java.io.OutputStream Conditional - Decrypted and verified data in the form of an output stream, when the stream input parameter is provided.

    • bytes: byte[ ] Conditional - Decrypted and verified data in bytes, when the bytes input parameter is provided.

    • verified: Boolean - Indicates whether the signature associated with the data is verified or not. A value of:

      • true indicates that the signed data is verified.

      • false indicates that the signed data is not verified.

    • status: String - Indicates whether the data is successfully decrypted and verified. If successful, status is success. Otherwise, status contains failure along with an error message.

    Usage Notes

    Use the decryptAndVerify service when an external system connected to IBM webMethods Integration requires decrypted data with verified signature.

    Prerequisites to use the decryptAndVerify service:

    • Generate a public-secret key pair for IBM webMethods Integration.

    • Make sure that the external system has access to the IBM webMethods Integration public key.

    • Make sure that IBM webMethods Integration has access to external’s system’s public key.

    Decryption and verification works as follows:

    1. The external system sends the data encrypted with the IBM webMethods Integration public key and signed with its secret key.

    2. IBM webMethods Integration receives the data and passes it to the decryptAndVerify service.

    3. The service uses the private key extracted from the secret key to decrypt the data.

    4. The service then uses the external system’s public key to verify the signature of the decrypted data.

    5. The service returns the decrypted and verified data.

  • encrypt: Converts plain data to encrypted data.

    Input Parameters

    • data: Document - Data that you want to encrypt. The data must be in one of the following formats. If multiple input parameters are supplied for data, the service throws an exception stating that only one parameter must be passed: string (Optional) - The string that you want to encrypt, stream (Optional) - The stream data that you want to encrypt, bytes (Optional) - The byte array that you want to encrypt.

    • loadAs: String (Optional) - The format in which the service returns the output. Set to bytes to return the output as a byte array (this is the default), or stream to return the output as a stream object.

    • publicKey: Document - The public key required to encrypt the data: publicKeyBytes (Optional) - The public key file in bytes.

      Note: Public key files have a .asc extension.

    • encryption Algorithm: String - The symmetric key encryption algorithm to use. select one of the following encryption algorithms: AES_192, AES_256, BLOWFISH, IDEA, TRIPLE_DES, or TWOFISH.

      The default value is AES_256.

    Output Parameters

    • stream: java.io.OutputStream Conditional - Encrypted data in the form of an output stream, when the stream input parameter is provided.

    • bytes: byte[ ] Conditional - Encrypted data in bytes, when the bytes input parameter is provided.

    • status: String - Indicates whether the data is successfully encrypted or not. If successful, status is success. Otherwise, status contains failure along with an error message.

    Usage Notes

    Before encrypted data is exchanged between IBM webMethods Integration and an external system, the external system must share its public key.

    The public key is passed to the encrypt service, which returns the encrypted data to IBM webMethods Integration.

    Authentication keys used in this service must be in the PGP format and generated using the RSA encryption algorithm.

  • sign: Adds a digital signature to data.

    Input Parameters

    • data: Document - Data that you want to sign. The data must be in one of the following formats. If multiple input parameters are supplied for data, the service throws an exception stating that only one parameter must be passed.

      • string: String Optional - The string that you want to sign.

      • stream: java.io.InputStream Optional - The stream data that you want to sign.

      • bytes: byte[ ] Optional - The byte array that you want to sign.

    • loadAs: String Optional - The format in which the service returns the output. Set to:

      • bytes to return the output as a byte array. This is the default.

      • stream to return the output as a stream object.

    • secretKey: Document - The secret key required to sign the data.

      • secretKeyBytes: byte[ ] Optional - The secret key file in bytes.
        Note: Secret key files have a .asc extension.

      • secretKey ​Passphrase: String - Password required to extract the private key from the secret key. This is the password provided while generating the secret key.

    • signingAlgorithm: String - The signing algorithm to use; select one of the following: MD5, SHA256, SHA384, or SHA512. The default value is SHA256.
      Note: If the secret key for signing the data is of the DSA (Digital Signature Algorithm) key type, this service does not support the MD5 signing algorithm.

    Output Parameters

    • stream: java.io.OutputStream Conditional - Signed data in the form of an output stream, when the stream input parameter is provided.

    • bytes: byte[ ] Conditional - Signed data in bytes, when the bytes input parameter is provided.

    • status: String - Indicates whether the data is successfully signed or not. If successful, status is success. Otherwise, status contains failure along with an error message.

    Usage Notes

    The sign service does not support a detached signature.

  • signAndEncrypt: Encrypts and add a digital signature to data.

    Output Parameters

    • stream: java.io.OutputStream Conditional - Signed and encrypted data in the form of an output stream, when the stream input parameter is provided.

    • bytes: byte[ ] Conditional - Signed and encrypted data in bytes, when the bytes input parameter is provided.

    • status: String - Indicates whether the data is successfully signed and encrypted or not. If successful, status is success. Otherwise, status contains failure along with an error message.

    Usage Notes

    Use the signAndEncrypt service when an external system connected to IBM webMethods Integration requires signed and encrypted data.

    Prerequisites to use the signAndEncrypt service:

    • Make sure that IBM webMethods Integration has access to the external system’s public key to encrypt data.

    • Generate a secret key for IBM webMethods Integration to sign the data.

    Signing and encryption works as follows:

    1. The service uses the secret key to sign the data.

    2. The service then uses the external system’s public key to encrypt the data.

    3. The service returns the signed and encrypted data.

  • verify: Verifies the digital signature associated with the data.

    Input Parameters

    • data: Document - Signed data that you want to verify. The data must be in one of the following formats. If multiple input parameters are supplied for data, the service throws an exception stating that only one parameter must be passed.

      • string: String Optional - The signed string that you want to verify.

      • stream: java.io.InputStream Optional - The signed stream data that you want to verify.

      • bytes: byte[ ] Optional - The signed byte array that you want to verify.

    • loadAs: String Optional - The format in which the service returns the output. Set to:

      • bytes to return the output as a byte array. This is the default.

      • stream to return the output as a stream object.

    • publicKey: Document - The signer’s public key required to verify the signed data.

    • publicKeyBytes: byte[ ] Optional - The public key file in bytes.

      Note: Public key files have a .asc extension.

    Output Parameters

    • stream: java.io.OutputStream. Conditional - Verified data in the form of an output stream, when the stream input parameter is provided.

    • bytes: byte[ ]. Conditional - Verified data in bytes, when the bytes input parameter is provided.

    • verified: Boolean - Indicates whether the signature associated with the data is valid or not. A value of:

      • true indicates that the signed data is verified.

      • false indicates that the signed data is not verified.

    • status: String - Indicates whether the data is successfully verified or not. If successful, status is success. Otherwise, status contains failure along with an error message.

    Usage Notes

    To verify signed data, IBM webMethods Integration must have access to the signer’s public key.

    The verify service cannot verify a detached signature.

Note: Data up to 1GB can be uploaded and tested for PGP Encryption and Decryption operations.