Certificate Management

  • Article

We get a lot of questions about managing your HealthVault application certificate.  When your application initiates a connection to HealthVault, it uses its unique private key to encrypt the first handshake message that it sends.  HealthVault then uses a public key to verify that the sender of this message is indeed a trusted host.  This public key must be registered with HealthVault before such connections can be made.

Generating your key pair and installing your private key

You can generate your key pair in one of two ways:

  • Use the MakeCert.exe tool which ships with the HealthVault SDK and is available on MSDN.  This doc on MSDN has more information on using MakeCert.
  • Use the Application Manager tool which ships with the HealthVault SDK.  Application Manager makes it easy to create a new AppId and certificate pair at the same time.  Application Manager does not handle the scenario of creating a new certificate pair for an existing application.

Once you have generated your key pair, you can install it for use by your application in one of three ways:

  • Cert store, default name.   Application Manager gives your certificate the default name, "WildcatApp-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx," and places it in the default location.  The HealthVault instructions on using MakeCert also give the cert the default name and place it in the default location.
  • Cert store, non-default name.   To specify your certificate name, specify the full subject name of the cert (CN=) in the <appSettings> section of your web.config file as follows:

<appSettings>

<add key="AppCertSubject" value="[full_cert_subject_name]"/>

</appSettings>

  • File system.   If you choose to take this approach then make sure that the following two things are true: 
    • The IIS worker process has access to read the file
    • The file is not stored in a location where it is visible on your web site.  Don't put it inside your web application path but in a secure file path not visible in IIS.
    • To store your certificate on the local file system, you must add an additional entry in your web.config to tell the HealthVault SDK code where to look for the certificate, as follows.  (This is also added to the <appSettings> section.)

 <add key="ApplicationCertificateFileName" value="C:\someFolderName\cert\HelloWorld-SDK_ID-05a059c9-c309-46af-9b86-b06d42510550.pfx" />

    • Note: the file path is an absolute local file path; relative path names are not allowed
    • If you configured your private key to require a password for use, then you can/must specify this password in your web.config by using the ApplicationCertificatePassword parameter

Registering your Public Key

In PPE, you can register your public key in one of two ways:

  • Use the Application Manager tool in the .NET HealthVault SDK to upload a new ApplicationId and its certificate.  Note that this workflow is only for creating new applications.  You cannot add a new certificate to an existing application this way.
  • Login to the Application Configuration Center at https://config.healthvault-ppe.com and click on the "Public Certs" tab.  You can upload additional CER files here.

Note that each application in the HealthVault-PPE environment has exactly one HealthVault-PPE account that has been set up with config access.  If you need to set up a new account with config access, you can request this access via a link on the App Config Center home page.

In Production, the only way to register your public key is to go through the HealthVault Go-Live process.  If your application is already live and you need to update or replace its public key, you can file a request with HealthVault Developer Support here.