Document classification capabilities

Document classification capabilities provides the ability to manage protective markings to emails. Email+ lists user interface fields to the user when viewing messages, replying to messages, or composing new messages.

The messages that are sent through Email+, adds the markings to the subject line, header, and optionally on the top and the bottom of message body. Email+ supports Protective Marking Standard for the Australian Government (2012 and 2018 versions) and Generic.

  • Classification - To identify the overall sensitivity of the message
  • Distribution Limiting Markers - To limit the distribution

Email classification JSON has two major parts:

  • Scheme
  • Values

Scheme

Scheme includes properties to define email classification behavior. The following table describes the general properties:

Property

Description

topOfBody

Email classification marker to add text at the top of a classified message.

Can include $sec$, $dlm$, $title$, $caveat$ variables.

Default value for AU_2018: {"default" : "$sec$, $caveat$, $dlm$", "noSec" : "$dlm$, $caveat$", "noDlm" : "$sec$, $caveat$", "noCaveat" : "$sec$, $dlm$" }

Default value for AU_2012: {"default" : "$sec$, $dlm$", "noSec" : "$dlm$", "noDlm" : "$sec$"}.

To remove the header and footer the "topOfBody" and "bottomOfBody" value should be set to an empty value: {} or {"default" : ""}.

bottomOfBody

Email classification marker to add text at the bottom of a classified message.

Can include $sec$, $dlm$, $title$, $caveat$ variables.

Default value for AU_2018: {"default" : "$sec$, $caveat$, $dlm$", "noSec" : "$dlm$, $caveat$", "noDlm" : "$sec$, $caveat$", "noCaveat" : "$sec$, $dlm$" }.

Default value for AU_2012: {"default" : "$sec$, $dlm$", "noSec" : "$dlm$", "noDlm" : "$sec$"}.

To remove the header and footer "topOfBody" and "bottomOfBody" values should be set to an empty value: {} or {"default" : ""}.
bodyTextColor

Email classification marker to apply color to the the text in "topOfBody" and "bottomOfBody" text in #AARRGGBB or #RRGGBB format. Text value.

Default value: "#FFFF0000". Examples: #ff0000, #a2ff230c;

default

Email classification marker to apply a default value. Format: { "sec" : "existing sec value", "dlm" : "existing dlm value" }.

Should be one of the markers defined in "values". If value is not set or marker does not exists - "" will be used.

textAlert

Warning message to display when a user is trying to send message without selected classification.

Text value. Default: "Classification is required".

textRequired

Warning text to display in "#FFFF0000" color instead of classification marking while classification is not selected.

Text value. Default: "Classification is required".

lockDlm

When set to "true" only markers with the same dlm as in original message should be available to select. Boolean value. Default: "false".

multiselectField

The fields from "multiselectField" JSON array supports multiple selections. The default value is empty.

When multiple values are selected $field$ notation is replaced with the appropriate values separated with "multiselectSeparator" text. "multiselectSeparator" default value is ", ".

Version properties

Version properties defines which classification type will be used. When version is not defined Generic classification will be used.

  • version - Defines email classification type.
    • Supported version: "AU" or "AU_2012" for Email Protective Marking 2012 Standard and "AU_2018" for Email Protective Marking 2018 Standard for the Australian Government.
  • versionValue - Defines version number used for sending classification.
    • Default value for "AU" and "AU_2012": "VER=2012.3,NS=gov.au". With "AU_2018" "VER=2018.1,NS=gov.au" is used.

Values

Values is used to define a list of Email classification markings. One of the following values must be presented in values field, that is they are optional in place where we substitute them (Subject, Body, Mime Headers and so on).

  • SEC - single SEC or array of SEC values.
  • DLM - single DLM or array of DLM values. With AU_2018 version should be used for the ACCESS(Information management marker) values.
  • CAVEAT - single CAVEAT or array of CAVEAT values.

One of "sec" or "dlm" must be presented in "values" item. When "sec" or "dlm" value is array all the permutations of "sec" + "dlm" should be used. Priorities are in ascending order from top to bottom, from left to right.

JSON is considered invalid and classification markers are not displayed when the values for SEC or DLM is empty or duplicated.

When values item defines a single classification marking that the next properties can be set such as:

  • title - defines text to use for marking title in the classifications picker when the classification is a single value.

Valid classification for AU 2018 contains only:

  • sec, caveat*, access*
  • sec, caveat*
  • sec, access*
  • sec

Where (*) is for one or several items)

A regular expression for AU 2018 Subject

[(SEC=<securityClassification>)(, CAVEAT=<caveatType>:<caveatValue>)*(, EXPIRES=(<genDate>|<event>), DOWNTO=(<securityClassification>)?(,ACCESS=<InformationManagementMarker>)*]

Header:

X-Protective-Marking: VER=<ver>, NS=gov.au, (SEC=<securityClassification>)(, CAVEAT=<caveatType>:<caveatValue>)*(, EXPIRES=(<genDate>|<event>), DOWNTO=(<securityClassification>)?(, ACCESS=< InformationManagementMarker>)*(, NOTE=<comment>)?, ORIGIN=<authorEmail>

The following is example for the Australian classification:

 

{

"scheme" : {

"topOfBody" : {"default" : "$sec$, $caveat$, $dlm$", "noCaveat" : "$sec$, $dlm$", "noDlm" : "$sec$, $caveat$", "onlySec" : "$sec$"},

"bottomOfBody" : {"default" : "$sec$, $caveat$, $dlm$", "noCaveat" : "$sec$, $dlm$", "noDlm" : "$sec$, $caveat$", "onlySec" : "$sec$"},

"bodyTextColor" : "#ffff0000",

"version" : "AU_2018",

"versionValue" : "VER=2018.1,NS=gov.au",

"default" : { "sec" : "OFFICIAL" },

"lockDlm" : "true",

"multiselectField" : ["dlm"],

"multiselectSeparator" : ", "

},

 

"values" : [

{

"sec": "UNOFFICIAL",

"title" : "Unofficial"

},

{

"sec": "OFFICIAL",

"title": "Official"

},

{

"sec": "OFFICIAL:Sensitive",

"dlm": ["","Personal-Privacy","Legal-Privilege","Legislative-Secrecy"]

},

{

"sec": "PROTECTED",

"dlm": ["","Personal-Privacy","Legal-Privilege","Legislative-Secrecy"],

"caveat": ["","SH:Cabinet"]

}

]

}

For Generic classification the following properties must be defined:

  • subjectSuffix - suffix that is appended to subject when sending an email. Can include $sec$, $dlm$ variables. Format: {"default" : "$sec$, $dlm$", "noSec" : "$dlm$", "noDlm" : "$sec$"}. Default: {"default" : "[$sec$]"}.
  • xHeaderName - email header that is added to an email. On reply and forward will overwrite the original header if its protection header cannot be parsed. Text value. Default: "x-classification".
  • xHeaderValue - value for "xHeaderName". Can include $sec$ variable. Format: {"default" : "$sec$, $dlm$", "noSec" : "$dlm$", "noDlm" : "$sec$"}. Default: {"default" : "[$sec$]"}.

The following is an example of Generic classification:

{

"scheme" : {

"subjectSuffix" : {"default" : "[$sec$]"},

"topOfBody" : {"default" : "$sec$, $dlm$", "noSec" : "$dlm$", "noDlm" : "$sec$"},

"xHeaderName" : "x-classification",

"xHeaderValue" : {"default" : "[$sec$]"},

"default" : { "sec" : "-Public-" }

},

 

"values" : [

{

"sec" : "-Public-",

"title" : "All external email"

},

{

"sec" : "-Internal-",

"title" : "BB&T Internal email"

},

{

"sec" : "-Secret-",

"title" : "BB&T Secret email"

}

]

}

The Email classification markers consists of JSON formatted data. The following table describes the generic classification and sample format:

Classification

Value

Sample format

Fields

Array of JSON objects of the classification field configurations.

  • name: The name is a combination of alphabets and numbers. The first letter of the name should be in uppercase.
  • title: The text that is displayed to a user in classification picker. It consists of letters, numbers, and spaces. The default value is equal to name value. (Optional)
  • description: The text displayed in the Classification Picker, to provide users with more information about the Field. The default value is an empty string. (Optional)
  • required: When set to "true" a user is required to select a value for this field Boolean. The default value is set to false. (Optional)
  • onReply: Possible values:
  • UPGRADE_ONLY - allows to upgrade this classification field on email reply.
  • LOCK - prevents from changing this classification field on email reply. (Optional)
  • ANY - allows any change to this classification field on email reply. The default value is set to "ANY". (Optional)
  • allowCustomValue: When "true" a user would be able to add a custom value manually in the picker. Possible only when "onReply" is "ANY". Boolean. The default value is set to false. (Optional)
  • selectionsMaxNumber:When enabled, you can select multiple field values. The default value is set to 1.

"fields":[

{

"name":"SEC",

"type":"text",

"title":"Security Classification",

"description":"",

"onReply":"UPGRADE_ONLY"

},

{

"name":"ACCESS",

"title":"Information Management Marker",

"parent":"SEC",

"required":false,

"onReply":"LOCK"

},

{

"name":"CAVEAT",

"title":"Caveat",

"required":false,

"allowCustomValue":true

}

]

Values

Array of JSON objects of the classification fields values.

  • $Fields.name$: Array on the classification values for the appropriate field. The same field name can be declared multiple times for the unique "parentRange"

  • value: A value to be used for the specific classification marking. Must not contain semi-colons or be comprised of only spaces. Must be declared in the priority order, from the least secure to the most. (Required)
  • title: The text that is displayed as a classification value in the picker. The default value is equal to "value". (Optional)
  • description: The text that is displayed as a description to the specific classification value. The default value is an empty string. (Optional)

  • defaultValue: Classification selected by default on a message compose start. Object of the field-value pairs. The default is an empty field.

  • conditionality: Defines the dependencies between different fields. One field may be dependent just to a single another one.

  • target: defines a parent field and its values in "field":["value_1", ...,"value_n"] format.
  • dependent: defines a child field with a list of values that a user would be shown when any of the "target" fields is selected.

"values":[

{

"SEC":[

{

"value":"UNOFFICIAL",

"title":"Unofficial",

"description":"Non work-related email"

},

{

"value":"OFFICIAL",

"title":"Official",

"description":" Work-related emails that do not carry a security classification"

},

{

"value":"OFFICIAL:Sensitive",

"title":"Official:Sensitive",

"description":"Sensitive but not security classified information"

},

{

"value":"PROTECTED",

"title":"Protected"

},

{

"value":"SECRET",

"title":"Secret"

},

{

"value":"TOP-SECRET",

"title":"Top secret"

},

],

 

},

{

"ACCESS":[{"value":"Personal-Privacy"}, {"value":"Legal-Privilege"}, {"value":"Legislative-Secrecy"}]

},

{

"CAVEAT":[{"value":"SH:CABINET", title:"Cabinet"}, {"value":"REL:AU", title:"Australia"}],

}

],

"defaultValue":{"SEC":"OFFICIAL", "ACCESS":"Personal-Privacy" },

"conditionality":[

{

"targetField":"SEC",

"dependentField":"ACCESS",

"dependencies":[{"targetValues":["OFFICIAL","OFFICIAL:Sensitive","PROTECTED","SECRET","TOP-SECRET"],

"dependentValues":["Personal-Privacy","Legal-Privilege","Legislative-Secrecy"]}]

},

{

"targetField":"SEC",

"dependentField":"CAVEAT",

"dependencies":[{"targetValues":["PROTECTED","SECRET","TOP-SECRET"],"dependentValues":["SH:CABINET","$custom$"]

}

]

},

]

}

SendOptions

JSON object that defines the actions that would be applied to a message while sending and to a new event after creation.

  • xHeader: Object to define the X-Header key and value to be sent with each email.Optional.

  • subjectSuffix: Text to be appended to a classified message subject.

  • bodyHeader and bodyFooter: Formatted text to be appended to the start or the end of a message before an email sending. Optional.

•text: text in Special formatting. "\\n" is resolved as a new line within the text.

Required.

•color: defines text color in #RRGGBB. Optional, default "#000000".

•alignment: defines text alignment with "LEFT"|"CENTER"|"RIGHT" values. Optional, default "LEFT".

•style - defines text style in HTML style format. When defined, "color" and "alignment" properties would be ignored.

•conditions: allows to modify "bodyHeader" or "bodyFooter" values ("text", "color", "alignment") depending on "when" condition.

•when: includes a field name and values. On an email sending with any of these classification values, a property from "result" would override the original "bodyHeader"/"bodyFooter" properties.

  • allowNotClassified: Boolean value that identifies if Email can be sent without classification selected. Boolean. Optional. Default value "false".

"sendOptions": {

"subjectSuffix" : "[(SEC=$SEC.value$){, }(ACCESS=$ACCESS.value$){, }(CAVEAT=$CAVEAT.value$){, }(CAVEAT=$CAVEAT.value_1$){, }(CAVEAT=$CAVEAT.value_2$)]",

"bodyHeader":{

"text":"($CAVEAT.title$: $CAVEAT.value$){, }($CAVEAT.value_1$){, }($CAVEAT.value_2$)",

"color":"#000000",

"alignment":"CENTER",

"conditions":[{"when":{"SEC":["PROTECTED"]},"result":{"color":"#FF0000"}}]

},

"bodyFooter":{

"text":"($CAVEAT.title$: $CAVEAT.value$){, }($CAVEAT.value_1$){, }($CAVEAT.value_2$)",

"color":"#000000",

"alignment":"CENTER",

"conditions":[{"when":{"SEC":["PROTECTED"]},"result":{"color":"#FF0000"}}]

},

"allowNotClassified":true

}

ReceiveMarking

Defines a list of patterns to parse classification from a received message. The order in which the patterns are applied is defined in "priorities".

  • xHeaderPatterns: Rules to parse classification value from the X-Header.The X-Header key is searched by "headerName" values with left-to-right priority. (Optional)

  • subjectSuffixPatterns: Rules to parse classification value from an email subject.

•boundaries define the range of characters in the subject to check for the classification. The "rules" are applied to the text starting from the first inclusion of "start" text and the last of "end". Whole subject is checked when not defined. (Optional)

  • priorities: Defines which patterns to fetch classification value. The default value is set to "priorities". ["xHeaderPatterns","subjectSuffixPatterns"]. (Optional)

"receiveMarking": {

"priorities":["xHeaderPatterns","subjectSuffixPatterns"],

"xHeaderPatterns":{ "headerName" : ["X-Protective-Marking", "X-Classification"],

"rules":["SEC=$SEC$", "sec=$SEC$", "SEC:$SEC$", "sec:$SEC$",

"ACCESS=$ACCESS$", "access=$ACCESS$", "ACCESS:$ACCESS$", "access:$ACCESS$",

"CAVEAT=$CAVEAT$", "caveat=$CAVEAT$", "caveat:$CAVEAT$", "caveat:$CAVEAT$"],

"separatorRegex":"[^a-zA-Z\d\-_\s]"

},

"subjectSuffixPatterns":{

"rules":["SEC=$SEC$", "sec=$SEC$", "SEC:$SEC$", "sec:$SEC$",

"ACCESS=$ACCESS$", "access=$ACCESS$", "ACCESS:$ACCESS$", "access:$ACCESS$",

"CAVEAT=$CAVEAT$", "caveat=$CAVEAT$", "caveat:$CAVEAT$", "caveat:$CAVEAT$"],

"boundaries":{"start":"[", "end":"]"},

"separatorRegex":"[^a-zA-Z\\d\\-_\\s:]"

}

},

Version

version value should be defined to differ between JSON schemas. (Required)

classification version: 2.0.0