Summary
This document outlines the expanded error reporting output from the Virtru Data Protection Toolkit(DPT) to help determine next steps and/or the need to open a support ticket with Virtru during your batch encrypt and/or decrypt process.
Where to find errors if they occur?
DPT is a command line tool and as-such creates progress and error reporting in two locations.
-
The Console: This is the scripted and/or manually executed command window the software has been invoked in. These messages are related to specific issues with syntax. All other errors reported here are also written to an error log file.
-
Log Files: In the log folder configured within the win-x64\Logging\log4net.config file there will be a log file named Virtru.CLI.Error.csv and Virtru.CLI.Debug.log. These files contain errors specific to the batch process you are performing and should be kept in order to determine next steps if applicable.
- Virtru.CLI.Error.csv: This is a properly formed CSV(comma separated) file and as-such can be imported into any client that supported delimited formats(e.g. Google Sheets, Microsoft Excel). If opening in Google Drive, first right-click on the file, and then Open With -> Google Sheet.
- Virtru.CLI.Debug.log: This is a verbose text base log file.
- Summary File: The DPT also creates a summary.log file after each run. This is a text based log file that outlines statistics about the entire run and for each individual input file processed.
Log File Structure
The error logging is designed for verbose logging that can be used for debugging and troubleshooting purposes. The previously mentioned Virtru.CLI.Error.csv error log file is output in the following format. For any given object(e.g. Email body, attachment) being processed there can be multiple errors written to the error log. Each error will be written one per line. To ensure you are looking at errors per object be sure to look at the unique identifier column Msg-ID Being Processed.
There are 2 part of the DPT tool:
- Shell process that handles Mbox, processing, fetching contacts from our SaaS, hmac auth to our SaaS, HTTPS requests to our SaaS
- SDK that handles the actual decryption of the messages.
In any case each portion of the DPT process can log an error for the same message if the error affects both the shell process and the SDK.
Raw Output
Unique ID, Date, File Being Processed, Msg-ID Being Processed, Content Type, Object Name,Type, Severity, Error, Error Details
"43b6cebd-ddd2-4ecf-9731-a96bf3722534","2021-07-07 12:44:29","cenglemboxtest--cengle@virtruprivacy.com_0.mbox","SA0PR22MB2112553401DB059C88F76243C1489@SA0PR22MB2112.namprd22.prod.outlook.com",”Email Body”,”Re: Meeting on 08/22”, "Email Body","Non-Transient","UnauthorizedPolicyAccessError","X-Request-Id: [43b6cebd-ddd2-4ecf-9731-a96bf3722534] HttpResponseCode: [Forbidden] Message: FetchContracts Contract:[4dbd6626-88ac-4caa-b0bb-35a25c4f4e5c] Id:[0] Exception: Virtru.Core.Api.VirtruApiException: [UnauthorizedPolicyAccessError] [The policy does not exist or the authenticated user is not authorized to access the policy.] [unauthorized]
Log Entry Details(1 log entry per line)
| Field in Log File | Description |
| Unique ID | This ID is unique to the specific request made to the Virtru SaaS services and must be included in any support request you open |
| Date | Date and time of this error event |
| File Being Processed | Name of the mbox or pst file being processed |
| Msg-ID Being Processed | RFC2822 message id of the specific email within the mailbox being processed. This ID can be given to a mail administrator to locate the message in any archive and/or live mail system. |
| Content Type | If the object being processed is an attachment, this field will include the file extension(e.g. .docx, .pdf) and if it is an Email Body it will include the text "Email Body" |
| Object Name | Subject of email if it is an email, and Filename if it is an attachment |
| Type | This field specifies whether the error is related to an email body and/or a file attachment being processed. This field will either be Email Body or Attachment |
| Severity | This field specifies whether this is a Non-Transient or Transient error. Transient errors can usually be retried. Non-Transient errors usually indicate something wrong with configuration(e.g. Authentication, Access Control, etc) or a fatal error with the service. |
| Error | This field indicates the specific error category that has been encountered. See the section below for details on these error categories. |
| Error Details | This field provides debug level error detail and should be included in any support ticket opened. |
Error Type and Detail
The detailed error output field in the error log will contain the following error messages. There are always environmental conditions that can cause errors not listed below, but these are the predominant categories that you should prepare your team to respond to.
| Error Category | Error Definition | Next Steps |
| InternalServerError | This category is usually permanent and the result of an unknown error condition. |
Contact Virtru Support support@virtru.com |
| UnauthorizedPolicyAccessError | This category can occur if the credentials being used are not authorized to perform the operation. In addition, this can also occur if the user performing the operation does not have permissions, the policy is missing, expired and/or revoked by an outside user(policy owner not within your organization). |
|
| NotFoundError | This category can occur if the cryptographic keys required for the operation cannot be found. |
Contact Virtru Support support@virtru.com |
| InvalidPermissionsError | This category can occur when the permissions for the operating user are not allowed to perform the operation. |
|
| TopLevel Exception: Multiple node elements can't be created | Current known bug with certain malformed transactional emails. This error usually occurs when a non-sensitive transaction email is parsed, usually resulting in no need to perform decryption. |
|
| TopLevel Exception: An error occurred while sending the request | This category is related to transient errors while sending the request to the Virtru SaaS service. These are usually temporary. |
|
| MessageType Undefined |
This error typically means the message being processed is malformed and/or not formed to RFC standards(RFC822 For Example). This happens with email from time to time and the typical response to these are: -> None: The message does not need to be decrypted as it is some transactional email and/or not payload bearing email -> Updated Version: When we encounter non-RFC compliant emails we will inspect them upon a ticket being opened with us and a new version of our tool released. |
|
|
ErrorSeverity Undefined and/or FATAL |
This category often catches unexpected processing errors and should be treated as a non-transient error condition. This error can also show up multiple times for a single email/attachment because the software retries many times. This retry can make it seem like this is happening a significant number of times within that batch transaction, but please be sure to look at the unique identifier for that line in the error file to count the distinct number or associated email/attachments. Oftentimes, this error occurs very early in the email processing process when the content is simply being parsed and some malformed content is encountered or when a network/authentication condition occurs that results in the activity failing very early in the process. While a retry can resolve many of these, it is recommended that if the email/attachment in question is important a High Urgency ticket be opened with Virtru so our team can help you troubleshoot. |
Contact Virtru Support support@virtru.com |
| Message: PERMANENT ReaderThreadParseAnyFile 6 HTML_PARSER_HAS_ERROR HTML_SECURE_DRAFT_DETECTED | Secure drafts created in the email interface using the browser plugin are encrypted cipher text but do not have a policy associated with them yet because the policy is created during the onsend event. . | No action required |
| Message: The message has corrupted data and cannot be decrypted. Technical Details: 'mac check in GCM failed' |
Result of broken metadata inside of the message payload that is required for decryption. This metadata is important for maintaining split key architecture https://www.virtru.com/platform-architecture/ |
No action required |
Object Error Output
For each object that has an unrecoverable error in the error log output, that object will also be written to an output file of the same format as the input file. For example, if you are processing input MBOX email archive files, it will write an MBOX file as an output. This output can be used to attempt re-processing of just the errored objects and/or to open a ticket with Virtru if the errors are persistent.
Summary Output Details
Output of statistics displayed in the console during the decryption process
Example Output
When running DPT there will be output printed to the console to help guide you through the process and/or report any errors. Below you will find some sample output and descriptions of the fields you will encounter.
Final Console Output:
========================================================================
Full\path\to\username123.mbox
Processing Summary:
┌───────────────────────────────────────┬───┐
│ Total Messages Processed: │ 8 │
├───────────────────────────────────────┼───┤
│ Total Unencrypted Messages Processed: │ 0 │
├───────────────────────────────────────┼───┤
│ Total Encrypted Drafts Processed: │ 1 │
├───────────────────────────────────────┼───┤
│ Total Encrypted Messages Processed: │ 7 │
├───────────────────────────────────────┼───┤
│ Total Messages Decrypted: │ 0 │
├───────────────────────────────────────┼───┤
│ Total Attachments Decrypted: │ 0 │
├───────────────────────────────────────┼───┤
│ Total Messages Written: │ 8 │
├───────────────────────────────────────┼───┤
│ Total Failed Messages: │ 8 │
├───────────────────────────────────────┼───┤
│ Total Failed Attachment: │ 0 │
└───────────────────────────────────────┴───┘
Performance and Debug Summary:
┌────────────────────────┬──────────────────┐
│ Total Processing Time: │ 6s │
├────────────────────────┼──────────────────┤
│ File Read: │ 0 (0.0/s) │
├────────────────────────┼──────────────────┤
│ Write: │ 0 (0.0/s) │
├────────────────────────┼──────────────────┤
│ Downloaded: │ 26.2KB (4.1KB/s) │
├────────────────────────┼──────────────────┤
│ HTTP Requests: │ 12 (1.9/s) │
├────────────────────────┼──────────────────┤
│ HTTP Errors: │ 0 (0.0/s) │
├────────────────────────┼──────────────────┤
│ Other Errors: │ 0 │
├────────────────────────┼──────────────────┤
│ MemPool-L-Used: │ 0B │
├────────────────────────┼──────────────────┤
│ MemPool-L-Free: │ 0B │
├────────────────────────┼──────────────────┤
│ MemPool-S-Used: │ 128KB │
├────────────────────────┼──────────────────┤
│ MemPool-S-Free: │ 1.4MB │
└────────────────────────┴──────────────────┘
Summary Output Field Definitions
| Log output | Definition |
| Total Messages Processed | Number of total emails in the mbox|pst file |
| Total Unencrypted Messages Processed | Number of total emails processed because they were not encrypted |
| Total Encrypted Drafts Processed | Number of encrypted drafts |
| Total Encrypted Messages Processed | Number of virtru encrypted emails in the mbox|pst file |
| Total Messages Decrypted | Number of virtru encrypted emails that were successfully Decrypted |
| Total Attachments Decrypted | Number of virtru protected attachments decrypted |
| Total Message Written | Number of messages written to the output files AND equal to Total Messages Processed |
| Total Failed Messages | Number of virtru protected messages that we were unable to decrypt. |
| Total Failed Attachments | Number of Virtru protected attachments that we were unable to decrypt. |
| Command Arguments | Output of the commands run in the .bat script |
| Total Processing Time | Total overall time taken to process the job |
| Write | Total messages written to the output file |
| File read | TDF files scanned |
| Downloaded | Total size of data downloaded during the process |
| Http requests | Total http requests during the process |
| Http Errors | Total http errors during the process |
| Other errors | Placeholder for unexpected or known retryable errors |
| Mempool-L-Used | Large memory pool used |
| Mempool-L-Free | Large memory pool unused (if this number is too small and/or <0 then you should consider allocated more memory) |
| Mempool-S-Used | Small memory pool used |
| Mempool-S-Free | Small memory pool unused (if this number is too small and/or <0 then you should consider allocated more memory) |