Trust Services: Getting Started

Article
1/17/2024

Click here to change the language (ja-JP).

Introduction

This tutorial shows how to perform the basic tasks in Trust Services.

Trust Services is a collection of components and Azure Service that enables secure information sharing through the Cloud. It enables you to encrypt your data before uploading it to cloud storage, saving it on a disk or sending it to your partner.

In this tutorial, you will learn how to subscribe to Trust Services, define policies that enforce protection of data, and use the policies to encrypt and decrypt sample data.

The demo scenario involves four parties:

**Trust Services Administrator (TSA) **is the Live ID user that manages the Trust Services account for the organization. The TSA performs the following actions on the Trust Services portal :
- Sign-up for a Trust Services service.
- Create and Manage Trust Servers associated with the account - The TSA creates a Trust Server and identifies a Trust Services Policy Administrator with an X.509 certificate (referred to as Principal Certificate) for the server. This certificate (containing only the public key) is uploaded by the TSA.
Trust Services Policy Administrator (TSPA) performs the following actions within a Trust Server using Trust Services SDK:
- Manage users: Identifies the publisher/subscribers associated with a Trust Server and uploads their certificates (containing only the public key).
- Define & Manage Policies: Defines policies for data entities, identifying the data entity (URI) as sensitive (protected with encryption) or non-sensitive (left as plaintext). In Trust Services, a data entity is identified by a uniform resource identifier (URI).
- Define & Manage the Data Authorization: Authorizes users to access (decrypt) the sensitive data entity.
- TSPA certificate rolling: Uploads a new TSPA certificate to designate a new TSPA.
**Data Publisher **is a user that runs an application that encrypts the data based on the policies defined by the TSPA.
**Data Consumer **is a user that runs an application that decrypts the data encrypted by Data Publisher based on the policies defined by the TSPA.

Note:

In some real-life scenarios all of the above roles can be performed by a single persona and accomplished using single X.509 certificate. We use all the personas to showcase system's capabilities.
In this release, the customer is assumed to be an Administrator Persona that holds an Azure Subscription. It is also assumed that he has subscribed & provisioned an Azure store for the purposes of storing sensitive data in the cloud.

Prerequisites

One of the following operations systems:
- Windows Server 2008 R2 x86
- Windows Server 2008 R2 x64
- Windows 7 x86
- Windows 7 x64
.NET Framework 4
PowerShell 2.0 (integrated with Windows 7 and 2008 R2)

Recommended:

Visual Studio 2010 for C# samples and easy creation of certificates

Tutorial scenario

In the steps below, you will learn how to subscribe to Trust Services, define policies that enforce protection of data, and use the policies to encrypt and decrypt sample data.

Step 1. Create certificates

X.509 certificates are used for authentication by Trust Service, and encryption and signing by Trust Services SDK and PowerShell Snap-In.

Certificates for the following three personas will be needed:

Policy Administrator,
Data Publisher, and
Data Consumer.

Each persona uses his certificate for multiple purposes: to authenticate to the Trust Service and gain access to appropriate Trust Server; to sign various objects he creates in Trust Server (keys, policies, etc) so they can be validated by him and other personas; to decypher encrypted objects stored in Trust Server for which he was granted access.

You can use existing certificates or create self-signed certificates. To create self-signed certificates:

Open Visual Studio Command Prompt from Start Menu.

Run the following commands:

makecert -r -pe -n "CN=Azure.Trust.Sample.PolicyAdmin" -sky exchange -ss my %HOMEPATH%\PolicyAdmin.cer
makecert -r -pe -n "CN=Azure.Trust.Sample.DataPublisher" -sky exchange -ss my %HOMEPATH%\DataPublisher.cer
makecert -r -pe -n "CN=Azure.Trust.Sample.DataConsumer" -sky exchange -ss my %HOMEPATH%\DataConsumer.cer

Now you should have these certificates in Current User Windows Certificate Store.

Step 2. Create a Trust Server

These steps are performed by the TSA role described in the Introduction.

Access the Trust Services Portal - https://trustservices2.cloudapp.net/
Sign in with your Live ID.
This will take you to the Registration Page. After successful registration, you will be redirected to the home page.
Add a Trust Server:
1. Click on Create button in Your Trust Servers box.
  
  This will create a new Trust Server (system auto generates a name).
Set Trust Services Policy Administrator (TSPA) of the Trust Server:
1. Expand the Trust Server by clicking on Trust Server name.
2. Click on Set TSPA button in Authorized Certificates box to upload TSPA certificate.
3. Upload TSPA .CER certificate file created in Step 2. This file contains public key.
  1. %HOMEPATH%\Azure.Trust.Sample.PolicyAdmin.cer
  If you are using your own certificates, upload .CER file corresponding to public keys of Policy Administrator.
4. At this point, TSPA is allowed to access the selected Trust Server and add other users, i.e. data publishers and data consumers.

Figure 1. Trust Server Portal shows the name of the Trust Server generated for you and certificate of TSPA associated with the Trust Server.

Note: Copy the Trust Server name. It will be needed in subsequent actions on the client machines.

Step 3. Install Trust Services SDK

Download "Trust Services" SDK here and install.

Note:

When installing the 64-bit version of the SDK, save the TrustServiceLab_amd64.msi file to local disk, before double-clicking on the file in Windows Explorer to start installation. This prevents an error message (about the Trust Services plugin not being found) from being displayed when the installer attempts to start the Trust Services Powershell window when installation completes. See the Troubleshooting page for more details.

Step 4. Create Data Users and Data Policy using PowerShell

These steps are performed by the TSPA role described in the Introduction.

Start Trust Services Shell shortcut in Start Menu.

Copy the following script into a notepad:

# Example script for using Trust Services PowerShell Snap-In.
# Policy Administrator defines encryption data policy and 
# authorizes Data Publisher and Data Consumer to the policy and data.

$ErrorActionPreference = "Stop"

# Thumbprints of certificates.
# Public key of policy administrator must be uploaded as .cer file to 
# Trust Server using Trust Services Portal.
$policyAdminThumbprint  = "153deca0bdd9f93cab118a75bef5bc8b25e1a8b7"
$publisherThumbprint    = "ae331870917312e78d86c2e0f0b7e3dde5ab75ee"
$consumerThumbprint     = "2e61b5d64c97746e44a75cbecd811329ecdfb9b4"

# Name of Trust Server created using Trust Services Portal.
$trustServerName = "i4p091naue"

# URL of Trust Service. Can be obtained from Trust Services Portal.
$trustServiceUrl = "https://TrustServicesApi2.cloudapp.net/"

# Find certificates to use by Trust Services snap-in.
# These certificates must be already uploaded to Trust Server using Trust Services Portal.
$paCert = dir cert:\currentUser\my | 
    where-object { $_.thumbprint -eq $policyAdminThumbprint }
if ($paCert -eq $null)
{
    Throw "Policy Administrator certificate with thumbprint ""$policyAdminThumbprint"" " +
        "not found in Current User Windows certificate store."
}
$pubCert = dir cert:\currentUser\my | 
    where-object { $_.thumbprint -eq $publisherThumbprint }
if ($pubCert -eq $null)
{
    Throw "Data Publisher certificate with thumbprint ""$publisherThumbprint"" " +
        "not found in Current User Windows certificate store."
}
$subCert = dir cert:\currentUser\my | 
    where-object { $_.thumbprint -eq $consumerThumbprint }
if ($subCert -eq $null)
{
    Throw "Data Consumer certificate with thumbprint ""$consumerThumbprint"" " +
        "not found in Current User Windows certificate store."
}

# Create admin ECM to create policies using Trust Services cmdlets.
if ( !(Test-Path "ecm:\polAdmin") )
{
    Write-Host "Creating admin Trust Services Edge Compliance Module"
    New-Ecm -Admin -ServerName $trustServerName -ServerUrl $trustServiceUrl `
        -EcmOwner $paCert -FriendlyName "polAdmin"
}

Write-Host "Adding Data Publisher"
Add-Principal -Principal $pubCert -FriendlyName "polAdmin"

Write-Host "Adding Data Subscriber"
Add-Principal -Principal $subCert -FriendlyName "polAdmin"

# Create a policy that data for URI "example:exampleUri" must be encrypted.
$policyUri = "example:exampleUri"

Write-Host "Creating policy for URI ""$policyUri"""
Add-DataPolicy -Encrypt -PolicyUri $policyUri -FriendlyName "polAdmin"

# Authorize publisher and consumer to data with URI "example:exampleUri".
Write-Host "Adding authorization for URI ""$policyUri"" to Data Publisher"
Add-DataAuthorization -Principal $pubCert -PolicyUri $policyUri -FriendlyName "polAdmin"

Write-Host "Adding authorization for URI ""$policyUri"" to Data Consumer"
Add-DataAuthorization -Principal $subCert -PolicyUri $policyUri -FriendlyName "polAdmin"

Replace thumbprints of certificates in the copied script.

$policyAdminThumbprint value with the thumbprint of the Policy Administrator's certificate,
$publisherThumbprint value with the thumbprint of the Data Publisher's certificate,
$consumerThumbprint value with the thumbprint of the Data Consumer's certificate.

Thumbprint of policy administrator certificate can be retrieved from Trust Services Portal by expanding the server as shown below.

Alternatively, thumbprints of all relevant certificates can be discovered by running the following command from PowerShell window:

dir cert:\currentUser\my | where {$_.Subject -eq "CN=Azure.Trust.Sample.PolicyAdmin" }
dir cert:\currentUser\my | where {$_.Subject -eq "CN=Azure.Trust.Sample.DataPublisher" }
dir cert:\currentUser\my | where {$_.Subject -eq "CN=Azure.Trust.Sample.DataConsumer" }

Replace $trustServerName value with the name of the Trust Server (auto-generated on the portal, please see Figure 1 in Step 4 above).
Save the script to a file, for example, d:\TrustPolicyExample.ps1
Execute the script from Trust Services Shell window, for example, by typing
```
d:\TrustPolicyExample.ps1
```
If you get the following error:
File d:\TrustPolicyExample.ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see "get-help about_signing" for more details.
then run the following command before running the script:
```
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
```
See [[Microsoft Codename "Trust Services" Troubleshooting|Troubleshooting]] page for other errors and possible solutions.

You should see output similar to the one below.

PS C:\Program Files\Microsoft\Trust Services Lab SDK and Shell (x64)\bin> d:\TrustPolicyExample.ps1
Creating admin Trust Services Edge Compliance ModuleAdding Data PublisherAdding Data SubscriberCreating policy for URI "example:exampleUri"Adding authorization for URI "example:exampleUri" to Data PublisherAdding authorization for URI "example:exampleUri" to Data ConsumerPS C:\Program Files\Microsoft\Trust Services Lab SDK and Shell (x64)\bin>

Note: You can also use C# SDK to generate data policies. Please refer to samples on Trust Services Samples page.

Step 5. Encrypt and decrypt data using PowerShell

Perform the following steps after the policies are created in the previous section.

The steps in this section are performed by Data Publisher and Data Consumer roles described in the Introduction.

Start Trust Services Shell shortcut in Start Menu

Copy the following script into a notepad:

# Example script for using Trust Services PowerShell Snap-In.
# Data Publisher encrypts data that Data Consumer decrypts.
# Policy Administrator must have already defined encryption data policy and 
# authorized Data Publisher and Data Consumer to the policy and data.

$ErrorActionPreference = "Stop"

# Thumbprints of certificates.
# Public key of policy administrator must be uploaded as .cer file to 
# Trust Server using Trust Services Portal.
# Public keys of Data Publisher and data user must have been added using
# Add-Principal command.
$policyAdminThumbprint  = "153deca0bdd9f93cab118a75bef5bc8b25e1a8b7"
$publisherThumbprint    = "ae331870917312e78d86c2e0f0b7e3dde5ab75ee"
$consumerThumbprint     = "2e61b5d64c97746e44a75cbecd811329ecdfb9b4"

# Name of Trust Server created using Trust Services Portal.
$trustServerName = "i4p091naue"

# URL of Trust Service. Can be obtained from Trust Services Portal.
$trustServiceUrl = "https://TrustServicesApi2.cloudapp.net/"

# Find certificates to use by Trust Services snap-in.
# These certificates must be already uploaded to Trust Server using Trust Services Portal.
$paCert = dir cert:\currentUser\my | 
    where-object { $_.thumbprint -eq $policyAdminThumbprint }
if ($paCert -eq $null)
{
    Throw "Policy Administrator certificate with thumbprint ""$policyAdminThumbprint"" " +
        "not found in Current User Windows certificate store."
}
$pubCert = dir cert:\currentUser\my | 
    where-object { $_.thumbprint -eq $publisherThumbprint }
if ($pubCert -eq $null)
{
    Throw "Data Publisher certificate with thumbprint ""$publisherThumbprint"" " +
        "not found in Current User Windows certificate store."
}
$subCert = dir cert:\currentUser\my | 
    where-object { $_.thumbprint -eq $consumerThumbprint }
if ($subCert -eq $null)
{
    Throw "Data Consumer certificate with thumbprint ""$consumerThumbprint"" " +
        "not found in Current User Windows certificate store."
}

# Create publisher ECM to encrypt data
if ( !(Test-Path "ecm:\pubUser") )
{
    Write-Host "Creating publisher Trust Services Edge Compliance Module"
    New-Ecm -User -ServerName $trustServerName -ServerUrl $trustServiceUrl `
        -EcmOwner $pubCert -TrustedPrincipal $paCert -FriendlyName "pubUser" 
}

# Create consumer ECM to decrypt data
if ( !(Test-Path "ecm:\subUser") )
{
    Write-Host "Creating consumer Trust Services Edge Compliance Module"
    New-Ecm -User -ServerName $trustServerName -ServerUrl $trustServiceUrl `
        -EcmOwner $subCert -TrustedPrincipal $paCert -FriendlyName "subUser"
}

# Policy must have been already created by the Policy Administrator.
$policyUri = "example:exampleUri"

# Data to be encrypted.
[byte[]] $originalBytes = 1,2,3

$originalString = -join ($originalBytes |  foreach {$_.ToString("X2") } )
Write-Host "Publisher encrypting data $originalString"

# Encrypt data.
$encryptedBytes = 
    Add-Encryption -ClearBytes $originalBytes -PolicyUri $policyUri -FriendlyName "pubUser"

$encryptedString = -join ($encryptedBytes |  foreach {$_.ToString("X2") } )
Write-Host "Consumer decrypting data $encryptedString"

# Decrypt data.
$decryptedBytes = 
    Remove-Encryption -CypherBytes $encryptedBytes -PolicyUri $policyUri -FriendlyName "subUser"

$decryptedString = -join ($decryptedBytes |  foreach {$_.ToString("X2") } )
Write-Host "Consumer decrypted data $decryptedString"

Replace thumbprints of certificates in the assignment lines:

$policyAdminThumbprint value with the thumbprint of the Policy Administrator's certificate,
$publisherThumbprint value with the thumbprint of the Data Publisher's certificate,
$consumerThumbprint value with the thumbprint of the Data Consumer's certificate.

To discover thumbprints of certificates, you can get them from Trust Services Portal by resizing the columns as in the screenshot below.

Alternatively, you can run the following command from PowerShell window:

dir cert:\currentUser\my | where {$_.Subject -eq "CN=Azure.Trust.Sample.PolicyAdmin" }
dir cert:\currentUser\my | where {$_.Subject -eq "CN=Azure.Trust.Sample.DataPublisher" }
dir cert:\currentUser\my | where {$_.Subject -eq "CN=Azure.Trust.Sample.DataConsumer" }

Replace $trustServerName value with name of the Trust Server (auto-generated on the portal, please see Figure 1 in Step 4 above).
Save the script to a file, for example, d:\TrustEncryptExample.ps1
Execute the script from Trust Services Shell window, for example, by typing
```
d:\TrustEncryptExample.ps1
```
If you get the following error:
File d:\TrustEncryptExample.ps1 cannot be loaded because the execution of scripts is disabled on this system. Please see "get-help about_signing" for more details.
then run the following command before running the script:
```
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
```
See [[Microsoft Codename "Trust Services" Troubleshooting|Troubleshooting]] page for other errors and possible solutions.