Cryptographic Message Service

The Cryptographic Message service builds and parses cryptographic messages in SMIME, PEM, or DER format.

The following table provides an overview of the Cryptographic Message service:

Service name	Cryptographic Message Service
System name	CryptoMsgService
Graphical Process Modeler (GPM) category	All Services
Description	Builds and parses cryptographic messages in SMIME, PEM, or DER format.
Business usage	The Cryptographic Message Service allows users to build and parse cryptographic messages in SMIME, PEM, or DER format.
Usage example	A business process that needs to create or parse the content in a cryptographic message in SMIME, PEM, or DER format can invoke this service by passing the required parameters. Cryptographic messages must follow either Cryptographic Message Syntax or PKCS#7 specification.
Preconfigured?	The Cryptographic Message service should be installed and deployed before it is invoked. However, configuration parameters are not required.
Requires third-party files?	No
Platform availability	All supported Sterling B2B Integrator platforms
Related services	No
Application requirements	No
Initiates business processes?	No. This service does not initiate business process.
Invocation	Yes. Runs as a service within a business process.
Returned status values	Values: buildResponse - If an exception is thrown during build process, the “exception-message” node is returned to ProcessData with the exception message. parseResponse - If an exception is thrown during parse process, the “exception-message” node is returned to ProcessData with the exception message.
Restrictions	None
Testing considerations	Considerations You should use the right certificates for signing or encryption/decryption. If you receive an error with the condition that certificates used for signing or decrypting are not created with a storepass value of integrator and are created with a keypass value of integrator, see your system administrator.

How the Cryptographic Message Service Works

Cryptographic Message Service (CMS) builds and parses secure messages in Secure MIME (SMIME), Distinguished Encoding Rules (DER), or Privacy Enhanced Email (PEM) format.

The security features of CMS are digital signature and encryption. The Digital signature feature provides authentication, message integrity, and non-denial with proof or origin whereas encryption provides data privacy.

The CMS supports two cryptographic message syntaxes. They are CMS and PKCS#7. If you are building outbound message syntax, you have to indicate the cryptographic message syntax as either one of them. The PKCS#7 uses non-streaming API to handle message building and has limitations to process large files whereas the CMS uses streaming API and has the capability to process large files. If you are parsing an inbound cryptographic message, there is no need to indicate your choice as CMS uses streaming API to parse either PKCS#7 or CMS messages.

Implementing the Cryptographic Message Service

To implement the Cryptographic Message service for use in a business process, complete the following tasks:

Create a configuration of the Cryptographic Message service. See Managing Services and Adapters. For information about the fields specific to this service, see Configuring the Cryptographic Message Service.
Specify field settings for the service configuration in the Sterling B2B Integrator Admin Console and in the GPM as necessary. For information, see Configuring the Cryptographic Message Service.
Use the Cryptographic Message service in a business process.

System Administrator Tasks

The following procedures describe the system administrator tasks for the cryptographic message service.

Importing a keyCert

Log in to Sterling B2B Integrator.
Select Trading Partner -> Digital Certificates -> System.
Select Key Certificate under Check-in.
Enter the Certificate Name and Private Key Password.
Select the certificate and assign an alias to it.
Review and click Finish. You can use this certificate in your BPML associated with the appropriate field (signingCert or decryptCert).

Importing a Public Certificate

Log in to Sterling B2B Integrator.
Select Trading Partner -> Digital Certificates -> Trusted.
Select New Certificate under Check-in.
Select the certificate and click Next.
Enter the Certificate Name and Next.
Review and click Finish. You can use this certificate in your BPML associated with the appropriate field (encryptCert or sigVerifyCert).

Configuring the Cryptographic Message Service

You can create one service instance for building and parsing cryptographic messages. You can configure the service in Sterling B2B Integrator and also in the GPM.

To configure the Cryptographic Message service, you must specify settings for the following fields:

Note: Any field values passed from a prior service can override any of configured fields for this service.

Field	Description
Name	Unique and meaningful name for the adapter configuration. Required.
Description	Meaningful description for the adapter configuration, for reference purposes. Required.
Select a Group	Group of services or adapters of the same type that can act as peers. A Service Group name is used in BPML in place of the Service Configuration name. Service Groups show up in the GPM as if they were Service Configurations. Select a Service Group to associate with this adapter. Valid values are: None - You do not want to include this configuration in a group at this time (default) Create New Group - You can enter a name for a new group in this field, which is then created along with this configuration. Select Group - If you have already created one or more groups for this service type, they are displayed in the list. Select a group from the list. For more information about service groups see Managing Services and Adapters.
Cryptographic Message Syntax	Drop-down menu containing a list of cryptographic message syntaxes for building cryptographic messages. Required. Valid values are: CMS (default) PKCS#7
Security Type	Drop-down menu containing the security type for building cryptographic messages. Required. Valid values are: Encrypted Only (default) - Encrypts the message only Detached Signed Only - Signs the original document and leaves the signature detached from the original document. If the message output format is SMIME, multipart MIME message will separate the original document and signature. If the message output format is DER or PEM, only detached signature will be returned by the service. Embedded Signed Only - Signs the original document and embeds the original document inside the signature. Detached Signed and Encrypted - Creates detached signed signature and encrypts the signed message. If the message output format is SMIME, the encryption is applied on the multipart MIME message. If the message output format is DER or PEM, the encryption is applied on the detached signature only. Embedded Signed and Encrypted - Creates embedded signed signature and encrypts the signed message.
Message Output Format	Message output format for generating the signed or encrypted message. Required. Valid values are: SMIME (default) - The signed or encrypted message will be output in MIME format. DER - The signed or encrypted message will be output in DER encoded format. PEM - The signed or encrypted message will be output in PEM encoded format, which is a base64 encoded DER format and enclosed between a start and an end boundary.
Document MIME Content Type	This parameter is enabled only if you select SMIME as the message output format.MIME content type for the document that needs to be packaged. If the input document is set with the content type, the value will override the setting here. Optional. Valid values are: application (default) text message image video audio
Document MIME Sub Content Type	This parameter is enabled only if you select SMIME as the message output formatMIME sub content type for the document that needs to be packages. If the input document is set with the sub content type, the value will override the setting here. Optional. Valid values are: octet-stream (default) plain edi-x12 edifact edi-consent xml
Content Transfer Encoding	This parameter is enabled only if you select SMIME as the message output format.Content transfer encoding format. Optional. Valid values are: Base64 (default) None
Apply Content Transfer Encoding on Detached Document	This parameter is enabled only if you select SMIME as the message output format.To indicate if content transfer encoding should be applied on the detached document. This is used for Detached Signed Only and Detached Signed and Encrypted security types. Optional. Valid values are: Yes (default) No
Encryption Algorithm:	Content encryption algorithm. Optional. Valid values are: Triple DES (3DES) 168 CBC with PKCS5 padding (default) 56-bit DES CBC with PKCS5 padding 128-bit RC2 CBC with PKCS5 padding 40-bit RC2 CBC with PKCS5 padding 128-bit AES CBC with PKCS5 padding 192-bit AES CBC with PKCS5 padding 256-bit AES CBC with PKCS5 padding
Encryption Certificate(s):	Public certificates to encrypt the document. A list or a single certificate can be chosen to encrypt the same document. When you choose multiple certificates, it allows multiple recipients to decrypt the message. Optional.
Signature Options	Options to sign the message. Required. Valid values are: Single Signature (default) Multiple Signatures Counter Signature No Signature Required
Signing Algorithm	The signing algorithm to hash the document. Optional. Valid values are: SHA1 (default) MD5
Signing Certificate(s)	Private certificates to sign the document. Optional. Valid values are: Select a signing certificate if you have selected Single Signature. Select a list of signing certificates for multiple users to sign the document if you have selected Multiple Signatures. Select a list of signing certificates for multiple users to sign the document and countersign the signature if you have selected Counter Signature.
Message Input Format	Message input format for parsing the signed or encrypted message. Required. Valid values are: SMIME (default) DER PEM
Security Type	This parameter is enabled only if you select either PEM or DER as the message input format.Security type that is applied to the inbound cryptographic message. Optional. Valid values are: Encrypted Only (default) - The inbound message is encrypted only. Detached Signed Only - The inbound message is signed in detached format. Embedded Signed Only - The inbound message is signed in embedded format. Detached Signed and Encrypted - The inbound message is signed in detached format and then encrypted. Embedded Signed and Encrypted - The inbound message is signed in embedded format and then encrypted.
Decryption Certificate	Private certificate to decrypt the cryptographic message. Optional.
Signature Verification Certificate(s)	Public certificates to verify signed cryptographic message. Optional. Note: You can select single certificate if the inbound message is signed by one certificate or select a list of certificates if multiple certificates sign the inbound message. Based on the certificates list sequence, counter-signature verification starts from the first level of the signature.

Parameters That Must Be Added in BPML

The following additional parameters are available for use with the Cryptographic Message service, but can only be added by editing your business process manually. This parameter is not available through the Admin console or the GPM:

Parameter	Description
Action	Required. The two values are either `build` or `parse`.
pipelineTimeout	Optional. Controls the duration of building or parsing process. By default, the value is 300 seconds and can be increased to process large files.
pipeSize	Optional. Size of the pipe (in bytes) created to carry out pipeline activities. By default, the value is 4096 bytes. The allowed values are any valid non-negative integer values. Note: The `pipeSize` value should always be greater than the `bufferSize` value. The `pipeSize` parameter must be used only when dealing with large MIME headers where the header size is greater than 1024 bytes.
bufferSize	Optional. Size of the buffer (in bytes) to contain the incoming data. By default, the value is 1024 bytes. The allowed values are any valid non-negative integer values. Note: The `pipeSize` value should always be greater than the `bufferSize` value. The `bufferSize` parameter must be used only when dealing with large MIME headers where the header size is greater than 1024 bytes.

Business Process Examples

The parameters passed from the BPML precede over the parameters passed from the service. The following BPML examples illustrate using the cryptographic message service instance:

Example Business Process 1

The following BPML builds the cryptographic messages based on the parameters passed from BPML to the service or the configuration set in CMS instance configuration.

<process name="cryptomsg_build">
  <sequence>
       <operation name="Crypto Message Service">
           <participant name="CryptoMsgService"/>
           <output message="buildRequest">
               <assign to="." from="*"/>
               <assign to="action">build</assign>
           </output>
          <input message="buildResponse">
              <assign to="." from="*"/>
          </input>
       </operation>
   </sequence>
</process>

Example Business Process 2

The following BPML parses the cryptographic messages based on the parameters passed from BPML to the service or the configuration set in CMS instance configuration.

<process name="cryptomsg_parse">
   <sequence>
      <operation name="Crypto Message Service">
          <participant name="CryptoMsgService"/>
          <output message="parseRequest">
              <assign to="." from="*"/>
              <assign to="action">parse</assign>
          </output>
           <input message="parseResponse">
               <assign to="." from="*"/>
           </input>
      </operation>
    </sequence>
</process>

Example Business Process 3

The following BPML builds and parses the cryptographic messages based on the parameters passed from BPML to the service or the configuration set in CMS instance configuration.

<process name="cryptomsg_buildandparse">
   <sequence>
    <operation name="Crypto Message Service">
      <participant name="CryptoMsgService"/>
         <output message="buildRequest">
           <assign to="." from="*"></assign>
           <assign to="action">build</assign>
           <!-- securityType=3 Encrypted Only,
                securityType=1 Detached Signed Only,
                securityType=2 Embedded Signed Only,
           	     securityType=4 Detached Signed and Encrypted,
                	securityType=5 Embedded Signed and Encrypted -->
           <assign to="securityType">4</assign>		
           <!-- signOptions=0 No Signature Required,
                signOptions=1 Single Signature,
                signOptions=2 Multiple Signatures,
                signOptions=3 Counter Signature -->		
           <assign to="signOptions">3</assign>
           <assign to="signAlgo">SHA1</assign>
           <assign to="signCerts">smime_priv1,smime_priv2,smime_priv3</assign>
           <!-- encryption algorithm
	        encAlgo=0 Triple DES 168 CBC with PKCS5 padding 
                encAlgo=1 56-bit DES CBCwith PKCS5 padding
                	encAlgo=2 128-bit RC2 CBC with PKCS5 padding
                encAlgo=4 40-bit RC2 CBC with PKCS5 padding
                	encAlgo=6 128-bit AES CBC with PKCS5 padding
	     encAlgo=7 192-bit AES CBC with PKCS5 padding
                	encAlgo=8 256-bit AES CBC with PKCS5 padding -->
           <assign to="encAlgo">0</assign>
           <assign to="encCerts">smime_pub1,smime_pub2</assign>
         </output>
          <input message="buildResponse">
             <assign to="." from="*"></assign>
         </input>
       </operation>  

       <operation name="Crypto Message Service">
          <participant name="CryptoMsgService"/>
          <output message="parseRequest">
              <assign to="." from="*"/>
              <assign to="action">parse</assign>
             <assign to="verifyCerts">smime_pub3,smime_pub2,smime_pub1</assign>
  	 <assign to="decryptCert">smime_priv1</assign>
         </output>
          <input message="parseResponse">
             <assign to="." from="*"/>
         </input>
       </operation>	
  </sequence>
</process>

Example Business Process 4

The following BPML puts the detached document under the detachedDoc area when parsing detaching only inbound message in PEM or DER format.

<process name="cryptomsg_parse">
   <sequence>
        <operation name="Import Document Request">
           <participant name="CryptoMsgTestFSA"/>
           <output message="FileSystemInputMessage">
               <assign to="Action">FS_COLLECT</assign>
               <assign to="collectionFolder" from="'/gisinstall'"/>
               <assign to="filter" from="'detached_doc.txt'"/>
                <assign to="useSubFolders">fals</assign>e<assign to="useSubFolders">false</assign>
               <assign to="bootstrap">false</assign>
                <assign to="deleteAfterCollect">fals</assign>e<assign to="deleteAfterCollect">false
                </assign>
               <assign to="." from="*"/>
           </output>
            <input message="FileSystemOutputMessage">
               <assign to="." from="*"/>
           </input>
         </operation>
        	<assign to="detachedDoc" from="PrimaryDocument/@SCIObjectID"/>	
        <operation name="Import Document Request">
           <participant name="CryptoMsgTestFSA"/>
           <output message="FileSystemInputMessage">
               <assign to="Action">FS_COLLECT</assign>
                <assign to="collectionFolder" from="'/gisinstall'"/>
               <assign to="collectionFolder" from="'/gisinstall'"/>
               <assign to="filter" from="'signed_msg.txt'"/>
	<assign to="useSubFolders">false</assign>
               <assign to="bootstrap">false</assign>
                <assign to="deleteAfterCollect">false</assign>
                <assign to="deleteAfterCollect">false</assign>
               <assign to="." from="*"/>
           </output>
            <input message="FileSystemOutputMessage">
               <assign to="." from="*"/>
           </input>
       </operation>
      <operation name="Crypto Message Service">
         <participant name="CryptoMsgService"/>
         <output message="parseRequest">
             <assign to="." from="*"/>
             <assign to="action">parse</assign>
             <!--securityType=3 Encrypted Only,
	securityType=1 Detached Signed Only,
	securityType=2 Embedded Signed Only,
	         securityType=4 Detached Signed and Encrypted,
	            securityType=5 Embedded Signed and Encrypted -->
             <assign to="securityType">1</assign>	
             <!--msgFormat=0 SMIME,
                 msgFormat=1 DER,
                 msgFormat=2 PEM -->			
             <assign to="msgFormat">2</assign>		
             <assign to="verifyCerts">smime_pub1</assign>  
          </output>
         <input message="parseResponse">
             <assign to="." from="*"/>
         </input>
       </operation>	
  </sequence>
</process>

Output from Service to Business Process

The following table describes the output from the cryptographic message service to the BPML ProcessData, when the service action is “build”:

Scenario	Output
Certificates used for encryption are acceptable	`<EncryptCerts> <Cert1> <Name>smime_pub1</Name> <Status>ok</Status> <ExpiryTime>20350726074016Z</ExpiryTime> </Cert1> <Cert2> <Name>smime_pub2</Name> <Status>ok</Status> <ExpiryTime>20350726074056Z</ExpiryTime> </Cert2> </EncryptCerts>`
Certificate used for encryption or signing has expired	`<SigningCerts> <Cert1> <Name>smime_pub1</Name> <Status>expired</Status> <ExpiryTime>20070726074016Z</ExpiryTime> </Cert1> </SigningCerts> <exception-message>xxx</exception-message>` Or `<EncryptCerts> <Cert1> <Name>smime_pub1</Name> <Status>expired</Status> <ExpiryTime>20070726074016Z</ExpiryTime> </Cert1> <Cert2> <Name>smime_pub2</Name> <Status>ok</Status> <ExpiryTime>20350726074056Z</ExpiryTime> </Cert2> </EncryptCerts>`
Certificate used for encryption has been revoked	`<EncryptCerts> <Cert1> <Name>cert1</Name> <Status>revoked</Status> </Cert1> </EncryptCerts> <exception-message>xxx</exception-message>`
Certificate used for encryption fails to process. For example, if the encryption certificate is not found in Sterling B2B Integrator.	`<EncryptCerts> <Cert1> <Name>cert1</Name> <Status>error</Status> </Cert1> </EncryptCerts> <exception-message>xxx</exception-message>`

The following table describes the output from the cryptographic message service to BPML ProcessData, when the service action is "parse":

Scenario	Output
Decryption is passed	`<DecryptionResult> <DecryptionCertName>smime_priv1</DecryptionCertName> <DecryptionCertStatus>ok</DecryptionCertStatus> <DecryptionCertExpiryTime>20350726074016Z </DecryptionCertExpiryTime> <Status>passed</Status> </DecryptionResult>`
Decryption certificate not found in Sterling B2B Integrator	`<DecryptionResult> <DecryptionCertName>cert1</DecryptionCertName> <DecryptionCertStatus>error</DecryptionCertStatus> <Status>failed</Status> </DecryptionResult>`
Decryption certificate failed to decrypt	`<DecryptionResult> <DecryptionCertName>smime_priv2</DecryptionCertName> <DecryptionCertStatus>ok</DecryptionCertStatus> <DecryptionCertExpiryTime>20350726074056Z </DecryptionCertExpiryTime> <Status>failed</Status> </DecryptionResult>`
Signature verification is passed	<SignatureVerificationResults> <SignatureVerificationResult1> <VerificationCertName>smime_dsa_pub</VerificationCertName> <VerificationCertStatus>ok</VerificationCertStatus> <VerificationCertExpiryTime>20350812084354Z </VerificationCertExpiryTime> <SigningTime>20080917021420Z</SigningTime> <Status>passed</Status> </SignatureVerificationResult1> <SignatureVerificationResult2> <VerificationCertName>smime_pub4</VerificationCertName> <VerificationCertStatus>ok</VerificationCertStatus> <VerificationCertExpiryTime>20350726074148Z </VerificationCertExpiryTime> <SigningTime>20080917021420Z</SigningTime> <Status>passed</Status> </SignatureVerificationResult2> <Status>passed</Status> </SignatureVerificationResults>
Signature verification fails	<SignatureVerificationResults> <SignatureVerificationResult1> <VerificationCertName>smime_pub4</VerificationCertName> <VerificationCertStatus>ok</VerificationCertStatus> <VerificationCertExpiryTime>20350726074148Z </VerificationCertExpiryTime> <SigningTime>20080917021549Z</SigningTime> <Status>passed</Status> </SignatureVerificationResult1> <SignatureVerificationResult2> <VerificationCertName>smime_pub3</VerificationCertName> <VerificationCertStatus>ok</VerificationCertStatus> <VerificationCertExpiryTime>20350726074122Z </VerificationCertExpiryTime> <SigningTime>20080917021549Z</SigningTime> <Status>failed</Status> </SignatureVerificationResult2> <Status>failed</Status> </SignatureVerificationResults>
Multiple signature verification fails	<SignatureVerificationResults> <SignatureVerificationResult1> <SigningTime>20080917071327Z</SigningTime> <Status>nomatched_verificationCert</Status> </SignatureVerificationResult1> <SignatureVerificationResult2> <VerificationCertName>smime_pub3</VerificationCertName> <VerificationCertStatus>ok</VerificationCertStatus> <VerificationCertExpiryTime>20350726074122Z </VerificationCertExpiryTime> <SigningTime>20080917021549Z</SigningTime> <Status>failed</Status> </SignatureVerificationResult2> <Status>failed</Status> </SignatureVerificationResults>
Signature verification certificate is revoked	`<SignatureVerificationResults> <SignatureVerificationResult1> <SigningTime>20080917024531Z</SigningTime> <VerificationCertName>serenaCRL1</VerificationCertName> <VerificationCertStatus>revoked</VerificationCertStatus> </SignatureVerificationResult1> <Status>failed</Status> </SignatureVerificationResults>`

The CMS service allows you to use an expired certificate to encrypt/decrypt or sign/verify the message if “validity” flag is not enabled when you check in the certificate into the system. The certificate status and expiry time is shown in the ProcessData as part of CMS service output.

The certificate ExpiryTime and SigningTime is displayed in UTC timezone in yyyyMMddHHmmssZ format. The BPML can perform the following checks after calling the CMS service:

ExpiryTime against SigningTime to determine if the signature verified by the expired certificate is acceptable or not.
ExpiryTime against the current date to determine if the encrypted or signed data created the expired certificate is acceptable or not.