Marking Documents with EchoMark API

A document is any markable content that can be persistent and archived. In other words, for the duration of your use of EchoMark you need to be able to retrieve and present the original content during investigations. For document content, EchoMark recreates all of the marked copies during the investigation. This allows for a highly robust investigation of any potential artifact. However, recreation of these marked copies requires that the exact original content is provided to the system.

The API server maintains a list of all recipients for whom it has ever been requested to mark this original document, and also that EchoMark knows how to associate this original with each of those recipients if presented with exactly the same original used to generate those copies. 

All of the static marking endpoints accept multipart form data as input with mark options and a file payload.

Content-Type: multipart/form-data; boundary=----FormBoundary7MA4YWxkTrZu0gW 
------FormBoundary7MA4YWxkTrZu0gW 
Content-Disposition: form-data; name="original; filename="secure.jpg" 
Content-Type: image/jpeg 
 
[Binary data of the JPEG file] 
------FormBoundary7MA4YWxkTrZu0gW 
Content-Disposition: form-data; name="mark_options" 
Content-Type: application/json 
 
{ 
  "recipient": "exployeeid_dwwhijtoarkbmkkz", 
  "recipient_name": "Alice Bar", 
  "image_watermarking_enabled": true, 
  "image_watermarking_options": { 
    "algorithm": "auto", 
    "color_distortion_limit": 3, 
    "spatial_distortion_limit": 5 
  }, 
  "text_watermarking_enabled": true, 
  "text_watermarking_options": { 
    "rendering_intent": "screen" 
  }, 
  "visible_watermarking_enabled": true, 
  "visible_watermarking_options": { 
    "text": "Personalized for {{recipient}}", 
    "position": "footnote", 
    "color": "000000", 
    "opacity": 1 
  } 
}

 
------FormBoundary7MA4YWxkTrZu0gW--j

They similarly return marked content as a multipart form returning two pieces of information. The marked content (which is to be delivered to the recipient) and the mark schema.  The mark schema is a “recipe” for regenerating a particular marked copy with version information and checksums etc. This data is persisted by EchoMark's API server but it is useful for the developer to log this data as well. It acts as a sort of receipt for marking, and in the event of data loss, can be used to investigate.

Content-Type: multipart/form-data; boundary=----FormBoundary7MA4YWxkTrZu0gW 
------FormBoundary7MA4YWxkTrZu0gW 
Content-Disposition: form-data; name="marked_copy" 
Content-Type: image/jpeg 
 
[Binary data of the JPEG file] 
------FormBoundary7MA4YWxkTrZu0gW 
Content-Disposition: form-data; name="marking_schema" 
Content-Type: application/json 
 
{ 
  "mark_schema": { 
    "mark_options": { 
      "recipient": "exployeeid_dwwhijtoarkbmkkz", 
      "recipient_name": "Alice Bar", 
      "image_watermarking_enabled": true, 
      "image_watermarking_options": { 
        "algorithm": "auto", 
        "color_distortion_limit": 3, 
        "spatial_distortion_limit": 5 
      }, 
      "text_watermarking_enabled": true, 
      "text_watermarking_options": { 
        "rendering_intent": "screen" 
      }, 
      "visible_watermarking_enabled": true, 
      "visible_watermarking_options": { 
        "text": "Personalized for {{recipient}}", 
        "position": "footnote", 
        "color": "000000", 
        "opacity": 1 
      } 
    }, 
    "content_type": "image/jpeg", 
    "sha256": "b94d27b99a1139c96512636b670770f40d25090598f61a113072927934519187", 
    "original_seed_checksum": "b94d27b99a1139c96512636b670770f40d25090598f61a113072927934519187" 
  }, 
  "version": 2, 
  "version_details": "{\"ImageEngineVersion\": \"a927934519187\", \"PDFEngineVersion\": \"b94d27b99a1139\"}" 
}

 
------FormBoundary7MA4YWxkTrZu0gW--j

The developer can anticipate the following responses from the API call.

JSON Mode

By default, your container will accept multipart form requests. But, you can use json requests if pass in a URL argument ?json=True to any of the endpoints below. In this mode, your files will be encoded as a base64 string instead of multipart forms. 

Content-Type: application/json 
{ "original": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=", 

"content_type": "image/png", 

"mark_options": 

{ "recipient": "exployeeid_dwwhijtoarkbmkkz", 

"recipient_name": "Alice Bar", 

"image_watermarking_enabled": true, 

"image_watermarking_options": { 

"algorithm": "auto", 

"color_distortion_limit": 3, 

"spatial_distortion_limit": 5 

}, 

"text_watermarking_enabled": true, 

"text_watermarking_options": { 

"rendering_intent": "screen" 

}, 

"visible_watermarking_enabled": true, 

"visible_watermarking_options": { 

"text": "Personalized for {{recipient}}", 

"position": "footnote", 

"color": "000000", 

"opacity": 1 } 

} 

}

Similarly, responses to the above requests will be returned as JSON as well. Note that the names of the parts are consistent the only difference is that the file parts are included in the json structure as base64 encoded strings. 

Content-Type: application/json 
{

  “marked_copy”: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=" 
  "mark_schema": { 
    "mark_options": { 
      "recipient": "exployeeid_dwwhijtoarkbmkkz", 
      "recipient_name": "Alice Bar", 
      "image_watermarking_enabled": true, 
      "image_watermarking_options": { 
        "algorithm": "auto", 
        "color_distortion_limit": 3, 
        "spatial_distortion_limit": 5 
      }, 
      "text_watermarking_enabled": true, 
      "text_watermarking_options": { 
        "rendering_intent": "screen" 
      }, 
      "visible_watermarking_enabled": true, 
      "visible_watermarking_options": { 
        "text": "Personalized for {{recipient}}", 
        "position": "footnote", 
        "color": "000000", 
        "opacity": 1 
      } 
    }, 
    "content_type": "image/jpeg", 
    "sha256": "b94d27b99a1139c96512636b670770f40d25090598f61a113072927934519187", 
    "original_seed_checksum": "b94d27b99a1139c96512636b670770f40d25090598f61a113072927934519187" 
  }, 
  "version": 2, 
  "version_details": "{\"ImageEngineVersion\": \"a927934519187\", \"PDFEngineVersion\": \"b94d27b99a1139\"}" 
}

/document/mark/pdf

A POST request to this API endpoint with PDF file (application/pdf) will return a marked PDF. PDFs are self-contained documents that contain all of the images and design content in a single file container. EchoMark will mark all content in the PDF including embedded content. For example, if the PDF contains an embedded image, EchoMark will mark the image based on the developer's image watermarking settings. All of this content is considered a single "original" for EchoMark's purposes.

/document/mark/html

A POST request to this API endpoint with a HTML document will mark the text body of the document with EchoMark, i.e., adjust the positioning of any static HTML text in the DOM. The endpoint also supports marking HTML fragments. This endpoint will not mark images that happen to be on the HTML document in <img> tags or <canvas> tags. Often, these elements refer to external URLs or are populated asynchronously with Javascript. The returning content will be a marked html document. There are a few tips to ensure design parity with the original.

1. Explicitly define preferred fonts for styles and do not rely on system defaults. EchoMark will override problematic system default fonts that are known to cause issues.
2. Avoid absolute positioning and sizing if possible. EchoMark's spacing may cause minor overflows that do not always interact nicely with absolute sizes.
3. Avoid styles that change word/character spacing, e.g., letter-spacing, word-spacing, text-align: justify, etc.

/document/mark/image

A POST request to this API endpoint with an image file (image/*) will return a marked image. If the image contains any layered information, EchoMark will flatten all layers and mark the flattened file. The return type is of the same format as the input. For example, if you post an image with content type image/png the return type is image/png.

Marking Static Workflow

Now, we diagram an example workflow for the static marking API for developers.

1. Developer has a document that needs to be delivered to a recipient.
2. The developer’s program calls the appropriate /document/mark/* endpoint with the appropriate mark options.
3. The requestor waits for a response if 200 OK, then the extracts the file body from the multipart form response.
   1. An explicit error code implies permanent failure.
   2. A closed connection may indicate the server is busy and the requestor can wait and retry.
4. The requestor delivers the marked file to the end recipient.
5. The developer needs to store  the original document (if not already archived) and the marking schema returned by the multipart form response.