API ReferenceDiscussions

Encrypting a Document

Encrypting a document using a SENxContext.

Suggest Edits

In this following example, we create a context for encryption and have chosen the Aes256Cbc cipher along with Sha256 as our hash algorithm. Using the context, the file contents of sample.pdf are encrypted using the public key associated with route 8565551234. The resulting cryptogram may be delivered using the SendFax() method.

Any errors encountered using the SENxContext will result in a CryptoException being thrown.

Behind the scenes, the encryption process uses the public key of the destination peer to generate a shared secret. A KDF (Key Derivation Function) function is then used to derive keying material used for the AES encryption operation. Upon successful completion of the encrypt function, the returned cryptogram will contain a unique ephemeral public key including the ciphering and hashing algorithms chosen, a keyed hash-based message authentication code (HMAC), and the encrypted payload itself. Should any information be tampered with along the way, the decryption process will fail.

Details of this process are explained here.

🚧

Programming Example

For the sake of brevity, this programming example has omitted error checking (file load, etc.).

// initialize SENx
SENx.Initialize();

try
{
    // retrieve route information
    var route = client.GetRouteInfo("8565551234");
    if (route != null &&
        route.Encryption != null &&
        route.Encryption.Enabled)
    {
        // let's do some encryption
        // ...
    }
      
    ...
      
    // create context, aes256cbc + sha256
    using (var context = new SENxContext(CryptoAlgorithm.Aes256Cbc, HashAlgorithm.Sha256))
    {
        // read all bytes from file
        var data = File.ReadAllBytes("sample.pdf");

        // load public key of destination
        var res = context.LoadKeyFromBuffer(route.Encryption.PublicKey);
        Console.WriteLine("LoadKeyFromBuffer: " + res);
      
        // encrypt payload into cryptogram
        var cryptogram = context.Encrypt(data);

        // create fax
        var fax = new FaxSend()
        {
            DialNumber = "8565551234",
            FaxImage = cryptogram
        };

        // begin sending the fax
        var result = client.SendFax(fax);
      
        // ...
    }
}
catch (CryptoException e)
{
    Console.WriteLine("CryptoException: {0} {1}", e.Result, e.Message);
}

// release all resources
SENx.Cleanup();

When querying a route, information returned in the Encryption section must be observed by the sending application.

NameDescription
EnabledIndicates whether encryption is enabled for this route/endpoint.
RequiredIndicates whether encryption is required/mandatory for this route/endpoint. If the peer has set this flag, the network will only accept cryptograms during fax submission.
PublicKeyContains the peer's public key in base64-encoded PEM format.

An example response from a route query:

{
  "Route": "+18565551234",
  "AcceptedFormats": [
    "image/tiff"
  ],
  "Resolutions": [
    "204x98",
    "204x196",
    "300"
  ],
  "PageWidths": [
    "a4"
  ],
  "Encryption": {
    "Enabled": true,
    "Required": false,
    "PublicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlHYk1CQUdCeXFHU000OUFnRUdCU3VCQkFBakE0R0dBQVFCb2J3NUJQSC9ENUpleGpRcGpMN0dLbUdHZkc0MwpEYTZHU2hzbkVjNGh3VWVCNEVLUDZ3WjFoYlp3cHRBUjhqYmNxWTJ3YlAreExmT3FBR0RZUC9vMTBBTUI1M3kzCjRzaDA2azdzSzhVKzY1SUhZZ3B6WjR3WWw1emsrQTQ2ZkRQUVhoS3BEdlVnWjExcm9WYUpOYUROK0p3QjFZT1UKbllNTUwzY05QZUs0dS9lcnBHMD0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg=="
  },
  "Name": "Pearson Medical"
}

📘

Encryption Algorithm (Cipher)

Though the SENx library does support various forms of AES, some peers may not be able to decrypt more advanced variants such AES/GCM. For best success, it is recommended to use the AES/CBC ciphers for maximum compatibility with other peers.

Updated about 6 years ago

What’s Next