CB Blockchain Seal Online Documentation

1. Introduction

The CB Blockchain Seal application is intended to allow on-demand and automatic sealing and on-demand verifications of documents (or files in general) stored in a document system.

The process is quite simple – when sealing or verification is started, the file is read by the application, a hash is computed from the content and the hash is sent to CB Digital Port of Trust service which takes care of storing the hash in a Blockchain.

The high-level overview can be seen below.

2. Install the application

The application consists of two services. Both are running as windows service applications.

• A web application that serves as the backend for a web user interface
• A worker application that processes jobs configured by the user.

The first step is the installer introduction screen. Click Next to continue.

If the .Net Core 3.1.1 runtime is not present yet on the target system the next screen is the prerequisites summary. .Net Core 3.1.1 is required and needs to be installed. Click Next to install the prerequisites.

From the following screen read and accept the End User Agreement by checking the “I accept the terms of this agreement” and click the “Next” button.

Select an installation directory and click Next.

From the next screen select the Microsoft SQL Server database that the application will work with.

The setup scans the network for existing MS SQL database servers and fills the dropdown list, so it is possible to select one from the list. It is also possible to type the name of a server directly.

If there is no database prepared yet, it is possible to write a database name and let the service create it automatically. Please ensure that the provided user has permissions to create a database on the server.

Note: if Trusted Connection is ON, the service authenticates with the database by its identity. Two services are communicating with the database. Both are running as a Local System identity. Therefore, access to the database must be enabled for these identities. As consequence, it is strongly recommended to use SQL Server Authentication and a dedicated user. For guidance on how to prepare the database user and the database itself please see How to create an MS SQL Server user and a database (Section 12.1).

Note: if the application is installed multiple times within an organization it must be taken care that they do not share one database.

On the next page, the setup is ready to install individual components. By clicking “Install” the installation process copies the needed file structure to configured folder, registers and starts installed services.

The last screen confirms your successful installation.

The setup installs and starts two Windows Services as described at the beginning of this chapter.

3. Start the application

You can start the application by going to your browser (Google Chrome is recommended) and typing (http://localhost:5970/) in the address bar. By default, the application is configured to use port 5970.

Alternatively, you could:

1. click the shortcut created on your desktop  after the installation was completed

2. or by pressing the Windows button and typing “CB Blockchain Seal”

 

4. Activate the application

The application is a client application of CB Digital Port of Trust cloud service. While communicating with the service, the application must send an activation code that presents an active valid subscription.

Please purchase your free trial from here. Once done, you will get an email from us with your code/token similar to the one below. Please click the Activate Service button shown below to activate your token.

To register your code, please navigate to the License tab from the CB Blockchain Seal application user interface, type the token and click “Activate Code” as shown below:

5. Configure the application

5.1 Configure the application with SharePoint

You need to configure a connection to your document management system (SharePoint), so you could navigate through the folders tree. To do so, as shown below, please navigate to the “Document System Configurations” section (1) where you could see the list of your existing configurations if any.

As shown above, to create a new configuration, press the “Create New” button and select “Create new SharePoint configuration” (2) to show the following dialogue where you could specify the required info to create a SharePoint connection.

There are two types of SharePoint authentication supported – the basic one with user and password and the “modern authentication”.

5.1.1 Basic authentication

In the above figure:
• Name – a configuration name that helps you to identify the connection in the list.
• Site Collection URL – the URL of your SharePoint.
• Is it SharePoint Online? – “checked” for Office 365 SharePoint Servers while “not checked” for on-prem servers.
• Username – a SharePoint service user with read/write right on the document libraries where the documents will be sealed or verified.
• Password – the provided SharePoint user’s password.

5.1.2 Modern authentication

In the above figure:
• Name – a configuration name that helps you to identify the connection in the list.
• Site Collection URL – the URL of your SharePoint.
• Is it SharePoint Online? – “checked” for Office 365 SharePoint Servers while “not checked” for on-prem servers.
• Application (client) ID – the Application (client) ID of the AAD application registration
• Directory (tenant) ID - the Directory (tenant) ID of the AAD application registration
• Certificate Thumbprint – the unique identifier of the certificate used by your app.

Please follow the next steps to get the info needed:

1. If you don’t have a certificate that could be used, then you could use the certificate shipped with the application. Please navigate to the folder “Utils” under the installation directory of the application.

2. Start the PowerShell script “create_cert.ps1” (works with Windows Server 2016+) to create a new certificate called “CBDigitalSealModernAuth” under the folder [Local Computer > Personal store]. The script needs to be started under elevated permissions to be able to write into the local computer store.

Note: the script has hard coded certificate subject and friendly names – they can be changed as needed. Also, it assumes the existence of the c:\tmp directory for export. If the directory doesn’t exist, the script will fail to export the certificate. In that case, the export directory should be changed to an existing one in the script.

3. Open certificate manager by pressing the Windows key and typing “certificate” and select “Manage computer certificates”.

4. Navigate to the desired certificate, right-click and select Export.

5. Ensure NOT to export the private key and click Next

6. Select DER format option and click Next

7. Save your certificate

8. Open Azure portal and log in using a user who is associated with the tenant of the SharePoint being configured.

9. Select All Resources from the menu and Click “Azure Active Directory”

10. Select “App registrations” from the menu

11. Click “New Registration” and fill in the basic data like the figure below and click “Register”.

12. From the left menu, select “Authentication”, click “Add platform” and choose “Web”

13. In the Redirect URIs specify https://localhost:5970/consent-callback.html where port 5970 is set as default by the app installation. Keep the checkboxes unchecked.

14. Click “Certificates & secrets” and upload the “cer” file exported in the previous section. Certificate thumbprint should be displayed after the upload. This is the certificate thumbprint that you need to copy to the configuration screen.

15. Click API Permissions and add Sites.Manage.All permissions for SharePoint.

16. Click “Grant admin consent” for your tenant.

5.1.3 Test the connection

Once you provide the above info, please click “Test Connection” to ensure a successful connection to your SharePoint server. If you have a successful connection, please click save as shown below.

5.1.4 Edit SharePoint configuration

As shown below, you can edit any saved configuration by clicking the “Edit” button (2) from the configuration row.

This will bring the configuration edit screen which is identical to the new configuration screen.

5.2 Configure the application with Dracoon

You need to configure a connection to your document management system (Dracoon), so you could navigate through the folders tree. To do so, as shown below, please navigate to the “Document System Configurations” section (1) where you could see the list of your existing configurations if any.

As shown above, to create a new configuration, press the “Create New” button and select “Create new Dracoon configuration” (2) to show the following dialogue where you could specify the required info to create a Dracoon connection.

5.2.1 Password authentication

To be able to connect using password authentication, you need to create a dedicated application in the Dracoon environment from the Apps/Custom Apps area.

The application needs to have a “password” option enabled.

The meaning of fields in the Dracoon connection dialogue is explained below the next figure.

• Name – a configuration name that helps you to identify the connection in the list.
• URL – the URL of your Dracoon team, e.g. https://myteam.dracoon.team or https://dracoon.team or your domain mapped to a Dracoon team IP
• Client ID – the Client ID from created Dracoon custom application
• User – the user used to login to Dracoon
• Client Secret – Client Secret from created Dracoon custom application
• Password – the password of the specified user used to login to Dracoon
• Master Password – the password to decrypt encrypted rooms – this is an optional setting; if the password is not provided, files from encrypted rooms will fail to be sealed

Once all mandatory fields are defined the connection can be tested the same way as with by clicking the “Test Connection” button.

5.2.2 Edit Dracoon configuration

As shown below, you can edit any saved configuration by clicking the “Edit” button (2) from the configuration row.

This will bring the configuration edit screen which is identical to the new configuration screen.

It is possible to update the visible fields (Name, URL, Client ID…) without the need to re-specify all the secret values. To achieve that keep the “Change Secrets” switch turned OFF as shown below.

To change one or more of the secret values, the “Change Secrets” switch must be set to “Yes”. In that case, at least one value must be specified, otherwise, changes cannot be saved.

5.3 Switch between configurations

As shown in the figure below, you can easily switch between configuration by clicking the star button (2) from the configuration row.

The active configuration has a filled star while non-active configurations have non-filled ones

5.4 Delete a configuration

As shown in the figure below, to delete a configuration, simply click the “delete” button (2) from the configuration row. You can delete a configuration only if there are no jobs associated with it.

If there are jobs associated with a specific configuration that you would like to delete, then please delete those jobs first by navigating to the Seal History tab discussed in Section 8.

6. Seal your documents

To seal or verify documents, please click the “Seal Folders” tab as shown below.

The “Seal folders screen” has the following options:

1. Shows the active document management system
2. Shows the document management system folder tree structure
3. If activated, orders the nodes in the tree alphabetically no matter of their type or how the target document system delivered them
4. Provides an extension filter to select which files to seal. Only files of the selected extensions in the selected location will be sealed. If none is specified, all files will be sealed.
5. Provides an input to add custom file extensions
6. Provides a switch, if turned ON, it allows the application to register itself for notifications on file changes, so it could seal changed documents automatically. This requires some settings on the SharePoint Server. Please refer to section 11 for the detailed steps.
7. Provides a switch, if turned ON, it allows the application to seal the documents regardless if they were sealed already or not. If turned OFF, only unsealed documents will be sealed.
Note: this switch is considered only in n case of SharePoint. In the case of other systems (e.g. Dracoon) files are sealed always regardless if they were sealed before.
8. Provides a switch, if turned ON, documents for sealing are searched in the whole folder subtree of the selected folder. If turned OFF, only files directly in the selected folder are evaluated for sealing.
9. The seal button when clicked, will start an asynchronous sealing job that searches all the files in the chosen folder based on the given filters, compute the hashes if required and send the hashes to CB Digital Port of Trust for blockchain sealing.

To check the progress of the sealing process, please navigate to the Seal History tab shown below.

Note on Microsoft Office files: Whenever a SharePoint list property related to an MS Office document changes, the document is automatically updated by SharePoint. Even though only the metadata is modified, not the content, the hash of the document would be different. Therefore, CB Blockchain Seal creates hash only from content, but not the whole file in case of MS Office files. This applies also to the verification process.

Note on Microsoft Azure Information Protection: If MS Office files are protected by MAIP they cannot be recognized because they are encrypted and the application cannot read the content. In that case, the encrypted version of the file is sealed. If SharePoint automatically modifies the metadata of the file and encrypts it again, the file will be different although the content was not changed. In that case verification of the file will fail.

Note on Outlook “msg” files: Whenever a SharePoint list property related to an Outlook msg file changes, the file is automatically updated by SharePoint. Even though only the metadata is modified, not the content, the hash of the file would be different after the change. CB Blockchain Seal currently doesn’t support content-only hashing for msg files, therefore these files should be either excluded from the sealing process or the file should be downloaded locally before sealing to enable verification later using the Connecting Software Verifier.

7. Verify your documents

To verify the seal of a document, navigate to the “Seal Folders” screen as shown below.

From the above page, click the “Verify Seals” button as shown next.

That will display a window with a folder structure where you could choose the document you wish to verify (1) then click the verify button (2). The service will calculate the hash of the document and send it to CB PoT to check if that hash was written to BlockChain.

Note: As this is an automatic process without user interaction, in case of multiple seals available for a hash, the latest one is taken.

If a file was sealed earlier and is still authentic (still contains the same content as when the document was sealed) then a screen explaining that will be displayed as shown below.

If a file contains a different content as when the document was sealed, the file is considered tampering. If that’s the case, a screen showing the same will be displayed a shown below

You could also verify a document library, a folder or a subfolder the same way you verify a document.

Simply, select the location (document library, folder or subfolder) you wish to verify (1) then click verify (2) as shown above.

If the location contains any tampered documents, it will show as below

1. The overall progress of the verification process
2. The number of documents verified
3. The number of tampered documents
4. The list of the tampered documents

If all the documents in the selected location are authentic, a screen like the one below will be displayed.

8. View sealing and verification jobs

You can view the jobs (sealings & verifications) executed in the past or being executed from the Seal History tab shown below.

You can filter the list by the job type, job state, execution date range, or path as shown below.

You can view the results (shown earlier) of a job by clicking the button from the row of that job.

You can delete a job but clicking the button from the row of that job.

9. View sealing and verification statistics

You can view the weekly statistical information about the sealing and verification jobs by navigating to the Statistics tab as shown below.

10. View application logs

You can view the logs of the application by navigating to the Logs tab. This tab offers an overview of the operations performed by the system. You can filter by the log severity.

11. Auto seal your documents

To allow the sealing of documents automatically after they are modified in SharePoint, SharePoint needs to send a change notification to the application. SharePoint sends notifications using the HTTP and HTTPS protocols. For the application, it means it must be accessible from the machine hosting the SharePoint Server. Moreover, the application must have a valid certificate if HTTPS should be used.

Note: When the automatic sealing is turned ON, the application registers itself for notifications. Notifications can be set on the list level. Whenever an item in the list is changed the application gets a notification with a URL of that item and seals it. The notification is sent for any change, not only content but also metadata or properties

11.1 Office 365 SharePoint Servers

As Office 365 SharePoint is hosted by Microsoft there is no possibility to access certificate store on the hosting machine, therefore CB Blockchain Seal Application must have a certificate provided by an official authority (e.g. https://letsencrypt.org/).

The application may be hosted using either one of the following options:

• In the cloud as a public service: if the default certificate generated by azure is sufficient then nothing else to configure. If you have a custom domain then please use the Azure/Amazon portal to bind the certificate to your custom domain.
• In the LAN of the customer: in this case, the port the application uses must be accessible from the target SharePoint (i.e. internet); moreover, the IP address must be associated with the domain name the certificate is issued for. Please see section 12.2 for instructions on how to set up a custom certificate in the application. If the pfx file is not available, but the certificate is in the store, then you could export it as described in section 12.3.

11.2 On-Prem SharePoint Servers

Options for Office 365 SharePoint are valid also for On-Prem SharePoint installations.
Additionally, a simplified configuration can be achieved by installing the application in the LAN and following the next steps
1. Create a self-signed as explained in section 12.4
2. Bind the created certificate to the application as explained in section 12.2
3. Add the certificate to trusted roots on the machine where SharePoint is hosted as explained in section 12.5.

If the communication within the LAN is considered secure enough, HTTP communication can be used. In that case, no certificate needs to be applied.

11.3 Dracoon

Since Dracoon is hosted in the cloud the same conditions apply as with Office 365 SharePoint Servers (see section 11.1).

12. Appendix

12.1 How to create an MS SQL Server user and a database

Prerequisites - make sure you have needed permissions to create new server logins and databases. Usually, trusted Windows user who installed the server and the “sa” user-specified during the installation has these permissions. Generally, users with at least “securityadmin” and “dbcreator” roles are required. For guidance regarding MS SQL server roles please visit Microsoft pages.

To create a new database and associated user follow these steps:

1. Connect to the server instance using MS SQL Management Studio

2. Select Databases -> New database

3. In the dialogue specify the name of your database and click OK

4. Select Security -> Logins -> New Login …

5. Specify login name, activate SQL Server authentication and specify a password. Select a database created in previous steps as the default one and click OK.

Note: In case Enforce password policy is activated and the password is changed in the future, it is needed to perform an update of the password in the application settings file.

6. In the same dialogue select User Mapping, check the database created in previous steps and check the db_owner role. Then click OK.

7. That’s it. To test the login, try to connect using the newly created user.

12.2 How to configure a custom certificate with the application?

Regardless of the certificate is provided by an authority or generated as a self-signed one, it must have a pfx file secured with a password. You need to copy that file to the root folder of the directory and add the following section to the appsettings.json file:

"Kestrel": {
    "Endpoints": {
      "SslEndpoint": {
        "Url": "https://cnsm-nb007.cns.local:5002",
        "Certificate": {
          "Path": "localhost.pfx",
          "Password" :  "xxxx" 
}
      }
    }
  }

• Url: The domain the certificate was issued for
• Path: The name of the pfx file (if the file is not copied in the root directory, you could also provide the relative path to the file)
• Password: The password specified when the certificate was exported

12.3 How to export a certificate?

1. From your windows start menu, type “Manage computer certificates” to show the Certificates browser shown blow

2. From the Certificate, Browser find the certificate to export, right-click, and from All Tasks, click “Export…” as shown below

3. Select the “Yes, export the private key” option and click next

4. Choose the pfx file format option

5. Specify the password to be used in the application certificate configuratioimn.

6. Choose the path to export the file to

7. Click ‘Finish’ on the next screen and you are done.

12.4 How to create a self-signed certificate?

The process of creating a self-signed certificate can be found on the internet. Example (http://woshub.com/how-to-create-self-signed-certificate-with-powershell/).

The basic steps of creating and applying the certificate using PowerShell are described below:

1. Setup certificate properties

$certificate = New-SelfSignedCertificate `
    -Subject localhost `
    -DnsName localhost `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -NotBefore (Get-Date) `
    -NotAfter (Get-Date).AddYears(2) `
    -CertStoreLocation "cert:CurrentUser\My" `
    -FriendlyName "Localhost Certificate for .NET Core" `
    -HashAlgorithm SHA256 `
    -KeyUsage DigitalSignature, KeyEncipherment, DataEncipherment `
    -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.1")

2. Set the certificate to be stored in current user’s store (to do it for local machine change the path to LocalMachine instead of CurrentUser)

$certificatePath = 'Cert:\CurrentUser\My\' + ($certificate.ThumbPrint)

3. Export the certificate to a pfx file (to be used late by the application) and cer file (to add the certificate later as a trusted one)

Note: The directory referred in assignment to $cerFilePath variable must exist. The path in the script can be changed to fit to existing file structure.

$pfxFilePath = "c:\tmp\myCertificate.pfx" 
$cerFilePath = "c:\tmp\myCertificate.cer" 
$pfxPassword = ConvertTo-SecureString -String "YourSecurePassword" -Force -AsPlainText 
Export-PfxCertificate -Cert $certificatePath -FilePath $pfxFilePath -Password $pfxPassword
Export-Certificate -Cert $certificatePath -FilePath $cerFilePath

12.5 How to add a certificate to trusted root?

You can achieve that via PowerShell or GUI:

12.5.1 Using PowerShell

Import-Certificate -FilePath $cerFilePath -CertStoreLocation Cert:\CurrentUser\Root

where $cerFilePath is the path to the exported cer file. If you want to add the certificate to the global machine’s store then replace the (Cert:\CurrentUser\Root) with (Cert:\LocalMachine\Root). Please note that admin permissions are required for this operation.

12.5.2 Using GUI

1. From your windows start menu, type “Manage computer certificates” to show the Certificates browser shown blow

2. Open the Trusted Root Certification Authorities store, right click certificates, all tasks and select Import

3. Depending on the scope of the selected store (machine or user) select the target store or skip the first screen

4. Specify the file you want to import by clicking the Browse button

5. Choose the option “Place all certificates in the following store”, click Browse, and select the Trusted Root store

6. Click Finish.

13. Conclusion

This document described how to install, configure, activate and use CB Blockchain Seal. For more info please contact us at office@connecting-software.com