1 introduction 2 configuration - signaturgruppen

Signaturgruppen Authentication Plugin Technical Documentation 1-04-2015

Signaturgruppen A/S www.signaturgruppen.dkIncuba-Navitas Inge Lehmanns Gade 10 8000 Århus C [email protected]

1 Introduction

This document is the technical reference for Signaturgruppens Authentication Plugin client library.

The Authentication Plugin consist of a single .Net 4.5 DLL (AuthenticationPlugin.dll), henceforth referred to asthe client library.

The API and configuration for the client library is described in this document.

2 Configuration

All configuration for the client library is configured in the web.config file for your web application. This sectiondescribes the section you need to add and the possible settings that are available.

2.1 Configuration section

The client library expects the following configuration section in the web.config file:

<configuration> <configSections> <section name="AuthenticationPlugin" type="Signaturgruppen.AuthenticationPlugin.Configuration.AuthenticationPluginConfigurationSection, AuthenticationPlugin" /> ...

<AuthenticationPlugin CertificateFile="~/App_Data/TestBlackBoxSelfSigned.p12" CertificateFilePassword="Test1234" BackendCertificateFile="~/App_Data/TestBlackBoxSelfSigned.p12.cer" BackendUrl="https://...[see web.config in latest demo]" Identifier="TestTu1" />

2.1.0.1 Introduction to CAPI

If you store your certificates in the Windows Certificate Store, you can configure the client library to load certifi-cates from there. This is done through the CryptoAPI (CAPI). In the following configuration parameters, nameswith a Capi suffix refers to certificates loaded through the CryptoAPI.

2.1.1 Configuration settings

The AuthenticationPlugin section has the following possible parameters



Setting Description

Identifier Service Provider Identifier

BackendUrl Url pointing to the backend

BackendCertificateFile Backend certificate

BackendCertificateCapi Backend certificate CAPI identifier

BackendCertificateCapiFindType X509FindType for BackendCertificateCapi

CertificateFile Certificate used to secure communication

CertificateFilePassword Password for CertificateFile

CertificateCapi CAPI identifier of Authentication Plugin certificate

CertificateCapiFindType X509FindType for CertificateCapi

CapiStoreLocation StoreLocation for Capi certificates



2.1.1.1 Identifier

Identifies the service (the client library) to the backend. This value can be choosen freely but has to match theconfiguration at the backend, as the backend uses this value to identify the specific configuration at the back-end, including certificates used for the secure communication.

2.1.1.2 BackendUrl

Url pointing to the root of the backend application.

2.1.1.3 BackendCertificateFile

Directory path pointing to the filebased certificate (typically a cer file), used to encrypt and verify messageswhen communicating with the backend. Supports absolute or virtual path.

2.1.1.4 BackendCertificateCapi

CAPI certificate identifier for the certificate used to encrypt messages when communication with the backend.The default behavior is to look for the Distinguished Name of the certificate.

2.1.1.5 BackendCertificateCapiFindType

Lets you set the X509FindType when also using the BackendCertificateCapi parameter. All values of theX509FindType are usable, but the following values are usually preferred:

X509FindType Description

FindBySubjectDistinguishedName Full distinguished name from certificate (X509Certificate2 style)

FindBySubjectName Find a substring in the certificate subject name

FindByThumbprint Find by certificate Thumbprint (usually SHA1 hash)

FindBySerialNumber Find by certificate serial number

If more than one certificate is found using the selected search method, the first found is selected.

2.1.1.6 CertificateFile

Directory path pointing to the filebased certificate (typically a p12 or ` pfx file), used to decrypt and sign mes-sages when communicating with the backend. Supports absolute or virtual path.

2.1.1.7 CertificateFilePassword

Password for the pfx/p12 file pointed to in the CertificateFile parameter

2.1.1.8 CertificateCapi

CAPI certificate identifier for the certificate used to encrypt messages when communicating with the backend.The default behavior is to look for the Distinguished Name of the certificate.

2.1.1.9 CertificateCapiFindType

Lets you set the X509FindType when also using the CertificateCapi parameter. See BackendCertificate-CapiFindType for possible values.

2.1.1.10 CapiStoreLocation

StoreLocation enum:



public enum StoreLocation{ CurrentUser = 1, LocalMachine = 2,}

Default for this setting is StoreLocation.LocalMachine

2.1.2 Configured certificates

The client library and the backend communicates securely using the configured certificates. Only one of Back-endCertificateFile and BackendCertificateCapi must be specified. Same applies for CertificateFile and Cer-

tificateCapi .

3 Logging

No external logging framework is used in the client library but the client library supports and requires logging.

This is done by requiring the registration of a logging method taking a message to be logged as a string param-eter:

//from Global.asax:

protected void Application_Start(object sender, EventArgs e){ log4net.Config.XmlConfigurator.Configure(); var logger = LogManager.GetLogger("Signaturgruppen.AuthenticationPlugin"); AuthenticationPluginLogger.LoggerAction = logger.Debug;}

This is an example taken from our demo application where we demonstrate the registration of a Log4Net debuglogger, which then receives all the log messages from the client library.

If this is not configured the AuthenticationPluginLogger will throw an exception at runtime.

The backend will log all required information regarding login, signing, validation, revocation checks etc.

A full audit log are generated at the backend which supports the extended reporting requirements from DanIDwhen using file or hardware based NemID flows

The backend is also able to log the XMLDSig (XML-signatures) generated by the NemID flows. These are alsoavaiable through the API.

The client logs are mainly for debugging purposes but we still require them.

4 HTML 5 Web Messaging and iframes

The flow works by setting up an iframe and then communicating with the backend using the HTML 5 Web Mes-saging JavaScript API through an iframe.

The client library generates the code needed to enable communication with the backend through an iframe. Asan example, the following code snippet creates the signed parameters for the backend as well as the JavaScriptneeded for the communication

var paramsGenerator = new NemIDOtpParamsGenerator();



paramsGenerator.GenerateScriptAndParametersForNemIDFrame("HandleResult.aspx");

We refer to the demo for details on how this is used.

The browser requirements for this setup are the same as for the NemID JavaScript client, thus if the usersbrowser supports the NemID client, it supports Signaturgruppens Authentication Plugin.



5 Test setup

Signaturgruppen has hosted a backend available when testing on http://authentication.signaturgruppen.dk/au-thenticationiframebleeding.

The demo application available at http://authentication.signaturgruppen.dk is configured to this test backendwhen you start it the first time.

It is possible to use the demo setup to get NemID up and running in your application(s) and test how NemIDand our software works before any agreements with us or DanID has been made.

6 Client flows and services

We support all NemID login and signing flows, which include the NemID JavaScript client using OTP cards(both Standard Mode and Limited Mode) and the OpenSign applet for key and hardware based login and sign-ing flows.

6.1 CPR Services

The client library supports the CPR services available through the NemID infrastructure. If you are a private ser-vice provider you are restricted to the CPR Match service, which lets you validate a given CPR paired with thePersonal ID (PID) from a successfull NemID authentication flow.

6.1.1 CPR (non-private service providers)

If you have a CPR agreement with DanID it is a simple configuration setting at the backend which enables theCPR service and sets the CPR in the response from the backend and makes it available through the NemIDVal-idationResult (see below).

The CPR is encrypted and decrypted transparently using RSA-SHA256.

6.1.2 CPR Match (private service providers)

The CPR Match service is available at the backend as a RESTful service available transparently through theclient library. A CPR Match agreement with DanID is required.

There are two ways to call the CPR Match service using the client library.

1. The NemIDValidationResult.AuthenticationInfo object contains the method:PidCprMatch(string cpr),which returns true or false. (See below for more details on the result object). When a response is receivedfrom the backend, the PID from the user certificate is already part of the response, and thus only the CPRnumber is needed in order to verify if the PID matched the given CPR.

2. The CPR Match service is also avaible as a "pure" backend-to-backend service using the following

var service = new PidCprMatchService();var cprMatchesPid = service.MatchPidAndCpr(string pid, string cpr);

The MatchPidAndCpr(string pid, string cpr) method returns true or false. All communication is secured by httpsand signed and encrypted using RSA-SHA256.

6.2 Sign _ Properties

If you need to add additional sign properties to the resulting XMLDSig document, you can do so by adding the



Sign _ Properties property to the parametergenerator, as demonstrated here:

var paramsGenerator = new NemIDOtpParamsGenerator();paramsGenerator.SetClientFlowParameter("Sign_Properties", "testProperty1=testValue1;testProperty2=testValue2;");

7 Backend response

The response received from the backend through the iframe is validated using the client library, resulting in anobject consisting of the validation result and all the information needed from the specific client flow.

Following snippet of code creates a validator which parses and validates the response string received from thebackend through the HTML5 WebMessaging API:

var validator = new NemIDAuthenticationValidator();NemIDValidationResult result = validator.Validate(receivedResponse);

The NemIDValidationResult object contains the validation result and all the data you need from the NemID au-thentication.

An example is a NemID login flow, where the result object contains validation status and if successfull all thecertificate info from the NemID user including: PID/RID and Common Name.

See the demo for all relevant examples, including demonstration of how to use the CPR-MATCH service.

7.1 NemIDValidationResult

In this section the API for the NemIDValidationResult class is described. We refer to an instance of NemIDVali-dationResult as "result".

7.1.1 result.AuthenticationResult : BOOLEAN

TRUE, if and only if, result.Status equals Ok.

7.1.2 result.Status : AuthenticationStatus

public enum AuthenticationStatus{ Ok, AuthenticationBackendError, ClientFlowCancel, ClientFlowError, AuthenticationPluginValidationError,}

7.1.2.1 Ok

In this case the communication and the flow requested was successfull. The user was authenticated successful-ly.

7.1.2.2 AuthenticationBackendError

And error occured at the backend. In this case the returned message is not signed and a generic error messagecould be displayed to the user. This is most likely to be caused by configuration errors.

7.1.2.3 ClientFlowCancel

In this scenario, the flow was cancelled, most often directly by the user.



7.1.2.4 ClientFlowError

In this case, an error occured in the requested flow. Examples could be and error with the NemID client. In thiscase the errorcodes returned to the backend from the requested client flow is returned and should be logged.See examples of this in the demo application. As a minimum, you should log the message returned from the.GetLogMessage() call on the validation result object.

7.1.2.5 AuthenticationPluginValidationError

An error occured parsing or validating the response from the backend.

7.1.3 result.AuthenticationInfo

Object containing the response from the NemID authentication. If AuthenticationStatus equals Ok, it contains allthe certificate information such as PID/RID, common name, certificate distinguished name etc. If Authentication-Status equals ClientFlowError, the error code from the NemID flow is found in the ErrorCode property.

The resulting XMLDSig is found in the SignedXml property, as a Base64 encoded string.

8 Flow overview

To illustrate how the different parts work together, we provide a short overview of the overall flow here.

All communication are done via https and are thus encrypted.

1. The client website opens an iframe to the backend and sends the generated and signed parameters to the backend through

2. The requested flow/client is started and generated parameters used. The user is interacting directly with the service inside the iframe using a secure connection.

3. As an example: The NemID client is started inside the iframe which transparently lets the user interact with the NemID client, as-if the client was hosted directly on the client website.

4. When the user has entered his credentials the response is validated and all required logs created at the backend.

5. A response is created and sent to the client website through the iframe using the HTML 5 web massag- ing API.

6. The response is validated using the client library, after which all required information is avaiable through the client library API.

7. All messages are signed and sensitive information is encrypted. Our library transparently validates and de-/encrypts the messages.

All communication is done through and from the users browser.

9 Contact information

Info

Mail [email protected]

Phone +45 70256425

Website http://www.signaturgruppen.dk

1 introduction 2 configuration - signaturgruppen

Documents