security

Control which client certificates are sent to other services and digitally sign data and process digital signatures. You can also use the elements to store and retrieve outbound passwords to access secure resources.

generateHashValue

Returns the hashed value for a string input.

Input Parameters for generateHashValue

inputString: String. The string that you want to convert to a hash value.

hashAlgorithm: String. Optional. The algorithm to generate the hash value. Select one of the following:

  • MD5
  • SHA256
  • SHA384
  • SHA512 The default value is SHA256.

saltValue: byte[]. Optional. A random value that you can prefix to the input string before hashing.

Note: To use a salt value in this service, run the generateSalt service and map the generated salt value to this parameter.

Output Parameters for generateHashValue

hashedValue: String. Hashed value of the input string.

status: String. Indicates whether the inputString is successfully hashed or not. If successful, status is success. Otherwise, status contains failure along with an error message.

Usage Notes generateHashValue

  • Use the generateHashValue service to generate a hash value for any input string. For example, you can create a secure hashedValue for a user's password.
  • Additionally, you can run the generateSalt service to generate a salt value, which can be passed to the generateHashValue service to generate a unique and stronger hashedValue, each time you run the generateHashValue service.

generateSalt

Creates a salt value.

Input Parameters for generateSalt

None.

Output Parameters for generateSalt

saltValue: byte[]. Salt value to be used for hashing purposes.

status: String. Indicates whether a salt value is generated or not. If successful, status is success. Otherwise, status contains failure along with an error message.

Usage Notes for generateSalt

Use the saltValue output of this service as input to the generateHashValue service.

decryptAndVerify

Decrypts the encrypted data and verifies the associated digital signature.

Input Parameters for decryptAndVerify

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 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. - 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. ForJCE-KBE, provide secretKeyBytes or keyStoreAlias. If you provide keyStoreAlias, you must provide keyAlias. Otherwise, the service throws an exception. - 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. - secretKeyPassphrase: String Password required to extract the private key from the secret key. This is the password provided while generating the secret key. This parameter is specific to PGP. - 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.

publicKey: Document The public key required to verify the digital signature associated with the data.For PGP, provide publicKeyBytes, publicKeyString. For JCE-KBE, provide publicKeyBytes, publicKeyString. - 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.
 - publicKeyString: String List Optional. One or more public keys as
                    strings for PGP. JCE supports only a single public key string.<br>
                    - truststoreAlias: String Optional. Applies only to JCE. The alias for the
                    truststore containing the public key and certificate.
Note: This parameter is applicable only for JCE.
 - certAlias: String Optional. Applies only to JCE. The alias identifying
                    a particular trusted certificate within a truststore.
Note: This parameter is applicable only for JCE and is required only when you use truststoreAlias.
signingAlgorithm: String The signing algorithm to use. For PGP, select one of the following: - 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.

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 decryptAndVerify

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

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

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

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 for decryptAndVerify

  • Use the decryptAndVerify service when an external system connected to server requires decrypted data with verified signature.

  • Prerequisites to use the decryptAndVerify service:

    • Generate a public-secret key pair for server.
    • Make sure that the external system has access to the server's public key.
    • Make sure that the server has access to external's system's public key.

  • Decryption and verification work as follows:

    • The external system sends the data encrypted with server's public key and signed with its secret key.
    • The server receives the data and passes it to the decryptAndVerify service.
    • The service uses the private key extracted from the secret key to decrypt the data.
    • The service then uses the external system's public key to verify the signature of the decrypted data.
    • The service returns the decrypted and verified data.

  • For PGP, conisder the following points:

    • To decrypt and verify the data signed and encrypted for multiple users, you must provide your secret key and the users' public keys to the service. You can provide the 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 JCE, conisder the following points:
  • You can decrypt and verify the data signed and encrypted for a single user only.
  • The service supports a maximum data limit that depends on the key size.

decrypt

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

Input Parameters for decrypt

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. 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 to extract the private key required to decrypt the data. For PGP, provide secretKeyBytes, secretKeyString. For JCE-KBE, provide secretKeyBytes, secretKeyString, or keyStoreAlias. If you provide keyStoreAlias, you must provide keyAlias. Otherwise, the service throws an exception. - 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.<br>
                    - secretKey Passphrase String Password required to extract the private key from
                    the secret key. This is the password provided while generating the secret
                    key.<br>
                    - keyStoreAlias String Optional. Applies only to JCE. The keystore alias that
                    contains the private key used for decryption.<br>
                    - 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 realistically.

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
  • Prerequisites to use the decrypt service:
    • Generate a public-secret key pair for server.
    • Make sure that the external system that sends the encrypted data has access to server's public key to encrypt the data.
    • Decryption works as follows:
      1. The external system sends the data encrypted with server's public key.
      2. The server receives the data and passes it to the pub.security:decrypt service.
      3. The decrypt service uses the private key to decrypt the data.
      4. The service returns the decrypted data.
    • For PGP, consider the following points: 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, 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. - 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.

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 required to encrypt the data. For PGP, provide publicKeyBytes, publicKeyString, or publicKeyRingFile. For JCE-KBE, provide publicKeyBytes, publicKeyString, or truststoreAlias. If you provide truststoreAlias, you must also provide certAlias. Otherwise, the service throws an exception. Following are the key descriptions: - 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.<br>
                    - truststoreAlias: String Optional. Applies only to JCE. The alias for the
                    truststore containing the public key and certificate.<br>
                    - 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:

  • Before encrypted data is exchanged between server and an external system, the external system must share its public key. The service accepts multiple public keys to encrypt the same data for many users.
  • The public key is passed to the encrypt service, which returns the encrypted data to server.
  • To encrypt the data for multiple users, provide the users' public keys to the service as a list of byte arrays, strings.
  • 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. - 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. - string to return the output as a string.

secretKey: Document The secret key required to sign the data. For PGP, provide secretKeyBytes, secretKeyString. For JCE-KBE, provide secretKeyBytes, secretKeyString, or keyStoreAlias. If you provide keyStoreAlias, you must provide keyAlias. Otherwise, the service throws an exception. - secretKeyBytes: byte[] Optional. The secret key file in bytes.

Note: Secret key files have a .asc extension for PGP.
Note: This parameter is required only when you use keyStoreAlias.

signingAlgorithm:String The signing algorithm to use. For PGP, select one of the following: - 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.

Note: Authentication keys in the .ecc format are not supported.

signAndEncrypt

Adds a digital signature to data and then encrypts the data.

Input Parameters for signAndEncrypt

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 and 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: String Optional. The string that you want to sign and encrypt. - stream: java.io.InputStream Optional. The stream data that you want to sign and encrypt. - bytes: byte[] Optional. The byte array that you want to sign and 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 required to encrypt the data.

For PGP, provide publicKeyBytes, publicKeyString.

For JCE-KBE, provide publicKeyBytes, publicKeyString, or truststoreAlias. If you provide truststoreAlias, you must also provide certAlias. Otherwise, the service throws an exception. - 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.
  • This parameteris required only when you use truststoreAlias.

encryptionAlgorithm: String The 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).

secretKey: Document The secret key required to sign the data. For PGP, provide secretKeyBytes, secretKeyString. For JCE-KBE, provide secretKeyBytes, secretKeyString, or keyStoreAlias. If you provide keyStoreAlias, you must provide keyAlias. Otherwise, the service throws an exception. - 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.
  • secretKeyPassphrase: 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:
  • 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
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 signAndEncrypt

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

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

string: String Conditional. Signed and 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 signed and encrypted or not. If successful,statusis success. Otherwise,status contains failure along with an error message.

Usage Notes for signAndEncrypt

  • Use the signAndEncrypt service when an external system connected to server requires signed and encrypted data. The service accepts multiple public keys to encrypt the same data for many users.

  • Prerequisites to use the signAndEncrypt service:

    • Make sure that server has access to the external system's public key to encrypt data.
    • Generate a secret key for server to sign the data.

  • Signing and encryption work as follows:

    • The service uses the secret key to sign the data.
    • The service then uses the external system's public key to encrypt the data.
    • The service returns the signed and encrypted data.

  • For PGP, consider the following point:

    • To sign and encrypt the data for multiple users, provide your secret key and the users' public keys to the service. You can provide the public keys to the service as a list of byte arrays, strings.
    • 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 JCE, you can sign and encrypt the data for a single user only.

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 Encryption) 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.

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

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

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

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. string: String Optional. The original string that you want to verify. stream: java.io.InputStream Optional. The original stream data that you want to verify. bytes: byte[] Optional. The original byte array 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 in bytes. Returned when the loadAs input parameter is set to bytes.

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

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, server must have access to the signer's public key.
  • 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.
    • 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.
  • For JCE, you can verify the data for single user only.
    Note: Authentication keys in the .ecc format are not supported.

createMessageDigest

Generates a message digest for a given message.

Input Parameters for createMessageDigest

algorithm: String Name of the algorithm that you want to use to compute the message digest. Must be one of the following: MD5, SHA-1, SHA-256, SHA-384, or SHA-512.

input: byte[] Optional. Message for which you want the digest generated where the message is in the form of a byte array.

Note: If both input and inputAsStream are provided, inputAsStream takes precedence.

inputAsStream: java.io.InputStream Optional. Message for which you want to generate a message digest where the message is in the form of an input stream.

Note: If both input and inputAsStream are provided, inputAsStream takes precedence.

Output Parameters for createMessageDigest

output: byte[] Conditional. Computed digest in the form of a byte array. output is returned when the input parameter input is provided.

outputAsStream: OutputStream. Conditional. Computed digest in the form of an output stream. outputAsStream is returned when the input parameter inputAsStream is provided.

getCertificateInfo

Retrieves information such as serial number, issuer, and expiration date from a digital certificate.

Input Parameters for getCertificateInfo

certificate: byte[] java.security.cert.X509Certificate The certificate whose information you want to retrieve.

dateFormat: String Optional. The date format to use for the date returned by the notBefore and notAfter fields in the validity output parameter. The value of dateFormat must be a pattern used by java.text.SimpleDateFormat, for example: MM/dd/yyyy . By default, getCertificateInfo service uses a preset date format that returns only the last two digits of the certificate expiration year. This can lead can lead to ambiguity as a certificate that expires in 2109 returns an expiration year of 09, which some systems might treat as 2009.

Output Parameters for getCertificateInfo

info: Document Information from the certificate. - version: java.lang.Number X509 certificate version number. - serialNumber: String Serial number of the certificate. - signature: String Signature algorithm used by the issuer to sign this certificate. - issuer: Document Detailed information about the CA that signed the certificate, such as name, location, and e-mail address. - validity: Document The time period over which the certificate is valid. - notBefore: String First date on which this certificate is valid (for example, 3/15/00 3:36PM). - notAfter: String Last date on which this certificate is notAfter valid (for example, 3/15/00 3:36PM). - subject: Document. Detailed information about the owner of the certificate, such as name, location, and mail address. - subjectPublicKeyAlgorithm: String Encryption algorithm with which the certificate's key is designed to be used (for example, RSA or DSA).

loadPKCS7CertChain

Converts a certificate chain that is in PKCS #7 format to a list of byte arrays.

Input Parameters for loadPKCS7CertChain

certificateChain: byte[] The certificate chain in PKCS #7 format.

Output Parameters for loadPKCS7CertChain

certificates: byte[] List of byte arrays in which each byte[] in the list contains a certificate from certificateChain.

decryptXML

Decrypts the encrypted XML, and returns the XML as either a string or stream object.

Input Parameters for decryptXML

String Optional. Encrypted XML that needs to be decrypted as plain text.

xmldata: String Optional. Encrypted XML that needs to be decrypted as plain text.

xmlStream: InputStream Optional. Encrypted XML in the form of an input stream.

Note: If both xmldata and xmlStream are provided, xmlStream takes precedence; server uses the xmlStream value and returns only decryptedXMLStream.

keyStoreAlias: String Optional. Alias of the keystore that contains the private key used for decryption.

keyAlias: String Optional. Alias of the private key, contained in the keystore specified by the keyStoreAlias parameter, that is used for decryption.

encoding: String Optional. Specifies the encoding to use if the encoding cannot be extracted from the XML. If encoding is not specified in the XML document or in the encoding parameter, server uses UTF-8.

The encoding value must be a valid IANA encoding.

Output Parameters for decryptXML

decryptedXMLData: String Conditional. DecryptedXML data. decryptedXMLData is returned when the input parameter xmldata is provided.

decryptedXMLStream: Object Conditional. A decrypted XML OutputStream object. decryptedXMLStream is returned when the input parameter xmlStream is provided.

Usage Notes for decryptXML

  • There are several prerequisites to using decryptXML:

    • Certificates must be configured for server and the client with which it is exchanging secure XML.
    • The sending, encrypting client must have access to server's public key before the document exchange can occur.
    • The server stores its certificates in keystores and truststores. You must configure a keystore and truststore for server before using the XML encryption services.

  • The decryptXML service works as follows:

    1. The external system sends the XML document encrypted with the server's public key.
    2. The server receives the document and passes it to the XML service.
    3. The server uses the private key member of the key pair to decrypt the XML.
    4. The decrypted XML is returned from the service.

  • If both xmldata and xmlStream are provided, xmlStream takes precedence; server uses the xmlStream value and returns only decryptedXMLStream.

  • keyAlias and keyStoreAlias should either both be provided or both be absent from the input. If no value is provided forthese parameters, server uses the private key/certificate specified for the Decryption Key. If no value is specified for Decryption Key, server uses the SSL Key.

encryptXML

Encrypt an XML document or node in an XML document.

Input Parameters for encryptXML

xmldata: String Optional. The XML to be encrypted.

xmlStream: InputStream Optional. Input stream to the XML that needs to be encrypted.

Note: If both xmldata and xmlStream are provided, xmlStream takes precedence.

nodeSelectors: String List XPaths to the node to be encrypted. If the value for this parameter is empty, no XML will be encrypted.

nsDecls: Document Optional. Mapping of the namespace prefixes to the namespace URIs. The first column contains the prefixes and the second column contains the corresponding URIs.

recipientCert: Byte[] Optional. The certificate containing the public key that will be used to encrypt the XML. If the input parameters recipientCert and recipientID are both provided, recipientCert is used.

contentOnly: Boolean Optional. Indicates whether the XML tags surrounding the content will be encrypted along with the content. Set to: - true to encrypt only the content. - false to encrypt both the tags and the content. This is the default.

algorithm: String Optional. The symmetric key algorithm to use for encryption. Set to: - tripledes-cbc for the algorithm at http://www.w3.org/2001/04/xmlenc#tripledes-cbc This is the default. - aes256-cbc for the algorithm at http://www.w3.org/2001/04/xmlenc#aes256-cbc - aes192-cbc for the algorithm at http://www.w3.org/2001/04/xmlenc#aes192-cbc - aes128-cbc for the algorithm at http://www.w3.org/2001/04/xmlenc#aes128-cbc

Note: If you are using aes256-cbc or aes192-cbc with JVM 1.6, make sure the unlimited policy jar files have been installed.

encryptedKeyAlgorithm: String Optional. The symmetric key that is randomly generated, and then encrypted with the receiver's public key. This encryption uses an asymmetric algorithm if public/private key pairs are being used. Set to: - rsa-1_5 for the algorithm at http://www.w3.org/2001/04/xmlenc#rsa-1_5 This is the default. - rsa-oaep-mgf1p for the algorithm at http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

encoding: String Optional. Specifies the encoding to use if the encoding cannot be extracted from the XML. If encoding is not specified in the XML document orin the encoding parameter, server uses UTF-8. The encoding value must be a valid IANA encoding.

Output Parameters for encryptXML

encryptedXMLData: String Conditional. Encrypted XML data. encryptedXMLData is returned when the input parameter xmldata is provided.

encryptedXMLStream: OutputStream Conditional. Encrypted XML in the form of an OutputSream. encryptedXMLStream is returned when the input parameter xmlStream is provided.

Usage Notes for encryptXML

  • If both xmldata and xmlStream are provided, xmlStream takes precedence.

  • There are several prerequisites to using the pub.security.xml:encryptXML service:

    • Certificates must be configured for server and the client with which it is exchanging encrypted XML.
    • Before an encrypted XML document can be exchanged between server and an external system, the external system must share its public key.
    • Prior to use of encryptXML, server must have access to the partner's public key. Such access is possible through:

      The server certificate mapping (for information, refer to webMethods Integration Server Administrator’s Guide).

      A copy of the partner's X.509 certificate that is available to server.

  • In encryptXML, the certificate/public key is specified through the following input parameters: the public key of the partner application (through recipientCert).

  • Because encryption is a processing-intensive activity, it is recommended to only encrypt the XML nodes requiring protection.

Signing and Encrypting the Same XML Document

You can use both encryption and signing in the same XML document.

  • If you sign and encrypt different XML elements in a document, you can run either signXML or encryptXML first.
  • Typically, if you sign and encrypt the same XML elements in a document, you should sign the elements before encrypting them. That is, invoke signXML before invoking xml:encryptXML.

signXML

Digitally sign an outgoing XML node or document.

Input Parameters for signXML

xmldata: String Optional. XML that needs to be signed.

xmlStream: InputStream Optional. Input stream containing the XML that needs to be signed.

Note: If both xmldata and xmlStream are provided, xmlStream takes precedence.

uri: String Optional. URI to the element to be signed. In combination with the nodeSelectors parameter, the uri identifies the nodes to be signed.

noNamespace SchemaLocation: String Optional. A URI that identifies the location of the XML schema definition that contains the ID attribute specified in uri. Provide a noNamespaceSchemaLocation when specifying an ID attribute for uri and the ID attribute resides in an XML schema with no namespaces.

schemaLocations: Document Optional. Document containing name-value pairs forthe XML namespace and the location of the XML schema definition that contains element declarations, attribute declarations, and type definitions for that namespace. Provide a schemaLocation when specifying an ID attribute for uri and the ID attribute resides in an XML schema for a particular namespace.

For example:
XML namespace = http://www.w3schools.com - XML schema
                    definition location = file:C:/note.xsd

nodeSelectors: String List XPath notation that identifies the nodes to be signed. The locations of the XPaths are not absolute, but relative, and work within the context of the node (an XPath Axes).

Note: Do not use absolute location XPaths here.

nsDecls: Document Optional. Mapping of the namespace prefixes to the namespace URIs. The first column contains the prefixes and the second column contains the corresponding URIs.

isEnveloped: String Optional. Indicates whether the signature is enveloped or enveloping. Set to: - True to indicate that the generated signature will be enveloped. This is the default. - False to indicate that the generated signature will be enveloping, provided the isDetached parameteris set to False.

Unlike the detached signature, which is kept apart from the original document, enveloping and enveloped signatures are tightly coupled with the original document.

isDetached: String Optional. Indicates whether the signature is detached or not.

The server uses as the container for signature and the XML to be signed. Set to:
  • True to indicate that the generated signature will be detached.
  • False to indicate that the generated signature will be enveloping or enveloped, based on the isEnveloped parameter setting. This is the default.
Note:
  • Setting isDetached to True and isEnveloped to False, indicates that the signature is detached.
  • Setting isDetached to False and isEnveloped to True, indicates that the signature is enveloped.
  • Setting isDetached to False and isEnveloped to False, indicates that the signature is enveloping.
  • Setting isDetached to True and isEnveloped to True, results in error.
  • SHA1 (default)
  • SHA256
  • SHA384
  • SHA512

includeKeyValue: String Optional. Indicates whether to include the key value (RSAKeyValue or DSAKeyValue), based on the certificate used for signing. The KeyValue element contains a single public key that can be used in validating the signature. Set to: - True to include the key value (RSAKeyValue or DSAKeyValue) based on the certificate used for signing. - False to exclude the key value from the signature.

includeCertChain: String Optional. Indicates whether the certificate chain should be included in the signature. Set to:
  • - True to include the certificate chain in the signature.
  • - False to leave the certificate chain out of the signature. This value is the default.

Output Parameters for signXML

signedXMLData: String Conditional. Signed XML data. signedXMLData is returned when xmlData is provided.

signedXMLStream: OutputStream Conditional. Signed XML in the form of an OutputSream. signedXMLStream is returned when xmlStream is provided.

Usage Notes for signXML

  • Before signing or verifying the XML signature between the server and an external system, the server shares the public key that matches the private key used to sign the document. The external system uses this public key to perform the verification.

  • keyAlias and keyStoreAlias should either both be provided or both be absent from the input. If no value is provided for these parameters, the server uses the private key/certificate specified for the Signing Key. If the Signing Key is not specified, server uses the SSL Key.

  • If both xmldata and xmlStream are provided, xmlStream takes precedence.

  • The uri and nodeSelectors parameters identify the nodes to be signed.

  • If uri is specified and nodeSelectorsis not specified, server signs the entire node identified by uri.

  • If uri and nodeSelectors are specified, server determines which nodes to sign by locating the node specified by the uri and then applying the filter from nodeSelectors.

  • If uri is not specified and nodeSelectors is specified, server determines which nodes to sign by applying the filter in nodeSelectors to the entire XML.

  • If neither uri nor nodeSelectors are specified, server signs the entire XML.

  • You can use the value of an ID attribute as the uri. For example, #sampleID.

  • Where sampleID is an ID attribute that functions as a unique identifier for an element in an XML schema definition. In this example, the server locates the node with the ID attribute "sampleID" and then apply the filter specified by nodeSelectors to determine which nodes to sign.

Signature Types for signXML

As opposed to a detached signature, which is kept apart from the original document, enveloping and enveloped signatures are tightly coupled with the original document.

An enveloping signature must be a parent node of the data being signed:
<!--
                    Example of Enveloping Signature --> <Signature> <my_document>. .
                    . </my_document> </Signature>\
The following input parameters and values are applicable only to enveloping signatures: 
isEnveloped: Specify a value of "false" for
                    enveloping.
If isEnveloped is set to false, then:
  • - If both uri and idXmlObject are null, the server creates a dynamic unique value for both uri and idXmlObject and signs the XML.
  • - If idXmlObject is provided and uri is null, the server creates a uri with a value of #idXmlObject_value and signs the XML.
  • - If both and uri and idXmlObject are provided and match the XML contract (for example,uri='#idXmlObject'), The server signs the XML. If the uri and idXmlObject parameters do not match the contract, the server issues an exception.
idXmlObject: Specifies the ID for the node that holds the original, signed XML. An enveloped signature must be a child node of the data being signed:
<!--
                    Example of Enveloped Signature --> <my_document><Signature> . . .
                    </Signature> </my_document>
The following parameters and values are applicable only to enveloped signatures: isEnveloped: The default value of "true" specifies that the signature is enveloped. signatureNodeSelector: XPath to the node where the signature is entered. If no value is provided, the signature is placed as a first child of the root node.

Signing and Encrypting the Same XML Document

You can use both encryption and signing in the same XML document.

  • If you sign and encrypt different XML elements in a document, you can run either signXML or encryptXML first.

  • Typically, if you sign and encrypt the same XML elements in a document, you should sign the elements before encrypting them. That is, invoke signXML before invoking encryptXML

getKeyAndChain

Returns a private key and its associated certificate chain from a designated keystore.

Input Parameters for getKeyAndChain

keyStoreAlias: String Alias for the keystore that contains the private key of interest and its certificate.

keyAlias: String Alias for the private key stored in the specified keystore.

Output Parameters for getKeyAndChain

privateKey: java.security.PrivateKey Object representing the private key.

certChain: byte[] [] List of byte arrays representing the certificate chain associated with the private key.