Security services

Use Security services to control which client certificates are sent to other services and digitally sign data and process digital signatures.

Use the Security services to:

  • Control which client certificates are sent to other services.
  • Digitally sign data.
  • Process digital signatures.
  • Store and retrieve outbound passwords to access secure resources.
  • Manage webMethods Integration keystores and truststores.
  • Secure XML documents.
Prerequisites

The keystores and truststores must be configured. For more information, see https://www.ibm.com/docs/en/hybrid-integration-lib/hybrid-integration/saas?topic=runtimes-configuring-runtime-security-settings.

decrypt

Decrypts the encrypted data and returns plain data as a stream object or byte array or string.

Input parameters for decrypt

  • securityProvider: String. Optional. The type of security provider. The valid values are:

    • PGP (Pretty Good Privacy)
    • JCE-KBE (Java Cryptography Extension-Key Based Encryption)

    The default value is PGP.

  • data: Document. Data that you want to decrypt. 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.

    Key Description
    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.
    file

    String. Optional. The absolute or relative path of the file that you want to decrypt.

  • 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 value.
    • stream to return the output as a stream object.
    • string to return the output as a string.

  • secretKey: Document. The secret key to extract the private key required to decrypt the data.

    For PGP, provide secretKeyBytes, secretKeyString, or secretKeyRingFile. If you provide secretKeyRingFile, you must also provide secretKeyAlias. Otherwise, the service throws an exception.

    For JCE-KBE, provide secretKeyBytes, secretKeyString, or keyStoreAlias. If you provide keyStoreAlias, you must provide keyAlias. Otherwise, the service throws an exception.

    Key Description
    secretKeyBytes

    byte[ ]. Optional. The secret key file in bytes.

    Note: Secret key files have a .asc extension for PGP.
    secretKeyString String. Optional. The secret key as a string.
    secret​KeyRingFile

    String. Optional. The absolute or relative path of the secret keyring file. The secret keyring file is a collection of secret keys with a unique key ID.

    Note: This parameter is applicable only for PGP.
    Note: Secret keyring files have a .skr extension for PGP.
    secretKeyAlias

    String. Optional. The 64 bit (16 characters) key identifier of the secret key.

    Note: This parameter is required only when you use secretKeyRing​File.
    secretKey Passphrase String. Password required to extract the private key from the secret key. This is the password provided while generating the secret key
    keyStoreAlias String. Optional. Applies only to JCE. The keystore alias that contains the private key used for decryption.
    keyAlias

    String. Optional. Applies only to JCE. The private key alias in the keystore specified by the keyStoreAlias parameter that is used for decryption.

    Note: This parameter is required only when you use keyStoreAlias.
  • cipher: String. Optional. Applies only to JCE. The cipher for decryption.

    Select one of the following:

    • RSA
    • RSA/ECB/PKCS1Padding
    • RSA/ECB/OAEPWithSHA-1AndMGF1Padding
    • RSA/ECB/OAEPWithSHA-256AndMGF1Padding
    • RSA/ECB/OAEPWithSHA-512AndMGF1Padding
    • RSA/ECB/OAEPPadding

    The default value is RSA.

Output parameters for decrypt

  • stream: java.io.OutputStream. Conditional. Decrypted data as an output stream. Returned when the loadAs input parameter is set to stream.

  • bytes: byte[ ]. Conditional. Decrypted data as bytes. Returned when the loadAs input parameter is set to bytes.

  • string: String. Conditional. Decrypted data as a string. Returned when the loadAs input parameter is set to string.

  • 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 for decrypt

The decrypt service requires authentication keys in the PGP format that are generated with the RSA encryption algorithm. PGP does not support authentication keys with .ecc file format. For JCE, the service supports a maximum data size that depends on the key size.

encrypt

Converts plain data to encrypted data.

Input parameters for encrypt

  • securityProvider: String. Optional. The type of security provider. The valid values are:

    • PGP (Pretty Good Privacy)
    • JCE-KBE (Java Cryptography Extension-Key Based Encryption)

    The default value is PGP.

  • 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.

    Key Description
    string String. Optional. The string that you want to encrypt.
    stream java.io.InputStream. Optional. The stream data that you want to encrypt.
    bytes byte[ ]. Optional. The byte array that you want to encrypt.
    file

    String. Optional. The absolute or relative path of the file 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.
    • stream to return the output as a stream object.
    • string to return the output as a string.

  • publicKey: Document. The public key to extract the private key required to encrypt the data.

    For PGP, provide publicKeyBytes, publicKeyString, or publicKeyRingFile. If you provide publicKeyRingFile, you must also provide publicKeyAlias. Otherwise, the service throws an exception.

    For JCE-KBE, provide publicKeyBytes, publicKeyString, or truststoreAlias. If you provide truststoreAlias, you must provide certAlias. Otherwise, the service throws an exception.

    Key Description
    publicKeyBytes

    Object List. Optional. One or more public key files as byte arrays for PGP. JCE supports only a single public key file.

    Note: Public key files have a .asc extension for PGP.
    publicKeyString String List. Optional. One or more public keys as strings for PGP. JCE supports only a single public key string.
    public​KeyRingFile

    String. Optional. The absolute or relative path of the public keyring file. The public keyring file is a collection of public keys with a unique key ID.

    Note: This parameter is specific to PGP.
    Note: Public keyring files have a .pkr extension for PGP.
    publicKeyAlias

    String List. Optional. One or more public key aliases as strings. A public key alias is the 64-bit (16 characters) key identifier of a public key.

    Note: This parameter is required only when you use publicKeyRing​File.
    turststoreAlias String. Optional. Applies only to JCE. The alias for the truststore containing the public key and certificate.
    certAlias

    String. Optional. Applies only to JCE. The alias identifying a particular trusted certificate within a truststore.

    Note: This parameter is required only when you use truststoreAlias.
  • encryption​Algorithm: String. The key encryption algorithm to use.
    • For PGP, select one of the following symmetric key encryption algorithms:
      • AES_192
      • AES_256
      • BLOWFISH
      • IDEA
      • TRIPLE_DES
      • TWOFISH

      The default value is AES_256.

    • For JCE, select RSA (asymmetric key encryption algorithm).
  • cipher: String. Optional. Applies only to JCE. The cipher for encryption.

    Select one of the following:

    • RSA
    • RSA/ECB/PKCS1Padding
    • RSA/ECB/OAEPWithSHA-1AndMGF1Padding
    • RSA/ECB/OAEPWithSHA-256AndMGF1Padding
    • RSA/ECB/OAEPWithSHA-512AndMGF1Padding
    • RSA/ECB/OAEPPadding

    The default value is RSA.

Output parameters for encrypt

  • stream: java.io.OutputStream. Conditional. Encrypted data as an output stream. Returned when the loadAs input parameter is set to stream.

  • bytes: byte[ ]. Conditional. Encrypted data as bytes. Returned when the loadAs input parameter is set to bytes.

  • string: String. Conditional. Encrypted data as a string in the ASCII-armored format. Returned when the loadAs input parameter is set to string.

  • 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 for encrypt

For PGP, consider the following points:
  • To encrypt the data for multiple users, provide the users' public keys to the service as a list of byte arrays, strings, or a keyring file. If you provide a keyring file, you must also provide the public key aliases.
  • Authentication keys used in this service must be in the PGP format and generated using the RSA encryption algorithm.
    Note: Authentication keys in the .ecc format are not supported for PGP.
For JCE, consider the following points.
  • You can encrypt the data for a single user only. Provide the public key to the service as a list of byte array, string, or truststoreAlias. If you provide truststoreAlias, you must also provide certAlias.
  • The service supports a maximum data size that depends on the key size.

sign

Adds a digital signature to data.

Input parameters for sign

  • securityProvider: String. Optional. The type of security provider. The valid values are:

    • PGP (Pretty Good Privacy)
    • JCE-KBE (Java Cryptography Extension-Key Based Encryption)

    The default value is PGP.

  • 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.

    Key Description
    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.
    file

    String. Optional. The absolute or relative path of the file 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.
    • string to return the output as a string.

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

    For PGP, provide secretKeyBytes, secretKeyString, or secretKeyRingFile. If you provide secretKeyRingFile, you must also provide secretKeyAlias. Otherwise, the service throws an exception.

    For JCE-KBE, provide secretKeyBytes, secretKeyString, or keyStoreAlias. If you provide keyStoreAlias, you must provide keyAlias. Otherwise, the service throws an exception.

    Key Description
    secretKeyBytes

    byte[ ]. Optional. The secret key file in bytes.

    Note: Secret key files have a .asc extension for PGP.
    secretKeyString String. Optional. The secret key as a string.
    secret​KeyRingFile

    String. Optional. The absolute or relative path of the secret keyring file. The secret keyring file is a collection of secret keys with a unique key ID.

    Note: This parameter is applicable only for PGP.
    Note: Secret keyring files have a .skr extension for PGP.
    secretKeyAlias

    String. Optional. The 64 bit (16 characters) key identifier of the secret key.

    Note: This parameter is required only when you use secretKeyRing​File.
    secretKey Passphrase String. Password required to extract the private key from the secret key. This is the password provided while generating the secret key
    keyStoreAlias String. Optional. Applies only to JCE. The keystore alias that contains the private key.
    keyAlias

    String. Optional. Applies only to JCE. The private key alias in the keystore specified by the keyStoreAlias parameter.

    Note: This parameter is required only when you use keyStoreAlias.
  • signingAlgorithm: String. The signing algorithm to use.
    • For PGP, select one of the following:
      • MD5
      • SHA256
      • SHA384
      • SHA512

      The default value is SHA256 for PGP.

    • For JCE, select one of the following:
      • RSA
      • SHA256withRSA
      • SHA512withRSA
      • SHA3-256withRSA
      • SHA3-384withRSA
      • SHA3-512withRSA
    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. This is applicable only for PGP.

Output parameters for sign

  • stream: java.io.OutputStream. Conditional. Signed data as an output stream. Returned when the loadAs input parameter is set to stream.

  • bytes: byte[ ]. Conditional. Signed data as bytes. Returned when the loadAs input parameter is set to bytes.

  • string: String. Conditional. Signed data as a string in the ASCII-armored format. Returned when the loadAs input parameter is set to string.

  • 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 for sign

For PGP, consider the following points:

  • The sign service does not support a detached signature.
  • Authentication keys used in this service must be in the PGP format and generated using the RSA encryption algorithm.
    Note: Authentication keys in the .ecc format are not supported.

verify

Verifies signed data.

Input parameters for verify

  • securityProvider: String. Optional. The type of security provider. The valid values are:

    • PGP (Pretty Good Privacy)
    • JCE-KBE (Java Cryptography Extension-Key Based verifyion)

    The default value is PGP.

  • 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.

    Key Description
    string String. Optional. The string that you want to verify.
    stream java.io.InputStream. Optional. The stream data that you want to verify.
    bytes byte[ ]. Optional. The byte array that you want to verify.
    file

    String. Optional. The absolute or relative path of the file 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.
    • string to return the output as a string.

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

    For PGP, provide publicKeyBytes, publicKeyString, or publicKeyRingFile. If you provide publicKeyRingFile, you must also provide publicKeyAlias. Otherwise, the service throws an exception.

    For JCE-KBE, provide publicKeyBytes, publicKeyString, or truststoreAlias. If you provide truststoreAlias, you must provide certAlias. Otherwise, the service throws an exception.

    Key Description
    publicKeyBytes

    Object List. Optional. One or more public key files as byte arrays for PGP. JCE supports only a single public key file.

    Note: Public key files have a .asc extension for PGP.
    publicKeyString String List. Optional. One or more public keys as strings for PGP. JCE supports only a single public key string.
    public​KeyRingFile

    String. Optional. The absolute or relative path of the public keyring file. The public keyring file is a collection of public keys with a unique key ID.

    Note: This parameter is specific to PGP.
    Note: Public keyring files have a .pkr extension for PGP.
    publicKeyAlias

    String List. Optional. One or more public key aliases as strings. A public key alias is the 64-bit (16 characters) key identifier of a public key.

    Note: This parameter is required only when you use publicKeyRing​File.
    turststoreAlias String. Optional. Applies only to JCE. The alias for the truststore containing the public key and certificate.
    certAlias

    String. Optional. Applies only to JCE. The alias identifying a particular trusted certificate within a truststore.

    Note: This parameter is required only when you use truststoreAlias.
  • signingAlgorithm: String. The signing algorithm to use.
    • For PGP, select one of the following:
      • MD5
      • SHA256
      • SHA384
      • SHA512

      The default value is SHA256 for PGP.

    • For JCE, select one of the following:
      • RSA
      • SHA256withRSA
      • SHA512withRSA
      • SHA3-256withRSA
      • SHA3-384withRSA
      • SHA3-512withRSA
    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. This is applicable only for PGP.
  • actualData: Document Applies only to JCE. The original data that was signed and needs to be verified against the signature to confirm that it hasn't been tampered with. The actualData parameter must be in one of the specified formats. If multiple input parameters are provided for actualData, the service throws an exception indicating that only one parameter should be passed.
    Key Description
    string String. Optional. The string that you want to verify.
    stream java.io.InputStream. Optional. The stream data that you want to verify.
    bytes byte[ ]. Optional. The byte array that you want to verify.
    file

    String. Optional. The absolute or relative path of the file that you want to verify.

Output parameters for verify

  • stream: java.io.OutputStream. Conditional. Verified data as an output stream. Returned when the loadAs input parameter is set to stream.

  • bytes: byte[ ]. Conditional. Verified data as bytes. Returned when the loadAs input parameter is set to bytes.

  • string: String. Conditional. Verified data as a string in the ASCII-armored format. Returned when the loadAs input parameter is set to string.

  • 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 for verify

For PGP, consider the following points:
  • To verify the data for multiple users, provide the users' public keys to the service as a list of byte arrays, strings, or a keyring file. If you provide a keyring file, you must also provide the public key aliases.
  • The verify service cannot verify a detached signature.
  • Authentication keys used in this service must be in the PGP format and generated using the RSA encryption algorithm.
    Note: Authentication keys in the .ecc format are not supported for PGP.

For JCE, you can verify the data for single user only.