p. 1 - 41 Nets Branch Norway Haavard Martinsens Vei 54 NO-0045 Oslo
T +47 22 89 89 89 www.nets.eu
Foretaksregisteret NO 996 345 734
E-Signing Integration guide
Version: 3.42 - 41
Contents
1. Introduction ... 4 Purpose ... 4 Document overview ... 4 Intended audience ... 4 Referenced documentation ... 4Terms and definitions ... 5
Acronym ... 5
Change log ... 6
2. Integration process ... 7
Overview ... 7
Customer test configuration ... 7
Production configuration ... 8 Merchant data ... 8 Merchant certificates... 8 Server certificates ... 9 3. E-Signing integration ... 11 Overview ... 11 XML Interface integration ... 13 Web services ... 13 Signing XML messages ... 13 TrustSignMessage ... 13 Example message ... 14 TrustNotificationMessage ... 15
SignWeb – Graphical User Interface ... 15
GUI ... 15 E-Signing environment ... 15 URLs ... 15 Networking ... 16 Integration issues ... 16 Time synchronization ... 16 Restrictions ... 17 Test users ... 17 XML notifications ... 17
Use GetSigning-Processes to check status ... 17
4. KeyUtil ... 19 Installation ... 19 Installation prerequisites ... 19 Installation KeyUtil ... 19 Using KeyUtil ... 20 Generate a key ... 20 Import a certificate ... 21
5. Appendix 2 – eID providers ... 22
Introduction ... 22
eID links ... 22
How to enable a new eID ... 22
BankID (NO) ... 23
Test certificate ... 23
Production certificate ... 23
BankID 2.0 (without Java) ... 23
3 - 41
Using the XML format ... 27
BankID (NO) without “OK-button” in client ... 27
BankID on mobile phones (“BankID på mobil”) (NO) ... 28
Information ... 28
Test certificate ... 28
Production certificate ... 29
Document format ... 29
Pre-set mobile phone number and birthdate ... 29
Limitations ... 29 Buypass (NO) ... 30 Information ... 30 Document formats ... 30 BankID (SE) ... 31 Introduction ... 31
Test certificate and clients ... 31
Production certificate ... 31
Autostart and SignerID in BankID ... 32
Document formats ... 33
Adding text to BankID security app signing field ... 33
Not supported functionality ... 34
Known issue ... 35
NemID – personal (POCES) and employee (MOCES) certificates (DK) ... 35
Information ... 35
NemID VOCES certificate ... 36
Test users ... 37
NemID JS client and CSS styling ... 37
Document formats ... 39
Not supported functionality ... 39
PDF validation ... 39
NemID youth certificates ... 39
SSN (CPR) in SDO ... 40
4 - 41
1.
Introduction
Purpose The E-Signing service is used to sign documents with electronic ID. This
service gives the ability to sign multiple documents by multiple signers with multiple ID’s. Signers and merchants may be notified through multiple channels like XML, SMS and e-mail.
E-Signing is a web service that acts on behalf of a merchant and offers the following functions:
- Electronic signing
- Authentication before signing
- A number of eID providers for signing
- Possibility for synchronous and asynchronous signing operations - Serial, parallel or combined signing flow
- Archival of signed documents
- Notification via different channels to both End users and the Mer-chant
Document overview This document is divided into five chapters. The first chapter gives an in-troduction, states the intended audience, referenced documentation and a glossary.
Chapter two describes the integration process while chapter three gives a more detailed description about the E-Signing integration.
The scope of the document is to give the reader the ability to:
- Understand how the integration process is defined. That is, the se-quence of activities that the merchant has to perform to get the service up and running.
Intended audience This document is intended for technical project leaders, merchant
integra-tors and developers. Referenced
documentation
Document Description
Nets E-Signing
Func-tional Description A detailed description of the E-Signing service and all its functionality with reference to archi-tecture and interfaces
Nets TrustSign-Message Interface Specification
This document describes the XML messages in the TrustSignMessage communication protocol for accessing E-Signing.
TrustSignMessage
XML Schema A schema defining the TrustSignmessage XML message structure. Nets
TrustNotifica-tionMessage Interface Specification
A detailed description of the E-Signing Notifica-tion service
5 - 41 Message XML Schema message structure
Nets Signing and Identification Services Technical Configura-tion form
The technical configuration form includes all necessary configuration details that are needed to enable Merchants in the customer test and production system.
Nets E-Signing Mer-chant technical verifi-cation test
This document describes tests that must be completed before the merchant is enabled in the production system
XML Signature Syntax
and Processing http://www.w3.org/TR/xmldsig-core/
Terms and
definitions Term Merchant The business entity that owns a sign order Description
Signer The user to whom a sign order is directed. Equivalent to end user
Acronym Acronym Description
HTML Hyper Text Markup Language
HTTP Hyper Text Transfer Protocol
HTTPS Secure HTTP
NTP Network Time Protocol
PDF Portable Document Format
PKCS#10 Certification request standard. See RFC 2986.
PKI Public Key Infrastructure
SDO Signed Data Object
SEID SDO ”Samarbeidet om Elektronisk ID” Detailed information about SEID SDO:
http://www.npt.no/iKnowBase/Content/44963/ SEID_Leveranse_3_v1.0.pdf
SMS Short Message System
SSL Secure Socket Layer
SSN Social Security Number
UTC Coordinated Universal Time
UTF-8 A character encoding format of ISO 10646 (RFC 3629)
6 - 41
XMLDSIG XML Digital Signature
Change log
Version Description Date
3.0 New URL’s and IP addresses to the service, replacing preproduction with customer test, updated infor-mation about BankID certificates, removing old information regarding NemID OTP applet, adding infor-mation about CPR (SSN) from NemID in SDO and error correc-tions.
10.12.2015
3.1 Corrected the IP address for TrustSignMessage (prod) on Extra-net
18.12.2015
3.2 Added information about how to use nemid_clientmode=limited and cor-rected the IP address for TrustSign-Message (prod) on Internet.
15.03.2016
3.3 This version includes these updates: - NemID process description - Added information about
server certificates - How to add texts to the
BankID SE security app. - Removed information about
the eIDs BankID NO app and Telia e-legitimation
27.05.2016
3.4 Corrected information about Nets on first page.
7 - 41
2.
Integration process
Overview A Merchant is a customer of Nets Signing and Identification Services and
must be registered in the E-Signing infrastructure.
Nets Signing and Identification Services has two environments available for its customers. These are the customer test environment for implementa-tion and testing purposes and the producimplementa-tion environment.
Note that updates to the customer test environment are usually performed during normal working hours. A notice to customers will be sent 1-2 days prior to the planned update1.
Merchant configurations in both environments are done on Wednesdays. To be registered all configuration data must be available for Nets Signing and Identification Services by noon the previous Friday.
Customer test
configuration The following data must be available for Nets before customer test configu-ration:
• Merchant test certificate from eID providers supported by E-Signing
• Completed “Nets Signing and Identification Services Technical
Con-figuration Form” (all customer test fields must be completed) • XML notification data (optional, see detailed description in the
Net-working section in chapter 3.
• A certificate request (*.p10 file) for signing and SSL client authen-tication (see detailed description in the Merchant certificates sec-tion).
All configuration data should be sent to the support address, [email protected].
After Nets’ configuration, the Merchant will receive the connection data (MerchantID and certificates).
The Merchant may now use the customer test environment for develop-ment, integration and testing of its own system. Issues not covered in the documentation should be directed to the support address.
After the implementation and testing of the merchant’s system the “Nets
E-Signing Merchant technical verification test” must be completed. This
must be done some time before the production configuration.
1Notifications are sent to e-mail addresses defined in the “Notification regarding service operation” field in the “Nets Signing and Identification Services Technical
8 - 41 Production
configuration The following data must be available for Nets before production configura-tion:
• Merchant certificate from eID providers supported by E-Signing
• “Nets Signing and Identification Services Technical Configuration
Form” updated with production data
• Completed “Nets E-Signing Merchant technical verification test”
• XML notification data (optional, see detailed description in the Net-working section in chapter 3.
• A certificate request (*.p10 file) for signing and SSL client authen-tication (see detailed description in the Merchant certificates sec-tion).
For handling of merchant certificates, see the Merchant certificates section later in this chapter.
After Nets’ configuration, the Merchant will receive the connection data (MerchantID and certificates).
The Merchant can now connect to the production system and verify the service integration.
Merchant data When filling the “Nets Signing and Identification Services Technical
Config-uration Form”, a Merchant needs to specify:
• Contact information for the Merchant, technical partners and eID providers
• Required eID provider(s)
• Required service(s)
• Information about servers/applications connected to the Nets infra-structure (IP addresses etc.)
• Dates for desired customer test/production configuration2
Merchant
certificates Merchant certificates from selected eID providers must be ordered from the different eID provider and handed securely over to Nets. See the Ap-pendix 2 – eID providers in chapter 5 for more information about the dif-ferent eID providers.
The Merchant needs a certificate to access the E-Signing service. This
2 It is recommended to schedule the production configuration date some days prior to the Merchants go-live date.
9 - 41 tificate, often referred to as the “sign-auth certificate”, is used to both sign the XML request and for SSL client authentication. The following must be done to retrieve the certificates.
• Generate a certificate request (*.p10 file) with belonging keys3. The certificate can be generated using any key generation tool. Nets offer one tool, see chapter 4 for more information. The fol-lowing is required fields in the certificate
a. CN: <The Merchant’s name or application’s name> b. O: <The Merchant’s name>
c. C: <Country code – Norway is NO) d. KeyLength: 2048 bit
• Send the *.p10 file to [email protected].
• Nets’ Eurida Connect CA will be used to issue the certificate, and the certificate will be returned to the Merchant after successful configuration at E-Signing. The Eurida Connect is a Root CA and its certificate can be downloaded from the following links:
Customer test: http://ca-preprod.eurida.com/ca/euridaconnect.cer Production: http://ca.eurida.com/ca/euridaconnect.cer
See the “Nets TrustSign Message Interface Specification” for more details regarding the use of the XML signing with certificate.
Server certificates In order to access E-Signing services you need to add trust for the server's
SSL certificate. This is typically accomplished by adding the relevant root certificate to your local trust store. Below, the root certificate for both cus-tomer test and production environment is included. You will also find the full certificate chain for both Customer Test and Production included in the "Server certificate" folder of the E-Signing document package.
Production & Customer test environment Root certificate, VeriSign Class 3 Public Primary Certification Authority - G5:
---BEGIN CERTIFICATE--- MIIE0zCCA7ugAwIBAgIQGNrRniZ96LtKIVjNzGs7SjANBgkqhkiG9w0BAQUFADCB yjELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTowOAYDVQQLEzEoYykgMjAwNiBWZXJp U2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MUUwQwYDVQQDEzxW ZXJpU2lnbiBDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0 aG9yaXR5IC0gRzUwHhcNMDYxMTA4MDAwMDAwWhcNMzYwNzE2MjM1OTU5WjCByjEL MAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZW
3 When generating a certificate request, a private and public key pair is formed. The *.p10 file includes the certificate data and the public key. The private keys must be securely stored.
10 - 41 ZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTowOAYDVQQLEzEoYykgMjAwNiBWZXJpU2ln biwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MUUwQwYDVQQDEzxWZXJp U2lnbiBDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9y aXR5IC0gRzUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCvJAgIKXo1 nmAMqudLO07cfLw8RRy7K+D+KQL5VwijZIUVJ/XxrcgxiV0i6CqqpkKzj/i5Vbex t0uz/o9+B1fs70PbZmIVYc9gDaTY3vjgw2IIPVQT60nKWVSFJuUrjxuf6/WhkcIz SdhDY2pSS9KP6HBRTdGJaXvHcPaz3BJ023tdS1bTlr8Vd6Gw9KIl8q8ckmcY5fQG BO+QueQA5N06tRn/Arr0PO7gi+s3i+z016zy9vA9r911kTMZHRxAy3QkGSGT2RT+ rCpSx4/VBEnkjWNHiDxpg8v+R70rfk/Fla4OndTRQ8Bnc+MUCH7lP59zuDMKz10/ NIeWiu5T6CUVAgMBAAGjgbIwga8wDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E BAMCAQYwbQYIKwYBBQUHAQwEYTBfoV2gWzBZMFcwVRYJaW1hZ2UvZ2lmMCEwHzAH BgUrDgMCGgQUj+XTGoasjY5rw8+AatRIGCx7GS4wJRYjaHR0cDovL2xvZ28udmVy aXNpZ24uY29tL3ZzbG9nby5naWYwHQYDVR0OBBYEFH/TZafC3ey78DAJ80M5+gKv MzEzMA0GCSqGSIb3DQEBBQUAA4IBAQCTJEowX2LP2BqYLz3q3JktvXf2pXkiOOzE p6B4Eq1iDkVwZMXnl2YtmAl+X6/WzChl8gGqCBpH3vn5fJJaCGkgDdk+bW48DW7Y 5gaRQBi5+MHt39tBquCWIMnNZBU4gcmU7qKEKQsTb47bDN0lAtukixlE0kF6BWlK WE9gyn6CagsCqiUXObXbf+eEZSqVir2G3l6BFoMtEMze/aiCKm0oHw0LxOXnGiYZ 4fQRbxC1lfznQgUy286dUV4otp6F01vvpX1FQHKOtw5rDgb7MzVIcbidJ4vEZV8N hnacRHr2lVz2XTIIM6RUthg/aFzyQkqFOFSDX9HoLPKsEdao7WNq ---END
11 - 41
3.
E-Signing integration
Overview The E-Signing infrastructure may be seen as an extension to Merchant
applications. The main purpose of E-Signing is to offer a digital signing service for Merchants by extracting abstract cryptographic operations for Merchant applications.
The E-Signing infrastructure is composed of several components. Each component has a dedicated task. The figure below is a high-level compo-nent layout of the E-Signing infrastructure:
The E-Signing concept is described in detail in the “E-Signing Functional Description” document.
The E-Signing infrastructure exposes 3 interfaces.
• The E-Signing web services:
An XML interface for inserting and managing Signing orders. See”Nets TrustSignMessage XML Interface Specification” for more details.
12 - 41 An XML interface to notify Merchants and End users about events regarding orders they participate in. See “Nets
TrustNotification-Message Interface Specification” for more details. • SignWeb:
A runtime interface for performing signing operations. This is the signing portal where end-users actually sign documents. See ”Nets
E-Signing SignWeb Integration Guide” for more details
The E-Signing service exposes simple interfaces to merchants that want to offer digital signing to their customers. To do so merchants must give E-Signing access to their digital ID. By interacting with the E-E-Signing using the TrustSignMessage web services, merchants may “remote control” the use of their own id without getting into the cryptographic issues.
E-Signing is a workflow based signing engine, and merchants interact with E-Signing via the TrustSignMessage XML interface. Through E-Signing, Merchants can place, manage and monitor Signing orders.
The TrustSignMessage XML interface exposes many request types to re-trieve and change existing orders. This is described in details in “Nets
13 - 41
XML Interface integration
The E-Signing service is built up on web service requests and responses. The Merchant needs to implement the interface between the Merchant and the E-Signing service in the figure below. The interface is indicated with a green line.
Web services The web service interface to the E-Signing service is built up of two Nets
provided XML schemes:
- TrustSignMessage service - TrustNotificationMessage service Signing XML
messages All messages to the E-Signing service must be signed with XMLDSIG to be
able to reach the service. The XMLDSIG must be of the enveloping kind. The entire message must be signed using the signing certificate the Mer-chant will be given upon configuration in the customer test and production environment respectively.
Information about the XMLDSIG standard is found at W3C,
http://www.w3.org/TR/xmldsig-core/. A text description of the standard
may be found at this link, http://en.wikipedia.org/wiki/XML_Signature. See the Example message section below for an example of a signed mes-sage including both a XMLDSIG signature and a TrustSignmesmes-sage.
TrustSignMessage TrustSignMessage is the system the Merchant interacts with to manage its
Signing orders. The “TrustSignMessage Interface Specification” and “TrustSignMessage XML Schema” describes the complete XML interface in detail. This XML interface consists of several messages that the Merchant
14 - 41 can use when implementing E-Signing.
Mandatory XML messages to implement:
• InsertOrder: In this message it is defined what to sign (docu-ments), who is signing (signers), where the signing is going to take place (web context), archival and who is signing which document in which order (execution details).
• GetOrderStatus: The message gives the overall status of the order, the document, signer(s), steps and execution details during the or-der-lifetime.
• GetSigningProcesses: This message fetches the URL for each sign-ing process and it shows the status of each Signsign-ing process.
Example message An example of a message to E-Signing is shown below:
<?xml version="1.0" encoding="UTF-8"?>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<CanonicalizationMethod Algorithm=" http://www.w3.org/2001/10/xml-exc-c14n#" xmlns="http://www.w3.org/2000/09/xmldsig#"/>
<SignatureMethod Algorithm=" http://www.w3.org/2000/09/xmldsig#rsa-sha1" xmlns="http://www.w3.org/2000/09/xmldsig#"/>
<Reference URI="#object" xmlns="http://www.w3.org/2000/09/xmldsig#"> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"
xmlns="http://www.w3.org/2000/09/xmldsig#"/> <DigestValue xmlns="http://www.w3.org/2000/09/xmldsig#">571jnDgGjp+N8ONpwmIOJENqf Hw=</DigestValue> </Reference> </SignedInfo> <SignatureValue xmlns="http://www.w3.org/2000/09/xmldsig#">....xJzkb3MkhlsUI9zczKbNJcuLG Jzcvw==</SignatureValue> <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"> <X509Data xmlns="http://www.w3.org/2000/09/xmldsig#"> <X509Certificate>...MgVo7GzAgIsZadVuemvYcs149r2jAzfP9Hzz8yrgxu4=</X509 Certificate> </X509Data> </KeyInfo>
<Object Id="object" xmlns="http://www.w3.org/2000/09/xmldsig#"> <TrustSignMessage xmlns="http://www.bbs.no/tt/trustsign/2009/05/tsm#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <MerchantID>9999</MerchantID> <Time>2008-11-10T11:12:25+02:00</Time> <MessageID>1</ MessageID > <InsertOrder> <OrderID>1228903945807</OrderID> ...
15 - 41 </InsertOrder> </TrustSignMessage> </Object> </Signature> TrustNotificationMe
ssage A TrustNotificationMessage is an XML notification message that is sent to
Merchant XML services from E-Signing. A Merchant defines its XML service by defining an “XMLService” notification channel when placing a Signing order. The interface is detailed in the following document: “Nets
TrustNoti-ficationMessage Interface Specification” and “TrustNotiTrustNoti-ficationMessage XML Schema” documents.
SignWeb – Graphical User Interface
GUI SignWeb provides End users with an interface for accessing and digitally signing documents. The SignWeb portal is described in detail in the “Nets
SignWeb Merchant Integration Guide” document and the “Nets UDD Style guide”.
E-Signing environment
URLs The table below provides the URLs to the E-Signing interfaces for both the
customer test and production environments.
Interface Preproduction Production
TrustSign-Message https:// order.sign-preprod1.nets.eu/tsos /XmlGw
https://
or-der.sign.nets.eu/tsos /XmlGw
SignWeb https://www.
sign-preprod1.nets.eu /sign https://www. sign.nets.eu /sign XML
16 - 41
Networking Ensure that all proxy servers and firewalls give you the necessary access to
E-Signing. See the E-Signing IP addresses in the tables below. Firewall openings (Internet) IP Address Port XML notification (customer test) 91.102.27.1
XML notification (production) 91.102.24.153
TrustSignMessage (customer test) 91.102.25.55 443 TrustSignMessage (production) 91.102.25.110 443
SignWeb (customer test) 91.102.25.56 443
SignWeb (production) 91.102.25.94 443
Firewall openings (Banking Net) IP Address Port XML notification (customer test/
Prod) 91.102.26.126
TrustSignMessage (customer test) 91.102.25.183 443 TrustSignMessage (production) 91.102.25.184 443 Note that all E-Signing interfaces communicate via SSL.
Merchants that need to be notified by XML must provide Nets with their service’s IP address. They must also make sure that Nets is allowed to contact their service by opening their firewall. If the merchant wants extra security on the communication from Nets to the merchant like basic au-thentication, SSL or client SSL, the merchant has to notify Nets and hand over the possible root certificates or keystore. For security reasons, key-store information must not be handed over in an open e-mail.
Integration issues
Time
synchronization The merchant’s system needs to be synchronized towards a reliable time source that is an NTP server. This is a security measure.
• The time range allowed for E-Signing is +/- 5 minutes compared to NTP time.
• The time set in the XML messages shall contain time zone infor-mation. That is, the merchant can use any time zone he wants. If the time zone information is not included, UTC will be used as de-fault.
17 - 41
Restrictions Text sent to TrustSignMessage shall be well formatted XML documents and
NOT contain html tags, java scripts or any malicious code.
The maximum size for an InsertOrder XML message is currently 5.7 MB. See also the “Document formats and sizes” section in chapter 4 in the
“Nets E-Signing Functional description” for recommended sizes for an eID.
E-Signing does only support UTF-8 encoded requests.
Test users See Appendix 2 – eID providers for information about test users.
XML notifications If the Merchant are using XML notifications from the E-Signing service (the
TrustNotificationMessage XML), be aware that the E-Signing service ex-pects an OK message from the Merchant within 5 seconds. It is important that the Merchant don’t implements other functions before an OK is given (for example using the GetSDO prior to saying OK). If an OK is not re-ceived within 5 seconds, the E-Signing service expects that something went wrong, and it will try to re-send the XML notification.
Use GetSigning-Processes to check status
In E-Signing’s XML interface there are many different status requests. One of the most common that will give a lot of “answers” in a single message is GetSigningProcesses.
The request:
Parameter Description
OrderID The Order you want to fetch the
status from.
LocalSignerReference The local reference to the signer. This is defined in the InsertOrder XML message
SigningProcessStatusFilter If you only want to get Signing processes with a specific status (Values are : Active, Pending, Complete, CancelledByMerchant, Expired, RejectedBySigner)
18 - 41 The response:
Highlights of some elements in the response:
Parameter Description
OrderStatus Status on the Order.
SigningProcessResult.Status Status on the SigningProcess. If this status is set to Complete, the End user has signed the document and all verifications have passed.
SignURL The signature URL for accessing
this Signing process. This is the URL the End user must use to start the Signing process.
If a Merchant wants to check if the End user has signed the document, the Merchant should check the SigningProcessResult.Status and not the Order status. When E-Signing redirect the End user back to the Merchant’s “ex-itUrl” the SigningProcessResult.Status will always be completed. But since this is a redirect through the End user’s browser the Merchant should al-ways verify this with the GetSigningProcesses message (the End User can fake this redirect). When the End user has completed the signature and E-Signing has redirected the End user back to the Merchant (exitUrl) the SigningProcessResult.Status will always be completed, but the Order status will probably have the status Active. The reason for this is that E-Signing have some post processing on the Order after a signature (Create and seal SDO, Notification, Archive), and this is asynchrony. When all post pro-cessing tasks have been performed (and no more signers on the Order) the Order status will be set to Complete.
19 - 41
4.
KeyUtil
Keyutil provides a command-line interface for software based key stored using the pkcs#12 storage format.
It’s main tasks is to generate RSA key pairs, create certificate requests and ul-timately create pkcs#12 based key stores based on imported certificates.
Installation
Installation
prerequisites Other software and hardware than listed in this chapter may also be fully functional. This is an overview of software and hardware officially tested by Nets.
The software and hardware listed in this chapter must be installed and fully functional before keyutil can be used.
Supported operative systems
• Windows XP SP3
• Solaris 10 SPARC
Supported Java Runtime Environments
• Sun Java Runtime Environment (JRE) 5.0 or higher
Installation KeyUtil Step Description Requirements / Results
1. Copy Keyutil package
Copy Keyutil -x.x.x.tar.gz or Keyutil -x.x.x.zip to a tempo-rary folder.
2. Extract package Extract package to destination folder.
3. Install Unlimited Strength Juris-diction Policy Files
Install JCE Unlimited Strength Crypto Policy Files under the used jvm.
keyutil
20 - 41
These files can be retrieved from:
http://java.sun.com/javase/down loads/index.jsp
At the bottom of the site there is a row with the name “Other Downloads” where you can find the target files.
Be sure to pick the file for your target jvm version.
When downloaded, extract the zip file and copy these files:
“COPYRIGHT.html” “local_policy” “README” “US_export_policy” to “$JAVA_HOME/jre/lib/security”
Using KeyUtil
Generate a key keyutil keygen
[-dn <distinguished name>] -pw <Key store password> -keysize <key size>
-keyfile <file in which to store private key> -p10file <file name>
The given dn must be enclosed by double quotes if it includes spaces and be of the format shown below. pw is the password that protects the
21 - 41 vate key and must be a regular passphrase of any length, keysize the
number of RSA bits (typically 1024, 2048 or 4096), keyfile is the file that will contain the protected private key and p10file the file name of the PKCS#10 certificate request.
See the Merchant certificates section in chapter 2 for the requirements to the certificate request.
Example on unix
# ./keyutil.sh keygen -dn "CN=Merchant A,O=Merchant A,C=NO" –pw
password -keysize 2048 –keyfile merchantA.key -p10file
merchan-tA.p10
Example in dos:
#.../keyutil keygen -dn "CN=Merchant A,O=Merchant A,C=NO" -pw
password -keysize 2048 –keyfile merchantA.key -p10file
merchan-tA.p10
If successful, the output is a Base64 PEM encoded PKCS#10 written to the specified file while status, filenames and PKCS#10 hash is shown on the screen. The key file is created and will be deleted during certificate import.
RSA key pair successfully generated
PKCS#10 certificate request written to merchantA.p10
Key file written to merchantA.key
Import a certificate keyutil import
-pw <Key store password>
-keyfile <File in which the private key is stored> -certfile <certificate file>
-p12file <The pkcs#12 file to generate>
pw is the password used for protecting the private key, keyfile is the file that contains the protected private key, certfile the (path and) name of the certificate file in DER, PEM or Base64 format and p12file is the final keystore containing the certificate and the private key.
Example
# ./keyutil.sh import -pw password –keyfile johnsmith.key – certfile johnsmith.cer –p12file johnsmith.p12
22 - 41
5.
Appendix 2 – eID providers
Introduction This appendix aims to list information regarding the different eID
provid-ers. This includes how to retrieve a Merchant certificate from the eID, how to retrieve test certificates, information about the eID, restriction regarding the eID and other information.
eID links eID provider How to obtain merchant ID
BankID (NO) http://www.bankid.no
BankID on mobile phones (“BankID på
mobil”) (NO) http://www.bankid.no
Buypass Smartcard (NO) http://www.buypass.no BankID including Mobile BankID and
Nordea e-legitimation (SE) http://www.bankid.com NemID POCES (DK) https://www.nets-danid.dk/ NemID MOCES (DK) https://www.nets-danid.dk/ How to enable a
new eID To enable a new eID for your Merchant site, the following steps should be fulfilled:
- Send an updated version of the “Nets Signing and Identification Services Technical configuration form” to support. If the eID should be added to your existing Merchant site, please state existing site and your MerchantID. Complete the applicable fields in the chapter regarding eID’s.
- Your Merchant application might need to update to the latest TrustSignMessage XML scheme. See the AcceptedPKIs element in
the InsertOrder for supported eID’s in that scheme. For more
in-formation about the InsertOrder message and the AcceptedPKIs element, see the “Nets TrustSignMessage XML interface
specifica-tion”.
- Specific eID details like eID information, merchant certificates and test certificates are provided later in this chapter.
- The parameter “forcepkivendor” can be used to distinguish be-tween the eID’s configured on your merchant site. See the “Nets
E-Signing Signweb integration guide” for more information about this
23 - 41
BankID (NO)
Test certificate Nets eSecurity support will issue a test merchant certificate to you if not
otherwise stated. In cases where others are issuing the certificate, please send the activation link and code for the certificate to Nets eSecurity sup-port: [email protected], (or you can make the bank forward the information directly). Nets Signing and Identification Services will activate the certificate and do the configuration.
End user test certificates can be ordered from Nets eSecurity support at
[email protected]. If you need a specific SSN (preferably a fictive
as this is test), please provide that together with the request for a test user certificate.
Production
certificate Nets through the Signing and Identification Services are resellers of Bank-ID merchant certificates, and this can be ordered either separately or tog-heter with E-Signing. If ordered through Nets, you will in an information letter be asked to complete a form with information needed to create a BankID “brukerstedsavtale” with BankID Norge. The form shall be returned
to [email protected], and based on the form Nets will register this
order at BankID. After the registration you will be asked to confirm and sign the order. When the order is signed with BankID Norge, Nets will re-ceive the activation information for your BankID merchant certificate from your bank. The merchant certificate will be activated and connected to your E-Signing configuration.
If you haven’t ordered the BankID merchant certificate through Nets, you will receive an activation link and code from your bank or another reseller of BankID merchant certificates. Contact Nets Signing and Identification Services support to get the name and number of the person that shall re-ceive the certificate information. The certificate information shall be sent to Nets Signing and Identification Services in two different channels (e.g acti-vation link in an e-mail and actiacti-vation code by sms).
If your bank requires a CoC (Certificate of Confirmation) before issuing the merchant certificate, please contact support. Nets Signing and Identifica-tion Services will send a CoC to your bank.
BankID 2.0
(without Java) From the 2.0 release of BankID, the BankID client is independent of Java. The E-Signing service is updated to support the new BankID client without Java. This section will explain what to do to start using the new BankID client and customer impact.
24 - 41 Migration and getting started
Migration to BankID 2.0 client from BankID Java applet:
System What to do
Customer test Migration of the customer’s merchant site is done upon request to [email protected]. Please supply us with your MerchantID / MID and the preferred time for migration. If BankID Java applet should be available after the configu-ration, please let us know. See the IE8 workaround for in-formation regarding this.
Migration in customer test is done consecutively and within 1-2 working days from the request.
Production Nets will schedule weekly migrations of customers in pro-duction. This will mainly be every Wednesday during day time. However the first will be Wednesday the 8th October 2014. Please notify Nets eSecurity support 10 days prior to migration.
Other migration times than Wednesdays may be agreed with Nets. Please notify Nets eSecurity support as soon as possible about your preferred time schedule.
When notifying Nets about your preferred production time, please include the MerchantID(s) /MID(s) and a contact person (e-mail and phone number) during the update. A roll-back procedure of your migration will be in place. Notify Nets eSecurity support as soon as possible if you are in need of a roll-back of the migration.
Customer impact
The migration to BankID 2.0 may be done without any specific changes in the interface between the customer and the E-Signing service. The follow-ing should however be considered:
1. The use of BankID 2.0 and Internet Explorer 8. It will not be possi-ble to use IE 8 together with the BankID 2.0 client. A solution to use IE8 together with the “old” BankID Java applet will be added prior to production. See the end of this section for a workaround. 2. There will be no changes to “TrustSignMessage” XML schema. 3. A new “forcepkivendor” parameter is defined (“no_bankid”), but for
backward compatbility, the old will still work. It is however recom-mended to change this parameter as the old will be phased out at a later point. Regarding this point, be aware of the workaround for customers using both BankID 2.0 and BankID Java applet to still support IE 8.
4. Migration to BankID 2.0 will impact graphical appearance and plat-form support. Nets strongly advices the customers to use the cus-tomer test facilities to test migrated systems before opening for
25 - 41 the production system. It is further adviced to test all document
types used for signing for responsiveness with different mobile de-vices. The recommended and minimum IFRAME sizes from BankID are:
a. Large screen (Desktop/tablet): 396px (w) by 280px (h) (recommended) / 370px (w) by 204px (h) (minimum) b. Small screen (Smartphone) (only minimum sizes): 320px
(w) by 350px (h) (portrait) / 480px (w) by 200px (h) (landscape)
c. Note: Customers using the signing deadline and/or signers table in E-Signing may need to use a slightly higher IFRAME size than the recommended sizes.
5. The optional possibility to remove the last page in the BankID sign-ing applet (confirmation page) will be as with the BankID Java ap-plet, hence as a configurable option for each customer. See the section BankID (NO) without “OK-button” in client
6. The optional possibility to show XML/HTML documents in a big win-dow is no longer possible in BankID. Customers using this option are recommended to either adjust their documents to the IFRAME size or increase the IFRAME size.
7. Some customers may experience that the BankID client has been cropped inside the IFRAME. This is solved by adjusting your CSS file. See the “CSS file adjustment” section on the next page. IE 8 workaround
IE 8 is not supported with BankID 2.0. To be able to still support IE 8 a workaround to load the “old” BankID Java Applet will be made available. This functionality is not available in the first release of BankID 2.0 support in E-Signing. Please make sure to notify our support that you want both BankID 2.0 and BankID Java Applet to be available.
If your Merchant configuration is made available with both BankID 2.0 and BankID Java Applet, the parameter “forcepkivendor” must be used to de-termine which client to start. The “no_bidnc” will start the BankID Java Applet, while “no_bankid” will start the BankID 2.0 client. If the “for-cepkivendor” parameter is not given, BankID 2.0 will be started. The user will never get the possibility to select between BankID 2.0 client and Bank-ID Java Applet. If the “Select” page from E-Signing is shown to the end user, only one choice for BankID will appear, and this is the newest version
26 - 41 of BankID.
Note: If you today are using the “forcepkivendor” parameter, your imple-mentation must be changed so that the “no_bidnc” parameter is not sent as default. If you have not specified that the BankID Java Applet shall be available for your configuration, both “forcepkivendor” parameters (“no_bidnc” and “no_bankid”) will start the BankID 2.0 client.
For more information about the “forcepkivendor” parameter and its use, see chapter 3 in the “Nets E-Signing SignWeb integration guide”. CSS file adjustment
The BankID 2.0 client must be styled with CSS to display properly. The default styling has a CSS rule that sets the proper sizes. If you override styling, your style sheet must be updated for the new BankID client. Styl-ing can be overridden by sendStyl-ing a style URL in the WebContext element in the InsertOrder request.
The default CSS styling sets width to 100% and height to 75%. The client will expand to fill the container (iframe), but leave some space below the client for signing deadline text and status table. If an status table is dis-played, the height can be increased.
When overriding styling, the sample CSS below will produce the same ef-fect as the default styling.
#bid_client { height: 75%; min-height: 280px; } #nobankid_index_html { height: 100%; } #nobankid_index_html .iframe,
#nobankid_index_html .iframe .ipage { height: 100%;
}
#nobankid_index_html .iframe .ipage .main { height: 100%;
min-height: 200px; }
27 - 41
Document formats The following document formats are supported using BankID (NO)
- PDF - Text - XML
Note: There is a known error with XML and ÆØÅ encoding. This was intro-duced with BankID 2.1 in E-Signing.
Using the XML
format BankID (NO) mandates that if an End user signs XML data then an XSL must be provided as well. The XSL is used to transform the XML to
pre-sentable HTML. So the merchant must provide two documents when they want an XML-document to be signed.
<BankIDXML>
<XML> ANSGKFLSDSF==</XML>
<XSL> ANSGKFLSDSF==</XSL> </BankIDXML>
The BankIDXML structure is the document that the End user actually signs. When E-Signing sends this BankIDXML structure to the BankID eID client, it recognizes this structure and performs an XML transformation. The result of the XML transformation is an HTML which again is presented to the End User. The XML and XSL document bytes provided by the merchant must be in 8859-1. So when providing the XML and XSL bytes, get the ISO-8859-1 (ISO-LATIN-1) bytes. The ISO-ISO-8859-1 bytes must be Base64-encoded.
BankID (NO) without “OK-button” in client
It is possible to remove the last screen in the BankID client. This is a con-figuration issue. To remove the button, contact support.
This is the last screen in the BankID client.
When adding this functionality to your Merchant site be aware of the fol-lowing:
After the last signature has been added to the document, a SDO is created and sealed. This operation may take a few seconds (depending on the size of the documents and the number of signers). If the Merchant makes a
28 - 41 request like a “getOrderStatus” to E-Signing right after the user has been returned to the Merchant’s site this may give the result “InProgress” even though all signers have signed the document(s) in the Sign order. The order is at this moment in the process of making the SDO. When present-ing the Signer with the last screen in the BankID client this has usually not been a problem since the creation and seal of the SDO has been completed before the user has been able to click “OK”. However, when removing the last screen the Signer is returned to the Merchant site a little bit earlier and the SDO may not have been finalized. To avoid this issue, you can do one of the following:
• If a getOrderStatus has returned an “InProgress” when you are ex-pecting complete, have a look at the “SigningProcessStatus” in the same message. This should have been set to “Complete”. To up-date your own systems with correct status of the order, wait a few seconds and send a new getOrderStatus.
When using XML notifications to get the status of an order, use the “On-OrderCompletion” notification instead of (or in addition to) “OnSignPro-cess” completion when it is the last signer in the order. Note: The “On-SignProcess” are used to check if the SignProcess has succeeded, and the “OnOrderCompletion” are used to check the status of the entire Order. The order status should be used if the Merchant are going to fetch the signed document (SDO) or show the signed document (SDO) to the end user.
BankID on mobile phones (“BankID på mobil”) (NO)
Information To enable BankID on mobile phones (NO) in your Merchant application you
need an agreement with a bank issuing BankID (NO) for a merchant certif-icate (“Brukerstedssertifikat”). When ordering the BankID merchant certifi-cate make sure to order BankID on mobile phones as well.
To be able to use BankID on mobile phones you also need an agreement with the phone suppliers. Your bank will supply you with the information you need.
More information:
https://www.bankid.no/
Test certificate For issuance of a BankID merchant test certificate, see the Test certificate
section in the BankID (NO) part earlier in this chapter. Remember to order BankID on mobile phones when you order a BankID (NO) merchant test certificate.
For End user test certificate you need a dedicated mobile phone with a SIM-card for test purposes. Contact BankID Norge to retrieve a SIM-card. After receiving the SIM-card, contact BankID support ([email protected])
29 - 41 to register the SIM-card in BankID preproduction.
Production
certificate For issuance of a BankID merchant certificate, see the Production certifi-cate section in the BankID (NO) part earlier in this chapter. When ordering the BankID merchant certificate make sure to order BankID on mobile phones as well.
Document format It is only possible to sign a text document of 116 characters using BankID
on mobile phones. There will be added 4 GSM characters to the original document.
Pre-set mobile phone number and birthdate
The end user’s mobile phone number and birthdate may be preset at the Merchant’s own site prior to calling the E-Signing service. The mobile phone number and birthdate can be appended as parameter to the signing URL. See the “Nets E-Signing Signweb integration guide” for more infor-mation.
Limitations The E-Signing service has made it possible to sign short text documents
using BankID on mobile phones. The signing with BankID on mobile phones is very useful if you have a short document to sign and there is only one signer.
There are however some limitations that must be considered when starting to use signing with BankID on mobile phones:
- The document sent to E-Signing will be changed to support signing in a phone. Two bytes are added and the document is GSM encod-ed.
- If the document shall be signed by more than one person and the user has another eID than BankID on mobile phones, the user signing with the other eID might have trouble reading the docu-ment as it is GSM encoded. If there are only users with BankID on mobile phones, this should not be an issue.
- When validating the signed document (SDO), the document may look awkward as it is GSM encoded.
30 - 41
Buypass (NO)
Information Buypass merchant certificates must be ordered from Buypass Smartkort
(www.buypass.no). Buypass will issue two sets of certificates. The keystore certificates (used to secure communication between Buypass and E-Ident) will be sent by registered mail to Nets, and the password will be sent to a defined person in Nets. The Buypass merchant certificate (used to seal the SDO) will be sent by e-mail to the person ordering the certificates and the password is sent registered to either the person ordering it or a defined person in Nets. The last part must be agreed between the merchant and Nets.
Document formats The following document formats are supported using Buypass (NO)
- PDF - Text
31 - 41
BankID (SE)
Introduction To enable BankID (SE) in your Merchants application you need an
agree-ment with a bank issuing BankID (SE). See https://www.bankid.com for banks that issues BankID and general information about BankID. BankID (SE) is issuing End user certificates in different ways
(http://www.bankid.com/sv/Vad-ar-BankID/BankID-pa-flera-satt/).
“Bank-ID på kort”,“Bank“Bank-ID på fil” and “Mobilt Bank“Bank-ID” are all supported through E-Signing. From April 2014, Nordea e-legitimation certificates are also supported through BankID (SE).
Test certificate and
clients Nets Signing and Identification Services has a test merchant certificate and test user certificates that the Merchant can use. This will be distributed to you during configuration of the test Merchant site. You may also get end user test certificates from your bank.
To test signing using Mobilt BankID, a test version of the “BankID säker-hetsapp” must be downloaded from http://www.bankid.com/rp/info/ and a test certificate to the given phone. See chapter 7 of the document “BankID
Relying Party Guidelines v2.x” at the page
http://www.bankid.com/rp/info/. In the table you will find information
about the test version of BankID Security App for Android, iOS and Win-dows 8.
To test signing on a PC, you need to download the latest BankID security program (BISP 5.x or higher) from https://install.bankid.com/. It is the same version of the BISP program that shall be used in both test and pro-duction. However, to use it in test you need to do some configurations on your PC. See chapter 7 of the document “BankID Relying Party Guidelines v2.x” at the page http://www.bankid.com/rp/info/. In the table you will find information about the test version of BankID Security Application for PCs (Windows and OS X). A CavaServerSelector.txt file has been added to the E-Signing document package.
Production
certificate These steps should be followed to retrieve a certificate:
- Merchant: Fill in the needed information in chapter 6.4 in the “Nets
Signing and Identification Services Technical configuration form”.
This is information that Nets will be using when generating a certif-icate request (*.p10 file) on behalf of the customer. Send in the complete form or an updated form to Nets Signing and Identifica-tion Services support [email protected].
- Nets: Based on the information in the above form, Nets will gener-ate a *.p10 file. When generating a *.p10 file the privgener-ate and pub-lic key pair is generated and stored safely at Nets. After generating the file, Nets will e-mail this to the Merchant.
- Merchant: E-mail the certificate request to your bank. The certifi-cate the merchant gets in return must be forwarded to support at
32 - 41
- Merchant: Please request the certificate chain / or the issuer certif-icates of the Merchant certificate from your bank. The entire certifi-cate chain must be sent to support at [email protected] and installed in E-Signing in order to verify a signature.
- Nets: Configures your Merchant site with support for BankID (Swe-den).
To support the use of Mobile BankID, the merchant certificate must include a display name. Most certificates issued after 31.12.2012 have been issued with this element.
Autostart and
SignerID in BankID BankID has two different clients. One client for PC and MAC, this is called “security program” and one for mobile devices (iOs, android, winPhone) called app.
All signing operations must first be initialized towards the BankID infra-structure. Hence, the client will after start-up connect to BankID infrastruc-ture to check if the user has any pending operation. There are two meth-ods of registering an operation in BankID, with or without SSN (Social Security Number/Person number). The differences between these two methods are how the client will be started. The client can be started with a reference or without. If you start the client with a reference the client will contact the BankID infrastructure and fetch the operation linked to this reference. If the client is not started with a reference the client will connect to the BankID infrastructure and check if there are any operations linked to the user’s SSN. In practice, these two different methods are used to start the client on the device the user has initialized the operation, or to start the client on another device (e.g. sitting on a PC, but wants to use BankID on the phone). If you want to start the client on another device the SSN must be used.
To realize the use of this functionality, the E-Signing service uses the the parameters “autostart” and the SignerID element in the InsertOrder (EndUserSigner-> AcceptedPKIs-> BankIDSE -> SignerID). Information about the “autostart” parameter may be found in the “Nets E-Signing
SignWeb integration guide” and information about the SignerID element is
found in “Nets TrustSignMessage interface description”.
The following rules applies when using the “autostart” parameter and the SignerID element:
Autostart SignerID Behaviour False
(default)
Null (default)
The user will be presented with a choice of using this device or another device (if another device is selected the end-user must provide the SSN). See BankID’s demo implementation of this page:
https://demo.bankid.com/nyademobanken/Logon.a spx
False xxxxxxx
33 - 41 client on another device.
The end-user will be presented a message; “Launch your BankID Security App.")”
The customer should give the end-user an option to either start the client on this device or on another device.
True Null
The client will be auto started on current device. The customer should give the end-user an option to either start the client on this device or on another device.
True xxxxxxx
The client will be auto started on current device. The customer should give the end-user an option to either start the client on this device or on another device, and it should send the appropriate autostart parameter.
Document formats The following document formats are supported using BankID (SE)
- PDF - Text Adding text to
BankID security app signing field
When signing a document using E-Signing and BankID SE, the document is shown prior to launching the BankID security app. In the BankID security app’s signing field a standard text has been added pointing to the previ-ously shown document. The customers can add extra text to the signing field in addition to the standard text. This is configurable at a merchant configuration level. The picture below shows how the addition of text will be shown.
34 - 41 To add a customized text to the field, you will need to do the following:
- Insert text into the “Description” element in the InsertOrder -> Documents -> Document -> Presentation
- Request support at [email protected] to update your mer-chant configuration to allow this usage.
Note: The text added to the “Description” element is also shown in the header if using Nets “Normal GUI” (standard) and it is added to the SDO. Not supported
functionality The following functionality is currently not supported for this eID:
- The MergeSDO message in TrustSignMessage
- Multi-signature in combination with the Norwegian BankID on mo-bile phones.
35 - 41
Known issue With the Mobile BankID app it is not always possible to detect if the app is
installed on the device used for signing.
When the app is closing, E-Signing tries to redirect the user back to the browser. However, it is not guaranteed that the user is redirected back to the same browser as the one that started the session. The merchant im-plementation must support that the end user are redirected back in a new web browser, eg cookies cannot be used.
NemID – personal (POCES) and employee (MOCES) certificates (DK)
Information NemID with both personal (POCES) and employee (MOCES) certificates are
supported through the E-Signing service. Information about these eID’s can be found at NemID’s webpages:
-
http://www.nets.eu/dk-da/Produkter/Sikkerhed/NemID-tjenesteudbyder/Pages/default.aspx
-
http://www.nets.eu/dk-da/Produkter/Sikkerhed/medarbejdersignatur/Pages/default.aspx The NemID eID are offering two different clients for End users. One is the JS client and the other is the OpenSign applet. The JS client offers the pos-sibility to sign with either personal (POCES) or employee (MOCES) certifi-cates. The OpenSign applet is used for signing with employee certificates only.
If the End user shall be presented with a list of possible eID’s to sign a document with, it is recommended to use the following description in “”:
- “NemID med nøglekort” (the JS client) - “NemID med nøglefil” (the OpenSign applet)
To be able to offer document signing with NemID (Personal cate/POCES) and/or NemID Medarbejdersignatur ((Employee certifi-cate/MOCES), Nets need to configure your Merchant site with a NemID Virksomhedssignatur (organization certificate/ VOCES).
Note: E-Signing is not supporting “NemID erhverv til bank”. See infor-mation about this NemID product here: https://www.nemid.nu/dk-da/erhverv/nemid_til_erhverv/nemid_erhverv_til_bank/
36 - 41 the E-Signing service with NemID.
NemID VOCES
certificate All customers must order a new NemID VOCES (“virksomhedscertifikat”) certificate to be used with E-Signing in production. In test, you will be set up with a general test VOCES in your configuration.
Ordering a NemID Company certificate (called production-VOCES)
1. Order the production-VOCES from the link below. Note: The pro-duction-VOCES must be ordered by a company administrator at the NemID Self Service:
https://www.medarbejdersignatur.dk/produkter/nemid_medarbejdersignatur/log_ paa_nemid_selvbetjening/log_paa_med_noeglefil/index.html
a. Add [email protected] as the technical contact
person
2. When the production-VOCES is issued, an installation code will be shown. Please send this code to [email protected]
3. Fetch the UID by going to the “Administrér virksomhedssignatur” in the Meny at NemID Self Service.
a. If needed search for the VOCES you have ordered and note the UID, see the figure
37 - 41
PID/RID agreement4
Nets eSecurity support will fill out a PID/RID agreement on your behalf. 4. Support will send you the prepared agreement. Please verify the information and let an authorised officer sign it. Return the signed agreement to [email protected] as a scanned PDF. NemID production access (only applicable if customer already have a TU-agreement)
If you already have a TU-agreement( “tjenesteudbyder”), Nets eSecurity support will request production access for your new production-VOCES.
5. Nets eSecurity support will request a new Friendly name from you. Note: The Friendly name must be different from any of your other production-VOCES certificates.
NemID production access (if no TU-agreement is in place)
If you do not have a TU-agreement, Nets eSecurity support will fill out the agreement to be a service provider on behalf of the customer
6. Support will request some information from you and you will re-ceive information about the standard and general terms according to the TU-agreement. You will also receive a form to accept that support makes a TU-agreement on your behalf.
Test users NemID test users can be ordered here:
- https://appletk.danid.dk/testtools/ (username=oces,
pass-word=nemid4all). Fill in a fictive CPR, standard address, zip and city. Check for POCES Qualified and Standard OTP Device. More information can also be found in the document “Vejledning i brug af test tools”:
-
http://www.nets.eu/dk-da/Service/kundeservice/nemid-tu/tjenesteudbyderpakkeJS/Pages/default.aspx
NemID JS client
and CSS styling The NemID JS client can either be shown in a standard or in a limited mode. Standard mode is the default mode and includes administration possibilities for the user. The mode is controlled using the
“nemid_clientmode” parameter. In E-Signing this is appended to the
4 NemID offers a PID/RID cpr-service that can match a user’s PID/RID with a CPR number. Info about PID/RID can be found here: http://www.nets.eu/dk-
38 - 41 ingURL. “nemid_clientmode=limited” will change the mode to limited.
The minimum recommended IFRAME sizes are:
- Standard mode: 500 x 450 (minimum width x heights sizes respec-tively)
- Limited mode: 250 x 200 (minimum width x heights sizes respec-tively) (landscape) or 200x250 (minimum height x width sizes re-spectively) (portrait)
- Note: Customers using the signing deadline and/or signers table in E-Signing may need to use a slightly higher IFRAME size than the recommended sizes.
CSS file adjustment
The NemID JS client must be styled with CSS to display properly. The de-fault styling has a CSS rule that sets the proper sizes. If you override styl-ing, your style sheet must be updated for the new NemID client. Styling can be overridden by sending a style URL in the WebContext element in the InsertOrder request.
The default CSS styling sets width to 100% and height to 75%. The client will expand to fill the container (iframe), but leave some space below the client for signing deadline text and status table. If an status table is dis-played, the height can be increased.
When overriding styling, the sample CSS below will produce the same ef-fect as the default styling.
#nemid_index_html { height: 100%; }
#nemid_index_html .iframe, #nemid_index_html .iframe .ipage,
#nemid_index_html .iframe .ipage .main { height: 100%; } .nemid_client { height: 75%; min-width: 500px; min-height: 450px; } .nemid_client.limited { min-width: 250px; min-height: 250px;
39 - 41 } #nemid_iframe { width: 100%; height: 100%; }
Document formats The following document formats are supported using NemID (DK)
- PDF - Text
Not supported
functionality The following functionality is currently not supported for this eID:
- The MergeSDO message in TrustSignMessage
PDF validation NemID has a whitelist of PDF versions it supports. The E-Signing service
uses the whitelists to validate PDF documents prior to accepting an Inser-tOrder request. There are currently two validation methods used. The one used depends on the NemID applet configured in your Merchant configura-tion.
NemID JS
For customers using only NemID JS, the “Sign Text validator tool” is used for validation. The tool may be found here:
http://www.nets.eu/dk-da/Service/kundeservice/nemid-tu/NemID-tjenesteudbyderpakken-okt-2014/Pages/default.aspx#tab4
NemID OpenSign
For customers using NemID OpenSign, the “Sign validator” is used. The tool may be found here:
http://www.nets.eu/dk-da/Service/kundeservice/nemid-tu/NemID-tjenesteudbyderpakken-for-Java-klienten/Pages/default.aspx#tab3 Note: If the customer has NemID JS client configured together with the NemID OpenSign applet, the “Sign Text validator tool” is used. An excep-tion to this is if the Merchant specifies only NemID OpenSign in the “Inser-tOrder” request, then the “Sign validator” is used.
NemID youth
certificates A NemID youth certificate is issued to people in the age between 15-18 years. Users above 18 years with a youth certificate can enforce renewal to a certificate without the youth indication. This is done in the self-service on
https://www.nemid.nu/dk-da/. A youth certificate is valid for 3 years, and
40 - 41 a valid youth certificate.
The E-Signing services are allowing signing using NemID youth certificates. To avoid accepting signatures used with youth certificates, you can do the following:
1. Checking the CPR number if you have access to that prior to initiat-ing a signinitiat-ing order to E-Signinitiat-ing.
2. Checking the certificate used to sign a document prior to accepting the signature. This can be done by following these steps:
a. After a document has been signed, the signed document can be fetched from the E-Signing service using the “GetSDO” XML message.
b. The SDO can be un-packed using the “GetSDODetails” XML message. In the response from the E-Signing service you will find the certificate used to sign a document. It is stated in the “DN” (Distinguished Name) field of the certifi-cate that the certificertifi-cate is a youth certificertifi-cate. If you mean that it is not ok to sign a document using a youth certifi-cate, you can choose not to accept the signature. See page 9 in this document for information about youth certificates:
i.
http://www.nets.eu/dk-
da/Service/kundeservice/nemid-tu/tjenesteudbyderpakkeJS/Documents/Specifikatio
nsdokument%20for%20OCSP.pdf
SSN (CPR) in SDO The signer’s SSN (CPR) may be added to the SDO to connect a signer’s
signature with the signer’s SSN. To add the SSN to the SDO, the following prerequisites exists:
- The SSN (CPR) must be added to the <SignerID> element in the InsertOrder message for this particular signer. When the SSN is added to this element, a CPR match towards NemID will be done after the signing is completed. See the «TrustSignMessage interface description» on how to add the <SignerID> element. - This function must be activated in your E-Signing configuration at
Nets. To activate the function, either e-mail support with your MerchantID and a request for this function (for existing customers) or mark the "Activate "CPR in SDO"" field in the Technical
configuration form.
If all prerequisites are in place, the following elements will be added to the SDO:
41 - 41 <ds:SignatureProperty Target="signature">
<openoces:Name>cpr</openoces:Name> <openoces:Value Encoding="xml" VisibleToSign-er="no">1234561234</openoces:Value> </ds:SignatureProperty>
Pseudonym in
NemID certificates According to the OCES certificate policy, the End user has a possibility to
use a pseudonym instead of its own name in the NemID certificate (name protection). If the End user does not want to show his or hers name in the NemID certificate, the pseudonym “Pseudonym” is chosen for him or her. See the chapter 6.1 in this document for more information:
-
http://www.nets.eu/dk-da/Service/kundeservice/nemid-tu/tjenesteudbyderpakkeJS/Documents/Specifikationsdokument%2 0for%20OCSP.pdf
Name is rarely unique and may be changed over time. The name can therefore only be used as an indication. In a NemID personal certificate, the PID is the unique identifier. The PID can be matched to the CPR using a PID/CPR register. More information about the PID/CPR register is found here:
-
http://www.nets.eu/dk-da/Produkter/Sikkerhed/NemID- tjenesteudbyder/supplerende-produkter/PID-RID-cpr-tjenester/Pages/Muligheder-med-PID-RID-cpr-tjenester.aspx The E-Signing service uses the PID/CPR register to match the PID with the CPR in this way:
1. The Merchant adds the CPR number to the Signing order. 2. A person signs the document. This is not necessarily the person
with this CPR (exception from this is if the “Identification before signing” function is used. See the “Nets Functional description” for information).
3. After the signing is complete, E-Signing retrieves the PID from the certificate and the CPR from the Signing order, and sends a match-ing request to the PID/CPR register. If this is a match, the signa-ture is ok, if not, the signing process is still seen as unsigned. If the CPR no is not known before creating the Signing order, E-Ident can as an example be used to retrieve information about the End user. The End user is identified through E-Ident, and in a page after the NemID applet, the CPR is retrieved from the End user. The CPR from the End user and the PID from the certificate used for identification is sent to the PID/CPR regis-ter to be matched. The CPR is returned in the E-Ident SAML artifact.
