Microsoft Codename "Trust Services" Getting Started Tutorial

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

Introduction
Prerequisites
Tutorial scenario
Next Steps
Quick Links

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) manages account for his organization, creates a subscription for his organization and manages set of users (also known as principals) that can access Trust Services.
Trust Services Policy Administrator (TSPA) defines and manages security policies about the data that his organization owns.
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. Request registration code

Complete the form located at

https://connect.microsoft.com/SQLServer/Survey/Survey.aspx?SurveyID=13835

You can complete the next step of creating certificates before you receive the registration code. You will need the registration code to use Trust Services Portal in Step 3.

Step 2. 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 3. Create a Trust Server

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

Access the Trust Services Portal - https://trustservices.cloudapp.net/
Sign in with your Live ID.
This will take you to the Registration Page.
Enter the Registration Code provided to you in the Code field, fill in the Name and Email fields after checking the Terms and Conditions box. Then click the Register button.
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).
Add users to the Trust Server:
1. Select the Trust Server.
2. Click on Add button in Authorized Certificates box to upload user certificates.
3. Upload the .CER certificate files created in Step 2. These files contain public keys.
  1. %HOMEPATH%\Azure.Trust.Sample.PolicyAdmin.cer
  2. %HOMEPATH%\Azure.Trust.Sample.DataPublisher.cer
  3. %HOMEPATH%\Azure.Trust.Sample.DataConsumer.cer
  If you are using your own certificates, upload .CER files corresponding to public keys of Policy Administrator, Data Publisher, and Data Consumer.
4. At this point, three users are allowed to access the selected Trust Server.

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

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

Step 4. 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 5. Create 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 keys must be uploaded as .cer files to Trust Server using Trust Services Portal.
$policyAdminThumbprint  = "D5ABE98896CB88D34C22BDA9CA0C42574E20D4C7"
$publisherThumbprint    = "46191D956D4F463CAE1EDC0CA220781803F3822A"
$consumerThumbprint   = "5E2788226DD5A96571DB057D0F291B085FF8DA0E"

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

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

# 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"
}

# 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.

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 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:\TruszpolicyExample.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 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 Module
Creating policy for URI "example:exampleUri"
Adding authorization for URI "example:exampleUri" to Data Publisher
Adding authorization for URI "example:exampleUri" to Data Consumer
PS 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 6. 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