Cryptographic API

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.5.4
  • Enterprise
  • Community
  • Planned

Overview

Many enterprise solutions need to store data in a secure way that prevents unwanted parties from gaining access to sensitive information. Sense/Net ECMS offers a simple and easy-to-use API for encrypting and decrypting short string values (currently up to 245 characters). This article describes how developers can make use of the API and how system operators should configure it on production servers.

Details

In the current version we support only an asymmetric encrypt/decrypt algorithm that is designed to work with short string values. In the future the API will support encrypting longer binaries too. The cryptographic API is built on a certificate that should be installed on the web server. The same certificate has to be installed on all web servers in a load balanced environment. After you configured this certificate in the web.config (see the Certificate section below) the portal will be able to encrypt and decrypt values using the public and private keys stored in that certificate.

Certificate

Create certificate

First you have to create a certificate in IIS. It can be a self-signed certificate, placed into the Personal store.

Server certificates in IIS

In case of an NLB environment please export and import this certificate on all web servers.

Please make sure that the application pool identity (the user running the app pool) has access to this certificate.

Please make sure that you have a backup of this certificate in a secure place in case something happens with the machine because encrypted values cannot be accessed without the same certificate (containing the private key) present.

Configuration

You have to add the thumbprint of this certificate to all your configuration files (most importantly web.config) where you plan to use the cryptographic api. You can access the thumbprint by opening the certificate in certmgr and copying the Thumbprint property from the Details panel (please make sure that you remove all the spaces from the value).

<sensenet>
    <cryptography>
      <add key="CertificateThumbprint" value="ABCDEFGHIJKLMNOP" />
    </cryptography>
</sensenet>

If you really want to make this thing secure, you may encrypt this section of the web.config the usual .NET way:


Cryptographic API

Developers can use the API to encrypt and decrypt strings the following way:

using SenseNet.ContentRepository.Security.Cryptography;
...
var encryptedText = CryptoServiceProvider.Encrypt(plainText);
var plainText = CryptoServiceProvider.Decrypt(encryptedText);

Currently there is no built-in switch for automatically securing certain values (e.g. fields). Developers will have to implement this two-way transformation into their business logic.

If something is not right with the certificate (e.g. it is missing or invalid) these methods will throw an exception.

Algorithm and extensibility

The built-in cryptographic service loads the configured certificate as an x509 certificate and uses the RSACryptoServiceProvider .Net class to encrypt and decrypt strings. You can replace this built-in algorithm by implementing the ICryptoServiceProvider interface in your custom library.

Portability

It is important to understand that the portal is able to encrypt/decrypt data only if the configured certificate is present and accessible for the app pool user. If you have to move your environment (e.g. between dev, staging and live servers), you will have to export and import the same certificate.

You may decide to export and deploy the certificate in a way that it contains only the public key. This means that you can build an environment where values can be encrypted (so that certain features work) but as the private key is necessary for decrypting data, existing confidential information is not accessible for untrusted parties (e.g. 3rd party developers).

Current usage

The system uses this API to store the following sensitive information in a secure way:


Related links

References