SMIME

Create digitally signed and/or encrypted MIME messages. You also use the services in this folder to process signed and encrypted MIME messages that are passed into the pipeline.

createCertsOnlyData

Generates a PKCS #7 certs-only S/MIME entity from an array of certificates. This service can be used to develop mechanisms for transmitting certificates and certificate chains to other parties.

Input parameters for createCertsOnlyData

certificates: byte[] The certificates that are to be encapsulated within the S/MIME entity. Each byte[] represents a single certificate.

Output parameters for createCertsOnlyData

SMimeEnvStream: java.io.InputStream S/MIME entity.

createEncryptedData

Encrypts a MIME message.

Input parameters for createEncryptedData

  • envStream: java.io.InputStream MIME message that you want to encrypt (for example, the output produced by getEnvelopeStream service under MIME group).
  • recipientCerts: byte[] The X.509 certificates of the recipients for whom this message will be encrypted. Each element in the list represents a certificate for a single recipient in the form of a byte[].
    Note: When you have multiple recipients, createEncryptedData creates a single message that is encrypted for all recipients. It does not create a separate message for each recipient.
  • encryptionAlg: String. Code specifying the encryption algorithm to use. Must be TripleDES (default), DES, or RC2.
  • keyLength: String. Length of the encryption key for RC2 encryption. Must be 40, 64, or 128 (default). This parameter is ignored if encryptionAlg is not RC2.

Output parameters for createEncryptedData

SMimeEnvStream: java.io.InputStream The encrypted MIME message.

processCertsOnlyData

WmPublic. Extracts the certificates from a PKCS #7 certs-only S/MIME entity.

Input parameters for processCertsOnlyData

SMimeEnvStream: java.io.InputStream The certs-only S/MIME entity.

Output parameters for processCertsOnlyData

certificates: byte[] The extracted certificates. Each element in the list contains one of the extracted certificates represented as a byte[].

processSignedData

Verifies the signature from a signed S/MIME entity and extracts the message from it.

Input parameters for processSignedData

  • SMimeEnvStream: java.io.InputStream Signed MIME entity (for example, the output produced by createSignedData from SMIME).

  • signerCertChain: byte[] Optional. Certificate chain of the party that signed the message, where each byte[] represents a single certificate in the chain. Certificates must appear in hierarchical order, starting with the signer's certificate in element 0. The following shows how the elements of a complete chain would appear for a certificate that was issued through two intermediate CAs:
    Element Contents
    0 Signer's certificate.
    1 Intermediary CA Certificate.
    2 Intermediary CA Certificate.
    3 Root CA Certificate.
    Note: If the signer included the certificate chain with the digital signature, you do not need to supply signerCertChain.

Output parameters for processSignedData

  • mimeData: Document MIME object containing the extracted MIME entity.
  • contentDigest: String Message digest (base64-encoded) that was recalculated by processSignedData.
  • signerCert: java.security.cert.X509Certificate Signer's X.509 certificate.
  • encrypted: String Conditional. Flag indicating whether the extracted MIME entity is encrypted. A value of:
    • true indicates that the MIME entity is encrypted.
    • false indicates that the MIME entity is not encrypted.
  • signed: String Conditional. Flag indicating whether the extracted MIME entity is signed. A value of:
    • true indicates that the MIME entity is signed.
    • false indicates that the MIME entity is not signed.
  • certsOnly: String Conditional. Flag indicating whether the extracted MIME entity is a certs-only entity. A value of:
    • true indicates that the MIME entity is a certs-only entity.
    • false indicates that the MIME entity is not a certs-only entity.
  • stream: java.io.InputStream Conditional. Extracted MIME entity.
  • verify: String Flag indicating whether the signature was successfully processed. Success indicates that the signature was successfully verified with the supplied public key. A value of:
    • true indicates that signature processing was successful.
    • false indicates that signature processing failed. The signature could not be verified because an errorCode 1, 2, 3, or 4 occurred.
  • trusted: String Flag indicating whether the signer certificate is trusted or not. A value of:
    • true indicates that the signer certificate is trusted.
    • false indicates that the signer certificate is not trusted.
  • errorCode: String Conditional. Number indicating the kind of error that occurred while processing the signature. See errorMessage for possible values. If no error occurred, errorCode will not be returned.
  • errorMessage: String Conditional. Textual error message indicating what kind of error occurred while processing the signature. Error codes and messages are as follows:
    errorCode errorMessage
    1 Invalid signer certificate file information.
    2 Certificate at index 'i' is not in recognizable format.
    3 Invalid certificate input at index 'i'.
    4 Signature cannot be verified.
    5 Expired certificate chain.
    6 Error in certificate chain.
    7 Untrusted certificate

Usage notes for processSignedData

  • If verify is false, the errorCode and errorMessage values will indicate the error that caused the failure. Note that errorCode values 5 through 7 do not represent signature-validation failures and, therefore, do not cause the verify flag to be set to false.
  • If the extracted entity is signed or encrypted, mimeData will be empty, and the extracted entity will reside in stream. You can check the state of the signed and encrypted output variables to determine whether the extracted entity requires additional processing, and pass stream to the processEncryptedData service as necessary.
Important: You can examine the contents of mimeData during testing and debugging. However, because the internal structure of mimeData is subject to change without notice, do not explicitly set or map data to/from these elements in your service. To manipulate or access the contents of mimeData, use only the MIME services that server provides.

createSignedData

WmPublic. Creates signed S/MIME data.

Input parameters for createSignedData

  • envStream: java.io.InputStream MIME message that you want to sign (for example,the output produced by pub.mime:getEnvelopeStream).
  • keyStoreAlias: String Alias of the keystore.
  • keyAlias: String Alias of the private key of interest in the keystore.
  • explicit: String. Flag indicating whether an implicit or explicit signature is generated. Set to:
    • True to generate an explicit (detached) signature. This is the default.
    • False to generate an implicit signature.
  • signingAlg: String. The signing algorithm to use to sign the S/MIME messages. Set to:
    • SHA1
    • SHA224
    • SHA256
    • SHA384
    • SHA512

    The default is SHA1.

    Note: If you do not set this parameter, server uses SHA1 algorithm to sign the incoming messages.

Output parameters for createSignedData

SMimeEnvStream: java.io.InputStream The signed MIME stream.

processEncryptedData

Decrypts an encrypted S/MIME message.

Input parameters for processEncryptedData

  • SMimeEnvStream: java.io.InputStream The encrypted S/MIME stream.
  • keyStoreAlias: String Alias of the keystore containing the decryption key.
  • keyAlias: String Alias of the key used for decryption.

Output parameters for processEncryptedData

  • mimeData: Document The decrypted MIME message.
  • contentDigest: String Message digest of the encrypted content, base64-encoded. (Some sites return this digest to the sender to acknowledge their receipt of the message.
  • encrypted: String Flag indicating whether the MIME entity passed in to the service was encrypted. A value of:
    • True indicates that the MIME entity was encrypted.
    • False indicates that the MIME entity was not encrypted.
  • signed: String Flag indicating whether the MIME entity passed in to the service was signed. A value of:
    • True indicates that the MIME entity is signed.
    • False indicates that the MIME entity is not signed.
  • certsOnly: String Flag indicating whether the MIME entity passed in to the servicen contained only digital certificates. A value of:
    • True indicates that the MIME entity is a certs-only entity.
    • False indicates that the MIME entity is not a certs-only entity.
  • stream: java.io.InputStream The decrypted MIME entity.