Automation

Communication Generation

Automation takes data payloads, processes them through workflow and populates templates that generate communication in a variety of output formats and channels.

Overview

This document contains information pertaining to the sending of payloads from the clients systems to CloudDirect for the purposes of creating single & batch output for delivery to the end customer.

Communication is secured using self-signed server & client SSL certificates. The client certificate provides an additional level of security that ensures the initial handshake is accepted only when a valid client certificate is provided.

The output created is forwarded onto the end customer via the required delivery channel; eg: e-mail, print

The payloads are sent to an endpoint hosted in the CloudDirect system & managed by the application Automation.

Exclusions

This document does not contain information on the specifics of

• How payloads will be processed once received by CloudDirect
• How generated output will be delivered via it’s required delivery channel
• Fields in the payloads used for identifying
  • delivery channels
  • client specific information; eg: client name
  • batching ID’s
  • etc
• endpoints for other client payloads

Communication Protocol

• Communication is performed over HTTPS using the HTTPS request-response protocol operating across TCP/IP
• Secure communication is established using a set of self-signed server & client certificates
• The request Method is POST
• The payload to be delivered for processing is sent as a stream in the HTTPS request data
• The request Content Type is text/xml
  • This is not a strict requirement that will cause an error if not adhered to absolutely
• The response will be either a plain text message or a file stream (see Responses→Success)

SSL certificates

Secure communication between the CloudDirect server & the client server will be established using a set of self-signed server & client certificates.

The client certificate will be directly associated with a server certificate (located on the CloudDirect server) which ensures that only valid certificates can connect & establish a secured communication channel. The format of the certificate will be PKCS #12 (see Appendix for a description of this format). The extension of the certificate will be .p12 The request sent to the endpoint must include the client certificate as part of the request.

Any requests sent to the endpoint without a valid client certificate, or no client certificate, will result in a 403 Access is Forbidden error.

The client certificate can be installed in the Windows Certificates Store or stored on disk.

If the certificate is installed in the Windows Certificates Store, it has to be placed in Local Machine -> Personal -> Certificates

See this link for installing certificates to the Local Machine -> Personal Certificates store: https://technet.microsoft.com/en-us/library/cc995171.aspx

See this link for an overview of certificate operations: https://social.technet.microsoft.com/wiki/contents/articles/2167.how-to-use-the-certificates-console.aspx

See the Example Code section below for a C# example of how to read the client certificate & supply it as part of the request. Note that because the certificates are self-signed, the request may throw an error thinking the server certificate is not trusted (since it’s not listed in the Trusted Root Authority). This does not compromise security; eg: MITM attacks; due to the requirement of the client certificate needing to be authenticated against the server certificate to establish a connection. The example code includes a function which allows valid self-signed server certificates to be used in the request.

Endpoint

Payloads to be processed are delivered to the endpoint https://test.edm.clouddirect.biz/dev// This endpoint receives payloads into the testing environment in CloudDirect. The generated output will contain a watermark indicating that the generated output is not in Production.

An endpoint for the production environment will be advised.

Responses

Success

Important: See the Notes section below Upon successful receipt & completion of processing a payload

• An HTTP status code of 200 is returned
• The HTTPS response will contain either a plain text message or a PDF file, which will be determined by the delivery channel (specified by a field in the payload). Following are the delivery channel values & the corresponding HTTPS responses
  • email
    • The plain text message Job finished successfully.
  • print
    • The plain text message Job finished successfully.
  • return
    • A PDF document of the processed payload

Error

If a payload encounters any errors during processing

• An HTTP status code of 400 is returned
• The HTTPS response will contain the plain text message Job failed to process successfully. Reason:

Any other error codes encountered will be according to the standard HTTP status codes. See https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

Notes

• As the field in the payload identifying how a document should be delivered; ie: e-mail/print/return; is still undefined, all payloads are currently processed as individual documents & returned to the client in the HTTPS response
• The current HTTPS responses may be altered based on further clarification from the client

Example code

Below is a C# example of

• Loading the client certificate
• Allowing valid self-signed server certificates
• Creating the request, assigning the client certificate & including the payload
• Receiving the PDF response Note that specific handling of error status codes is not implemented.

private static bool ValidateServerCertificate(object sender, X509Certificate
ServerCertificate, X509Chain Chain, SslPolicyErrors SSLPolicyErrors)
{
  //If the server certificate is a valid, signed certificate, return true
  if (SSLPolicyErrors == SslPolicyErrors.None)
    return true;

  //If there are errors in the certificate chain, look at each error to determine the cause
  if ((SSLPolicyErrors & SslPolicyErrors.RemoteCertificateChainErrors)!= 0)
  {
    if (Chain != null && Chain.ChainStatus != null)
    {
      foreach (X509ChainStatus CertStatus in Chain.ChainStatus)
      {
        if ((ServerCertificate.Subject == ServerCertificate.Issuer) && (CertStatus.Status == X509ChainStatusFlags.UntrustedRoot))
        {
          //Self-signed certificates with an untrusted root are valid
          continue;
        }
        else {
          if (CertStatus.Status != X509ChainStatusFlags.NoError)
          {
            //If there are any other errors in the certificate chain, the certificate is invalid; return false
            return false;
          }
        }  //else if certstatus
      }  //foreach certstatus
    } //if chain!=null

    //When processing reaches this line, the only errors in the certificate chain are untrusted root errors for self-signed server certificates. These certificates are valid; return true.
    return true;
  } //if sslpolicyerrors!=0
  else //in all other cases, return false
    return false;
  }

private void Process()
{
  string Endpoint = "https://test.edm.clouddirect.biz/dev/<TBC>";
  //Set the SSL client certificate (imported into Personal -> Certificates) search value string SSLFindByValue = "CloudDirect";
  //Read certificates from Local Machine -> Personal certificates store X509Store CertStore = new X509Store("My", StoreLocation.LocalMachine); CertStore.Open(OpenFlags.ReadOnly);
  //Locate the required client certificate.
  //Note that the ValidOnly parameter must be set to 'false' as the self-signed certificate
  //may be classed as not valid since it has no root certificate (it will be validated //against the server certificate).
  X509Certificate2Collection SSLCollection = CertStore.Certificates.Find(X509FindType.FindByIssuerName, SSLFindByValue, false);
  CertStore.Close();
  if (SSLCollection.Count == 0) //error finding matching certificate
    throw new Exception("Unable to find the client certificate.");
  X509Certificate2 SSLCertificate = SSLCollection[0];
  /*
  ** The certificate can also be loaded from file if it's not saved to the certificate store
  X509Certificate SSLCertificate = new X509Certificate(@"C:\Certificates\CloudDirect.p12");
  */

  //Allow self-signed server certificates
  ServicePointManager.ServerCertificateValidationCallback = ValidateServerCertificate;

  //Create the request
  HttpWebRequest HTTPRequest = (HttpWebRequest)WebRequest.Create(Endpoint); HTTPRequest.KeepAlive = false;
  //Add SSL certificate to request HTTPRequest.ClientCertificates.Add(SSLCertificate);
  //Set the Method property of the request to POST HTTPRequest.Method = WebRequestMethods.Http.Post;
  //Load data file for POST data
  XmlDocument InputXML = new XmlDocument(); InputXML.Load(<path to XML file>);
  //Set the ContentType property of the WebRequest HTTPRequest.ContentType = "text/xml";
  //Get the request stream
  Stream DataStream = HTTPRequest.GetRequestStream();
  //Write the data to the request stream InputXML.Save(DataStream);
  //Close the Stream object DataStream.Close();
  //Get the response
  try
  {
    HttpWebResponse HTTPResponse = (HttpWebResponse)HTTPRequest.GetResponse();
    //!! The status code & status description can be checked here
    //Get the stream containing content returned by the server DataStream = HTTPResponse.GetResponseStream();
    //Save the stream to disk
    using (Stream SaveFile = File.Create(txtbxSaveTo.Text)) {
      DataStream.CopyTo(SaveFile); //save returned content to disk
    } //using savefile
    
    //Clean up the streams
    DataStream.Close();
    HTTPResponse.Close();
  } //try httpresponse
  catch(WebException Ex)
  {
    StreamReader ExStream = new StreamReader(Ex.Response.GetResponseStream(), true );
    MessageBox.Show(ExStream.ReadToEnd(), "Processing error");
    ExStream.Close();
  }
}

Appendix

PKCS #12

The PKCS #12 format is a binary format for storing the certificate, any intermediate certificates, and the private key into a single encryptable file. PKCS #12 files are usually found with the extensions .pfx and .p12. PKCS #12 files are typically used on Windows machines to import and export certificates and private keys.

Errors

Following is a list of errors that may be received when sending a request & the possible solutions for those errors.