Running Stormshield Data Mail Outlook Edition

Stormshield Data Mail Outlook Edition can be run using a PowerShell script or a .NET program to send and read encrypted and/or signed messages.

Configuring Microsoft Outlook

By default, Microsoft Outlook restricts the execution of external programs.

When you execute a PowerShell script or .NET program using Microsoft Outlook properties, the following pop up window appears:

Click Allow to enable the PowerShell script or .NET program to run Microsoft Outlook. Access is allowed for a specified duration (1, 2, 5 or 10 minutes).

To execute a PowerShell script or .NET program using Microsoft Outlook and bypass this pop up window, configure Microsoft Outlook to accept being run by other programs:

Run Microsoft Outlook as administrator.
Open the Trust Center in the Outlook options and click Trust Center Settings:
Select Never warn me about suspicious activity in the Programmatic Access tab.

It is possible to configure a registry key on each workstation to automatically allow the execution of external programs in Microsoft Outlook. For Microsoft Outlook 2019 and Office 365, the registry key is:

Microsoft Outlook 32 bits or 64 bits:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\16.0\Outlook\Security

DWORD: ObjectModelGuard

Value: 0, 1 or 2
Microsoft Outlook 32 bits running on 64-bit systems:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Office\16.0\Outlook\Security

DWORD: ObjectModelGuard

Value: 0, 1 or 2

The ObjectModelGuard values depend on the Programmatic Access Security parameters:

Warn me about suspicious activity when my antivirus software is inactive or out-of-date (recommended) → Value 0
Always warn me about suspicious activity → Value 1
Never warn me about suspicious activity (not recommended) → Value 2

Configuring Stormshield Data Mail Outlook Edition

In the normal operating mode of the Stormshield Data Mail Outlook Edition add-in, the EnableScripting value of the registry key HKLM\SOFTWARE\Arkoon\Security BOX Enterprise\Properties\Mail\ is disabled (value = 0). Therefore, when encrypted and/or signed messages are sent or read, if errors occur (issues with the certificate for example), dialog boxes that require the user's manual response will appear.

To run the add-in in "script" mode, i.e., from a PowerShell script or a .NET program, this registry value needs to be enabled (value = 1). As such, when errors occur, dialog boxes requiring the user's response will no longer appear.

If this value has not been enabled and the add-in is run in "script" mode, the dialog boxes that may open would prevent the encrypted and/or signed message from being sent or read. Potential errors that may occur during the process will be logged in the file %TEMP%\Arkoon.SecurityBox.Mail.Scripting.log.

After the process of sending or reading encrypted and/or signed messages has finished running, the value needs to be disabled where necessary in order to switch back to a normal operating mode of the Stormshield Data Mail Outlook Edition add-in.

The default value of the EnableScripting registry value is 0.

Interacting with Stormshield Data Mail Outlook Edition

The Stormshield Data Mail Outlook Edition module processes outgoing messages in order to encrypt and/or sign them and incoming messages to decrypt and/or read their signatures according to the properties assigned to the message.

Sending an encrypted and/or signed message

Create a PowerShell script or .NET program that will use the Outlook Object Model programming interface.

Add the following properties to the message created:

SDSEncrypt to encrypt an e-mail.
SDSSign to sign an e-mail.

The message will be encrypted with the certificates found in the address book of the current Stormshield Data Security user. If no user is connected then a connection pop-up window displays.

The message will be signed by the user logged on to Stormshield Data Security, using his private signature key.

For more information about creating a new user property in the UserProperties collection and about the security behavior of the Outlook Object Model, refer to the Microsoft Developer Network website.

The following examples show the two methods for opening a Microsoft Outlook instance and sending a signed and encrypted message.

The PowerShell script and .NET program automatically send an encrypted and signed message to the recipient john.doe@mycompany.com. This message will also be encrypted for the sender.

PowerShell

Connect-SDSUser –Id "Alice Smith" –Interactive
Set-ItemProperty –Path "HKLM:\SOFTWARE\Arkoon\Security BOX Enterprise\Properties\Mail" -Name "EnableScripting" -Value 1
$outlook = New-Object -ComObject Outlook.Application
$session = $outlook.Session
$session.Logon("Outlook") # maps to configured Outlook profile name
$mailItem = $outlook.CreateItem(0)
$mailItem.Recipients.Add("john.doe@mycompany.com")
$mailItem.Subject = "Simple text Subject"
$mailItem.Body = "Simple text Body"
$userProp = $mailItem.UserProperties.Add("SDSEncrypt", 6, $false, 1)
$userProp.Value = $true
$userProp = $mailItem.UserProperties.Add("SDSSign", 6, $false, 1)
$userProp.Value = $true
$mailItem.Send()				
Set-ItemProperty –Path "HKLM:\SOFTWARE\Arkoon\Security BOX Enterprise\Properties\Mail" -Name "EnableScripting" -Value 0

The script above does not take into account the release of COM objects that have been instantiated from Microsoft Outlook. They need to be released using:

[Runtime.InteropServices.Marshal]::ReleaseComObject($variable)

.NET

using Stormshield.DataSecurity.Connector;
using Microsoft.Office.Interop.Outlook;

namespace SDConnectorSample
{
  class Program
  {
    static void Main(string[] args)
    {
      string keyPath = @"SOFTWARE\ARKOON\Security BOX Enterprise\Properties\Mail";

      #region Enabling registry key
      using (RegistryKey baseKey = RegistryKey.OpenBaseKey(RegistryHive.LocalMachine, RegistryView.Registry64))
      {
        using (RegistryKey subKey = baseKey.OpenSubKey(keyPath, true))
        {
          subKey.SetValue("EnableScripting", 1);
        }
      }
      #endregion

      using (API api = new API())
      {
        api.Execute("Connect-SDSUser –Id 'Alice Smith' –Interactive");
      }

      Application outlook = new Application();
      NameSpace session = outlook.Session;
      session.Logon("Outlook"); // maps to configured Outlook profile name
      MailItem mailItem = outlook.CreateItem(OlItemType.olMailItem);
      mailItem.Recipients.Add("john.doe@mycompany.com");
      mailItem.Subject = "Simple text Subject";
      mailItem.Body = "Simple text Body";
      UserProperty userPropEncrypt = mailItem.UserProperties.Add("SDSEncrypt", OlUserPropertyType.olYesNo, false, OlFormatYesNo.olFormatYesNoYesNo);
      userPropEncrypt.Value = true;
      UserProperty userPropSign = mailItem.UserProperties.Add("SDSSign", OlUserPropertyType.olYesNo, false, OlFormatYesNo.olFormatYesNoYesNo);
      userPropSign.Value = true;
      ((Microsoft.Office.Interop.Outlook._MailItem)mailItem).Send();
      
      #region Disabling registry key
      using (RegistryKey baseKey = RegistryKey.OpenBaseKey(RegistryHive.LocalMachine, RegistryView.Registry64))
      {
        using (RegistryKey subKey = baseKey.OpenSubKey(keyPath, true))
        {
          subKey.SetValue("EnableScripting", 0);
        }
      }
      #endregion
    }
  }
}

The program above does not take into account the release of COM objects that have been instantiated from Microsoft Outlook. They need to be released using:

Marshal.ReleaseComObject(variable)

Reading an encrypted and/or signed message

When a message is read in Microsoft Outlook through a PowerShell script or a .NET program, the Stormshield Data Outlook Edition add-in will decrypt the message seamlessly. The MailItem object retrieved in this manner will be in plain text and both properties will allow determining whether the message had been encrypted and/or signed:

SDSReadEncrypted if the message was encrypted
SDSReadSigned if the message was signed

The following examples show the two methods for opening a Microsoft Outlook instance and reading a message from the inbox.