Safewhere*NemIDSigning
User Guidelines
Version: 1.1
Date: 27-02-2014
Page 1
Contents
Introduction ....................................................................................................................................................... 3
Terminology ..................................................................................................................................................... 3
Prerequisites .................................................................................................................................................... 3
Installation ....................................................................................................................................................... 3
Configuration ................................................................................................................................................... 6
Processing flow (high level protocol specification) .................................................................................... 7
Certificates ....................................................................................................................................................... 8
Client configuration ........................................................................................................................................ 8
Server configuration ..................................................................................................................................... 10
Demonstrations ............................................................................................................................................. 12
Normal Case ................................................................................................................................................. 12
Test Mode 1 ................................................................................................................................................. 13
Test Mode 2 ................................................................................................................................................. 14
Troubleshooting ............................................................................................................................................ 14
APIs ................................................................................................................................................................. 15
Signing methods........................................................................................................................................... 15
GetSignedResult methods............................................................................................................................ 16
ComputeSignData methods ......................................................................................................................... 17
SignData object ............................................................................................................................................ 18
NemIdSigningConfiguration class ................................................................................................................ 18
NemIdSigningClientDemo explanation ........................................................................................................ 19
Page 2
Introduction
This document describes the deployment and use of the Safewhere*NemIDSigning solution, which is an
Asp.Net MVC web application.
Using the Safewhere*NemIDSigning solution you can guarantee the authenticity and integrity of clear text
messages sent from your applications, by requiring users to authenticate such messages via their NemID
account.
By digitally signing a message a user will prove to the recipient that the message can only come from that
person. This helps prevent tampering of the message and ensures trust between sender and receiver.
Safewhere*NemIDSigning is a stand-alone solution that is run in anonymous mode and therefore does not
require any particular setup, but is installed and configured as most other ASP.net web applications.
The solution takes the shape of an ASP.net web application that makes a NemID signing applet available for
other business applications. The signing applet is used to sign clear text received from these business
applications.
The solution must be executed on a Microsoft platform, e.g. from a Windows Server 2008R2 with Internet
Information Server (IIS) as well as Microsoft .Net Framework 3.5 or newer.
Terminology
This document refers to the system that has data to be signed as “the application” and the web application
that handles NemId signing as “the signing solution” or Safewhere*NemIDSigning.
Prerequisites
The reader is expected to have a relatively deep knowledge of the described technologies.
The following technologies are used in the solution:

Microsoft Internet Information Server 6/7

Asp.Net MVC Web Application 2.0 or newer.

X509 certificates

NemId / DanId

DanID TU13 service provider package

Java JRE (installed on the PC of users for signing using NemId)
Installation
Running the installer NemIdSigning_xxx.exe will take you through the following steps
Page 3
Welcome screen: Displays general information. Just click next.
End User License Agreement screen: Simply tick the checkbox to show you agree with the End User License
Agreement and then click next.
Registration Information screen: Fill in your name and your company name and proceed.
Page 4
Destination Location screen: Specify the location where NemIdSigning should be installed. The default
location should work perfectly for most companies, so stick to this unless your company has policies that
say otherwise.
After this just complete the remaining screens to execute the installation.
Page 5
If NemIdSigning was installed successfully, then the below shown folders will have been created on the
server.
-
NemIdSigning: for NemIdSigning server
NemIdSigningClientDemo: for Client demo site
Configuration
The following steps will help you set up and configure the client demo site:
1. Use the IIS Manager to create two websites and point them to the above mentioned folders.
NemIdSigning Server: point to C:\Program Files\Safewhere\Identify\NemIdSigning
Client Demo Site: point to C:\Program Files\Safewhere\Identify\ NemIdSigningClientDemo
2. Update the web.config files as follows:
Client demo site:
- Modify SigningApplicationUrl and ReturnUrl values so they point to your demo_site_URL (as
specified in step 1 above)
- Update the certificate thumbprint as Client Configuration if you do not want to user default
cert
NemIdSigning Server:
- Modify the LogConfigurationFileName value in <appSettings> to point to the
DiagnosticsLogging.config file.
3. Import the server and client certificates in C:\Program Files\Safewhere\Identify\Certificates to
appropriate stores based on the config file from step 2.
Page 6
Processing flow (high level protocol specification)
The following is the flow that is run when using the signing application.
1. The application calls .Sign(String clearText) on the client dll.
2. The client dll signs and encrypts the clearText and any relevant processing instructions for the
signing solution (subject, etc.), using the certificate of the signing solution (as well as its own
certificate).
a. A unique code, called “challenge code”, is also sent to the signing solution. The signing
solution will send this code back to the application later on. This code will be used by the
application to check for replay attacks.
3. The client DLL sends the signing request to the signing solution.
4. The signing solution decrypts the received signing request and verifies the signature
5. The signing solution asks the user to sign the clearText
6. The signing solution verifies that the NemId used for signing corresponds to the subject for the
signing request (the subject was provided by the application).
7. The signing solution composes a response that consists of at least
a. The sign text
b. The subject that performed the signing operation
Page 7
c. Any relevant processing instructions (e.g. result of signature operation)
8. The signing solution sends the response back to the application
9. The client dll verifies the response, and returns a result object.
Certificates
In order to support step #2 above, a pair of certificates will be used. One is for the application and one is for
the signing application. Obviously, the public key of each certificate should be given to the other party.
Client configuration
-
ClientId: since the server will support multiple clients, each client needs to have a unique identity.
This value determines this purpose
-
SigningApplicationUrl: the URL of the signing application to which text that needs to be signed will
be sent
Page 8
-
ReturnUrl: after text is signed, the signing application will return signed text to this URL.
-
SignTextFormat:
o
Defines format of the text. If the format is HTML, text will be applied HtmlDecode on the
server side before signing.
o
Default value is text. In case you are unsure what value to put in, just leave it empty or use
the text value.
-
NoEncryption: true/false. This value specifies if data that is sent back and forth between the
applications should be encrypted.
-
ApplicationCertificate: specify the location where the certificate of the application can be found.
(according the configuration image value above: import “NemIdSigning Client Certificate.pfx” file
into LocalMachine Location and Personal Store, password is Test!234, remember to grant access
for IIS_IUSRS user or AppPool user (example IIS AppPool\DefaultAppPool) to private key of this cert
(in mmc right click to cert -> Manage Private Key))
-
SigningApplicationCertificate: specify the location where the public key of the certificate of the
signing application can be found. (import the certificates containing public key of server certificate
into LocalMachine and Trusted People Store, according to the configuration value above: generate
a public key from “NemIdSigning Server Certificate.pfx” password Test!234)
-
TimeStamp: (in minutes) define duration from now that the request will be expired.
-
Please note that it is possible to use the signing APIs without adding the configuration above to
Web.config. Please refer to APIs section below for more details.
Page 9
Server configuration
-
The NemId section contains settings, which are used to launch up NemId javascript as IframeaseUrl,
SignWidth, SignHeight, SuccessEndPoint, ErrorEndPoint, CancelEndPoint, DigestAlgorithm, and
NemIdAppletOperation. Below are configurations for the NemID certificate like Store and Value.
P a g e 10
You will need to put in a valid NemId certificate issued by DanId. Remember to grant IIS/AppPool
user to its private key.
-
CertificateRevocationCheck options are: None, FullCrlRevocation.
o
In order for NemIdSigning solution performs certificate revocation check successfully, your
server need to be able to make requests to DanId’s servers. Please consult their official
documentation for more details.
-
NemIdSigning section:
o
SigningApplicationCertificate: this is NemID Server Certificate use to decrypt data.
(According to value provide in image: Install “NemIdSigning Server Certificate.pfx”
password Test!234 to LocalMachine/Personal store, grant iis/appPool user to its private
key.
o
ApplicationCertificates: sine server site support multiple clients application (means we may
have many client demo site) this section holds a set of client certificate which identified by
ClientId. It has child element same as section ApplicationCertificate in the client
configuration with StoreName and StoreLocation are a little but different and additional
ClientId value. (According to the example in image, it has 2 clients with clientid are 1 and 2,
it has the same certificate public key from “NemIDSigning Client Certificate.pfx” password
Test!234 in LocalMachine/TrustedPeople)
-
SimulatedSigningCertificate: can use any certificate which is generated for the purpose of signing.
Please note that the certificate must have private key. Change the FindValue tag to its thumprint
value, grant iis/appPool user to its private key.
-
TestMode: when set to true, test mode (aka simulated signing mode) will be enabled. In test mode,
the signing application will use a simulated certificate to sign user’s data instead of the Nemid
applet.
-
Another cool way to enable test mode is to enter a CPR number to the “Text must be signed by” on
the client side. When it is set to a CPR with “x-NNNN” format, NemIdSigning will understand that a
user wants to use test mode.
-
ShowExplanationPeriod: species how many milliseconds the explanation about what test mode is
displayed on the UI. When it is set to 0 and test mode is enabled, either by setting TestMode=true
or by entering a CPR number to the subjectName field, test mode will be selected automatically.
(See Demonstrations section for more detail)
-
Change the LogConfigurationFileName to the correct path for log4net configuration file.
-
RequestIssuer: the issuer request to signature.
P a g e 11
Demonstrations
The following use cases use the demo application shipped with NemIdSigning installer.
Normal Case
(TestMode = false or not defined means that a user does *not* enter a CPR number to the Signer textbox)
Step 1: application form, input sign text
Step 2: click Sign, the client application calls the signing application to load NemID applet form, then user
inputs a NemId account to sign the data.
P a g e 12
Step 3: After the data is signed, it returns to the application:
Test Mode 1
-
Here we set the TestMode key to true to enable test mode
 Test Mode = true, ShowExplanationPeriod = 1000
o In Step 2 it shows two signing options for the user to choose:
o
o
o
Select ‘Normal signing’ to return to the applet as Normal Case
Select ‘Simulated signing’ to use simulated signing. A brief description about what the
simulated mode is shown for ShowExplanationPeriod seconds before the real
simulated page shows up.
Select ‘Cancel’ to cancel the sign process
P a g e 13

Test Mode = true, ShowExplanationPeriod = 0: the simulated page shows up without
immediately without any explanation.
Test Mode 2

Here we don’t set the TestMode key to true, but in Step 1 a valid CPR is set to the subjectName
parameter/to the “Text must be signed by” textbox as below
o
-
That CPR subjectName will trigger simulated mode:
In the simulated mode page, user should enter the same CPR as the value inserted into “Text must
be signed by:” at Step 1.
After the test signature process is done, it returns a signed document to the application.
Troubleshooting
-
If any certificates error happens please recheck all installation certificates above.
-
If ‘Key Set not found’ error is returned, please recheck that user IIS/appPool has been granted
rights to the certificate private key.
-
If ‘SignatureDescription could not be created for the signature algorithm supplied’ error is
returned, please register SHA256 algorithm by following the steps below:
o
Add the below block before </configuration> tag in machine.config file for .net framework
2.0 and 4.0 (both 32 and 64 bit)
P a g e 14
<mscorlib>
<cryptographySettings>
<cryptoNameMapping>
<cryptoClasses>
<cryptoClass RSASHA256SignatureDescription="Security.Cryptography.RSAPKCS1SHA256SignatureDescription,
Security.Cryptography, Version=1.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
</cryptoClasses>
<nameEntry name="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" class="RSASHA256SignatureDescription"/>
</cryptoNameMapping>
</cryptographySettings>
</mscorlib>
o
Register Security.Crytography.dll version 1.5 into GAC if it does not exist in GAC.
o
Restart.
APIs
This section includes description of APIs and an explanation of a the demo source code which shows how to
use these APIs.
Signing methods
-
The Sign methods build signing requests and redirects users to the signing application
automatically. There are five overloads:
Sign(
string signText, HttpContextBase httpContext)
Sign(
string signText,
string subjectName,
HttpContextBase httpContext)
Sign(
string signText,
string subjectName,
HttpContextBase httpContext,
INemIdSigningConfiguration configuration)
Sign(
string signText, string subjectName,
HttpContextBase httpContext,
string signingApplicationUrl,
string returnUrl, string textFormat,
bool noEncryption,
P a g e 15
CertificateReference applicationCertificateReference,
CertificateReference signingApplicationCertificateReference)
Sign(
string signText, string subjectName,
string returnUrl, HttpContextBase httpContext)
-
The rules are:
o
If SubjectName is not provided, the API will get it from HttpContext.User.Name
o
If configuration is not provided, it will be loaded from the Web.config (See
NemIdSigningConfiguration section for more details)
-
Usage: to initiate data signing:
Signing signing = new Signing();
// ------------ To enable logging, init the .Logger property --//signing.Logger = new NemIdLogger
//
{
//
DebugLogger = Logging.Debug,
//
ErrorLogger = Logging.Error,
//
InfoLogger = Logging.Info,
//
};
signing.Sign(signText, signer, this.ControllerContext.HttpContext);
GetSignedResult methods
-
These methods are used to parse the response from the signing application into a SignResult object
GetSignedText(HttpContextBase context)
GetSignedText(HttpContextBase context,
INemIdSigningConfiguration configuration)
GetSignedText(HttpContextBase context,
CertificateReference applicationCertificateReference,
CertificateReference signingApplicationCertificateReference)
-
The rule is: If configuration is not provided, it will be loaded from the Web.config.
-
SignResult object contains signed information returned to client, from this client can show that
signed data depends on its purpose or show error details if it happens.
public class SignResult
{
/// <summary>
/// Text after being signed by NemId, in XML format.
/// </summary>
public string SignedText { get; internal set; }
P a g e 16
/// <summary>
/// Based64 encoded form of the signedText
/// </summary>
public string SignedTextBase64 { get; internal set; }
/// <summary>
/// RawResult that is sent from NemId applet, for example 'Ok' and 'Cancel'
/// </summary>
public string RawResult { get; internal set; }
/// <summary>
/// Raw signature that is sent from NemId applet
/// </summary>
public string RawSignature { get; internal set; }
/// <summary>
/// NemId certificate of the user who signed
/// </summary>
public X509Certificate2 EndUserCertificate { get; internal set; }
/// <summary>
/// True if text is signed successfully.
/// False if the user canceled signing or an error happened
/// </summary>
public bool IsOk { get; internal set; }
/// <summary>
/// Loaded SignedXml object
/// </summary>
public SignedXml SignedXml { get; internal set; }
/// <summary>
/// Returns the reason which failed the signing process. When IsOk is true, this property is
set to None
/// </summary>
public SigningFailedReason Reason { get; internal set; }
/// <summary>
/// Returns error message of the top most exception which happened during the signing process
/// </summary>
public string ExceptionMessage { get; internal set; }
/// <summary>
/// Returns full stack trace of an exception which happened during the signing process
/// </summary>
public string StackTrace { get; internal set; }
}
-
Usage:
var signing = new Signing();
var result = signing.GetSignedText(this.ControllerContext.HttpContext);
string signXml = result.IsOk ? result.SignedText : result.ExceptionMessage;
ComputeSignData methods
-
For scenarios in which the redirect mechanism - which the Sign methods use – does not work well,
e.g. when the NemIdSigning library runs on a SharePoint project, the ComputeSignData methods
provide an alternative approach in that they can be used to compute sign data requests. The
hosting application will then decide how it wants to send the requests to the signing application.
-
Computes and returns sign data to allow callers to post it to the NemIdSigning server (the signing
application) by their own methods. Return SignData object.
-
ComputeSignData(string signText, HttpContextBase httpContext)
P a g e 17
ComputeSignData(string signText, string subjectName, HttpContextBase httpContext)
ComputeSignData(string signText, string subjectName, string returnUrl
, HttpContextBase httpContext)
ComputeSignData(string signText, string subjectName, HttpContextBase httpContext,
INemIdSigningConfiguration configuration)
ComputeSignData(string signText, string subjectName, HttpContextBase httpContext,
string signingApplicationUrl, string returnUrl, SignTextFormatType textFormat,
bool noEncryption, CertificateReference applicationCertificateReference,
CertificateReference signingApplicationCertificateReference)
-
The rules are:
o
If SubjectName is not provided, the API will get it from HttpContext.User.Name
o
If configuration is not provided, it will be loaded from Web.config
SignData object
public class SignData
{
/// <summary>
/// Signed and encrypted request to send to NemIdSigning server (the signing application)
sign
/// </summary>
public string Data { get; set; }
to
/// <summary>
/// The challenge code which is embedded in the Data string above, and also added to
session state
/// before this SignData object is returned from the ComputeSignData method. Provides it here
just in case
/// there are some needs for it.
/// </summary>
public string ChallengeCode { get; set; }
}
NemIdSigningConfiguration class
-
This class contains configuration for the application as well as the signing application:
public sealed class NemIdSigningConfiguration : INemIdSigningConfiguration
{
string SigningApplicationUrl { get; set; }
string ReturnUrl { get; set; }
SignTextFormatType SignTextFormat { get; set; }
bool NoEncryption { get; set; }
CertificateReference SigningApplicationCertificate { get; set; }
CertificateReference ApplicationCertificate { get; set; }
CertificateReference SimulatedSigningCertificate { get; set; }
}
-
Usage: to load it from web.config:
INemIdSigningConfiguration configuration = NemIdSigningConfiguration.GetConfiguration();
-
For developers who favor coding over configuration, the configuration object can also be created
programmatically.
-
Another scenario is that you may want to use configuration file, but you also want to override just
P a g e 18
one or two settings after loading it. The Override[PropertyName] family of methods give you that
power. Please note that these methods return a new configuration object. The caller object is kept
as is.
INemIdSigningConfiguration OverrideSigningApplicationUrl(string signingApplicationUrl);
INemIdSigningConfiguration OverrideReturnUrl(string returnUrl);
INemIdSigningConfiguration OverrideSignTextFormat(SignTextFormatType signTextFormat);
INemIdSigningConfiguration OverrideNoEncryption(bool noEncryption);
INemIdSigningConfiguration OverrideSigningApplicationCertificate(CertificateReference
signingApplicationCertificate);
INemIdSigningConfiguration OverrideApplicationCertificate(CertificateReference
applicationCertificate);
INemIdSigningConfiguration OverrideSimulatedSigningCertificate(CertificateReference
simulatedSigningCertificate);
NemIdSigningClientDemo explanation
-
NemIdSigning is shipped with a client demo MVC site to demonstrate how to use the APIs
described above. The demo client page allows users to enter text and expected signer’s name. It
then uses the Sign method to send request to the signing application which is defined by the
SigningApplicationUrl key in web.config. Upon receiving a response from the signing application, it
verifies the response and shows signing result to the user.
-
Firstly, the Index action show UI for user to input the text and signer
public ActionResult Index()
{
var model = new SignTextModel();
// if simulated signing certificate is configured,
// use it to initialize the signer field
INemIdSigningConfiguration configuration = NemIdSigningConfiguration.GetConfiguration();
var certificateService = new DefaultCertificateService();
if (configuration.SimulatedSigningCertificate != null)
{
var simulatedSigningCertificate =
certificateService.GetCertificate(configuration.SimulatedSigningCertificate);
model.Signer = simulatedSigningCertificate.SubjectName.Name;
}



-
return View(model);
}
The system loads configuration value from web.config using NemIdSigningConfiguration class
If simulate certificate exists, load the signer field with the cert’s subject name.
The user see a form with 2 text fields SignText and Signer (provided in
Views/Signing/Index.aspx)
When a user clicks the ‘Sign’ button, the system calls the DoSign action of the Signing controller.
The action uses the NemIdSigning.Signing.Sign API to send signing data to the signing application.
public void DoSign(string signText, string signer)
{
Signing signing = new Signing();
signing.Sign(signText, signer, this.ControllerContext.HttpContext);
}
-
After signing is done, the signing application returns either signed data or signing error to the demo
application.
-
The Signed action of the SigningController controller uses the Siging.GetSignedText API to process
signing result:
public ActionResult Signed()
{
string querystring = Request["querystring"];
var model = new SignedTextModel();
if (!string.IsNullOrEmpty(querystring))
{
var signing = new Signing();
var result = signing.GetSignedText(this.ControllerContext.HttpContext);
string signXml = result.IsOk ? result.SignedText : result.ExceptionMessage;
P a g e 19
string signedXml = signXml;
model.SignedText = signedXml;
}
else
{
model.SignedText = "not exist";
}
return View("Signed", model);
}
It checks the IsOk property of SignResult object to determine if it should display signed text
or error message to the user. Please note that the IsOk property can only tell if a sign
request is successful, the signResult.Reason property can tell what the exact error is.
P a g e 20