E-Signing Integration guide

Transcription

1 Nets Branch Norway Haavard Martinsens Vei 54 NO-0045 Oslo T Foretaksregisteret NO E-Signing Integration guide Version: 3.4 Date: p. 1-41

2 Contents 1. Introduction... 4 Purpose... 4 Document overview... 4 Intended audience... 4 Referenced documentation... 4 Terms and definitions... 5 Acronym... 5 Change log Integration process... 7 Overview... 7 Customer test configuration... 7 Production configuration... 8 Merchant data... 8 Merchant certificates... 8 Server certificates E-Signing integration Overview XML Interface integration Web services Signing XML messages TrustSignMessage Example message TrustNotificationMessage SignWeb Graphical User Interface GUI E-Signing environment URLs Networking Integration issues Time synchronization Restrictions Test users XML notifications Use GetSigning-Processes to check status KeyUtil Installation Installation prerequisites Installation KeyUtil Using KeyUtil Generate a key Import a certificate Appendix 2 eid providers Introduction eid links How to enable a new eid BankID (NO) Test certificate Production certificate BankID 2.0 (without Java) Document formats

3 Using the XML format BankID (NO) without OK-button in client BankID on mobile phones ( BankID på mobil ) (NO) Information Test certificate Production certificate Document format Pre-set mobile phone number and birthdate Limitations Buypass (NO) Information Document formats BankID (SE) Introduction Test certificate and clients Production certificate Autostart and SignerID in BankID Document formats Adding text to BankID security app signing field Not supported functionality Known issue NemID personal (POCES) and employee (MOCES) certificates (DK) Information NemID VOCES certificate Test users NemID JS client and CSS styling Document formats Not supported functionality PDF validation NemID youth certificates SSN (CPR) in SDO Pseudonym in NemID certificates

4 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-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 Merchant Document overview This document is divided into five chapters. The first chapter gives an introduction, 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 sequence 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 integrators and developers. Referenced documentation Document Nets E-Signing Functional Description Nets TrustSign- Message Interface Specification TrustSignMessage XML Schema Nets TrustNotificationMessage Interface Specification TrustNotification- Description A detailed description of the E-Signing service and all its functionality with reference to architecture and interfaces This document describes the XML messages in the TrustSignMessage communication protocol for accessing E-Signing. A schema defining the TrustSignmessage XML message structure. A detailed description of the E-Signing Notification service A schema defining the TrustNotificaton XML 4-41

5 Message XML Schema Nets Signing and Identification Services Technical Configuration form Nets E-Signing Merchant technical verification test XML Signature Syntax and Processing message structure The technical configuration form includes all necessary configuration details that are needed to enable Merchants in the customer test and production system. This document describes tests that must be completed before the merchant is enabled in the production system Terms and definitions Term Merchant Signer Description The business entity that owns a sign order The user to whom a sign order is directed. Equivalent to end user Acronym Acronym Description HTML HTTP HTTPS NTP PDF Hyper Text Markup Language Hyper Text Transfer Protocol Secure HTTP Network Time Protocol Portable Document Format PKCS#10 Certification request standard. See RFC PKI SDO SEID SDO Public Key Infrastructure Signed Data Object Samarbeidet om Elektronisk ID Detailed information about SEID SDO: SEID_Leveranse_3_v1.0.pdf SMS SSL SSN UTC Short Message System Secure Socket Layer Social Security Number Coordinated Universal Time UTF-8 A character encoding format of ISO (RFC 3629) XML extensible Markup Language 5-41

6 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 information about BankID certificates, removing old information regarding NemID OTP applet, adding information about CPR (SSN) from NemID in SDO and error corrections. 3.1 Corrected the IP address for TrustSignMessage (prod) on Extranet 3.2 Added information about how to use nemid_clientmode=limited and corrected the IP address for TrustSign- Message (prod) on Internet. 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 3.4 Corrected information about Nets on first page

7 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 implementation and testing purposes and the production 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 update 1. 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 configuration: Merchant test certificate from eid providers supported by E- Signing Completed Nets Signing and Identification Services Technical Configuration Form (all customer test fields must be completed) XML notification data (optional, see detailed description in the Networking section in chapter 3. A certificate request (*.p10 file) for signing and SSL client authentication (see detailed description in the Merchant certificates section). All configuration data should be sent to the support address, support.esecurity@nets.eu. After Nets configuration, the Merchant will receive the connection data (MerchantID and certificates). The Merchant may now use the customer test environment for development, 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. 1 Notifications are sent to addresses defined in the Notification regarding service operation field in the Nets Signing and Identification Services Technical Configuration Form 7-41

8 Production configuration The following data must be available for Nets before production configuration: 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 Networking section in chapter 3. A certificate request (*.p10 file) for signing and SSL client authentication (see detailed description in the Merchant certificates section). 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 Configuration 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 infrastructure (IP addresses etc.) Dates for desired customer test/production configuration 2 Merchant certificates Merchant certificates from selected eid providers must be ordered from the different eid provider and handed securely over to Nets. See the Appendix 2 eid providers in chapter 5 for more information about the different eid providers. The Merchant needs a certificate to access the E-Signing service. This cer- 2 It is recommended to schedule the production configuration date some days prior to the Merchants go-live date. 8-41

9 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 keys 3. The certificate can be generated using any key generation tool. Nets offer one tool, see chapter 4 for more information. The following 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 support.esecurity@nets.eu. 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: Production: 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 customer 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. 9-41

10 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 CERTIFICATE

11 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 component 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. The E-Signing Notification System: 11-41

12 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-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 retrieve and change existing orders. This is described in details in Nets TrustSignMessage Interface Specification

13 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 Merchant will be given upon configuration in the customer test and production environment respectively. Information about the XMLDSIG standard is found at W3C, A text description of the standard may be found at this link, See the Example message section below for an example of a signed message including both a XMLDSIG signature and a TrustSignmessage. 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 13-41

14 can use when implementing E-Signing. Mandatory XML messages to implement: InsertOrder: In this message it is defined what to sign (documents), 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 order-lifetime. GetSigningProcesses: This message fetches the URL for each signing process and it shows the status of each Signing process. Example message An example of a message to E-Signing is shown below: <?xml version="1.0" encoding="utf-8"?> <Signature xmlns=" <SignedInfo xmlns=" <CanonicalizationMethod Algorithm=" xmlns=" <SignatureMethod Algorithm=" xmlns=" <Reference URI="#object" xmlns=" <DigestMethod Algorithm=" xmlns=" <DigestValue xmlns=" Hw=</DigestValue> </Reference> </SignedInfo> <SignatureValue xmlns=" Jzcvw==</SignatureValue> <KeyInfo xmlns=" <X509Data xmlns=" <X509Certificate>...MgVo7GzAgIsZadVuemvYcs149r2jAzfP9Hzz8yrgxu4=</X509 Certificate> </X509Data> </KeyInfo> <Object Id="object" xmlns=" <TrustSignMessage xmlns=" xmlns:xsi=" <MerchantID>9999</MerchantID> <Time> T11:12:25+02:00</Time> <MessageID>1</ MessageID > <InsertOrder> <OrderID> </OrderID>

15 </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 TrustNotificationMessage Interface Specification and TrustNotificationMessage 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 SignWeb XML distribution order.signpreprod1.nets.eu/tsos /XmlGw signpreprod1.nets.eu /sign order.sign.nets.eu/tsos /XmlGw sign.nets.eu /sign

16 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) XML notification (production) TrustSignMessage (customer test) TrustSignMessage (production) SignWeb (customer test) SignWeb (production) Firewall openings (Banking Net) IP Address Port XML notification (customer test/ Prod) TrustSignMessage (customer test) TrustSignMessage (production) 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 authentication, SSL or client SSL, the merchant has to notify Nets and hand over the possible root certificates or keystore. For security reasons, keystore information must not be handed over in an open . 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 information. That is, the merchant can use any time zone he wants. If the time zone information is not included, UTC will be used as default

17 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 Use GetSigning- Processes to check status If the Merchant are using XML notifications from the E-Signing service (the TrustNotificationMessage XML), be aware that the E-Signing service expects 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 received within 5 seconds, the E-Signing service expects that something went wrong, and it will try to re-send the XML notification. 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 OrderID LocalSignerReference SigningProcessStatusFilter Description The Order you want to fetch the status from. The local reference to the signer. This is defined in the InsertOrder XML message If you only want to get Signing processes with a specific status (Values are : Active, Pending, Complete, CancelledByMerchant, Expired, RejectedBySigner) 17-41

18 The response: Highlights of some elements in the response: Parameter OrderStatus SigningProcessResult.Status SignURL Description Status on the Order. Status on the SigningProcess. If this status is set to Complete, the End user has signed the document and all verifications have passed. 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 exiturl the SigningProcessResult.Status will always be completed. But since this is a redirect through the End user s browser the Merchant should always 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 processing tasks have been performed (and no more signers on the Order) the Order status will be set to Complete

19 4. KeyUtil keyutil PKC#12 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 ultimately 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 temporary folder. 2. Extract package Extract package to destination folder. 3. Install Unlimited Strength Jurisdiction Policy Files Install JCE Unlimited Strength Crypto Policy Files under the used jvm

20 These files can be retrieved from: 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 pri

21 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 merchanta.p10 Example in dos: #.../keyutil keygen -dn "CN=Merchant A,O=Merchant A,C=NO" -pw password -keysize 2048 keyfile merchanta.key -p10file merchanta.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.p

22 5. Appendix 2 eid providers Introduction This appendix aims to list information regarding the different eid providers. 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) BankID on mobile phones ( BankID på mobil ) (NO) Buypass Smartcard (NO) BankID including Mobile BankID and Nordea e-legitimation (SE) NemID POCES (DK) NemID MOCES (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 information about the InsertOrder message and the AcceptedPKIs element, see the Nets TrustSignMessage XML interface specification. - 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 between the eid s configured on your merchant site. See the Nets E- Signing Signweb integration guide for more information about this parameter

23 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 support: support.esecurity@nets.eu, (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 support.esecurity@nets.eu. 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 togheter 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 support.esecurity@nets.eu, 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 receive 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 receive the certificate information. The certificate information shall be sent to Nets Signing and Identification Services in two different channels (e.g activation link in an and activation code by sms). If your bank requires a CoC (Certificate of Confirmation) before issuing the merchant certificate, please contact support. Nets Signing and Identification 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 Migration and getting started Migration to BankID 2.0 client from BankID Java applet: System Customer test What to do Migration of the customer s merchant site is done upon request to support.esecurity@nets.eu. Please supply us with your MerchantID / MID and the preferred time for migration. If BankID Java applet should be available after the configuration, please let us know. See the IE8 workaround for information 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 production. This will mainly be every Wednesday during day time. However the first will be Wednesday the 8th October 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 ( 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 following should however be considered: 1. The use of BankID 2.0 and Internet Explorer 8. It will not be possible 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 recommended 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 Migration to BankID 2.0 will impact graphical appearance and platform support. Nets strongly advices the customers to use the customer test facilities to test migrated systems before opening for 24-41

25 the production system. It is further adviced to test all document types used for signing for responsiveness with different mobile devices. 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 signing applet (confirmation page) will be as with the BankID Java applet, 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 window 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 determine 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 forcepkivendor 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 25-41

26 of BankID. Note: If you today are using the forcepkivendor parameter, your implementation 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. 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 displayed, the height can be increased. When overriding styling, the sample CSS below will produce the same effect 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; } 26-41

27 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 introduced 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 presentable HTML. So the merchant must provide two documents when they want an XML-document to be signed. <BankIDXML> </BankIDXML> <XML> ANSGKFLSDSF==</XML> <XSL> ANSGKFLSDSF==</XSL> 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 ISO So when providing the XML and XSL bytes, get the ISO (ISO-LATIN-1) bytes. The ISO bytes must be Base64- encoded. BankID (NO) without OKbutton in client It is possible to remove the last screen in the BankID client. This is a configuration 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 following: 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 27-41

28 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 presenting 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 expecting complete, have a look at the SigningProcessStatus in the same message. This should have been set to Complete. To update 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) OnSignProcess 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 certificate ( Brukerstedssertifikat ). When ordering the BankID merchant certificate 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: 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 (support@bankid.no) 28-41

29 to register the SIM-card in BankID preproduction. Production certificate Document format Pre-set mobile phone number and birthdate Limitations For issuance of a BankID merchant certificate, see the Production certificate 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. 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. 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 information. 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 encoded. - 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 document 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 Buypass (NO) Information Document formats Buypass merchant certificates must be ordered from Buypass Smartkort ( 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 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. The following document formats are supported using Buypass (NO) - PDF - Text 30-41

31 BankID (SE) Introduction To enable BankID (SE) in your Merchants application you need an agreement with a bank issuing BankID (SE). See for banks that issues BankID and general information about BankID. BankID (SE) is issuing End user certificates in different ways ( Bank- ID på kort, BankID på fil and Mobilt BankID 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äkerhetsapp must be downloaded from and a test certificate to the given phone. See chapter 7 of the document BankID Relying Party Guidelines v2.x at the page In the table you will find information about the test version of BankID Security App for Android, ios and Windows 8. To test signing on a PC, you need to download the latest BankID security program (BISP 5.x or higher) from It is the same version of the BISP program that shall be used in both test and production. 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 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 certificate request (*.p10 file) on behalf of the customer. Send in the complete form or an updated form to Nets Signing and Identification Services support support.esecurity@nets.eu. - Nets: Based on the information in the above form, Nets will generate a *.p10 file. When generating a *.p10 file the private and public key pair is generated and stored safely at Nets. After generating the file, Nets will this to the Merchant. - Merchant: the certificate request to your bank. The certificate the merchant gets in return must be forwarded to support at 31-41

32 - Merchant: Please request the certificate chain / or the issuer certificates of the Merchant certificate from your bank. The entire certificate chain must be sent to support at support.esecurity@nets.eu and installed in E-Signing in order to verify a signature. - Nets: Configures your Merchant site with support for BankID (Sweden). To support the use of Mobile BankID, the merchant certificate must include a display name. Most certificates issued after 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 infrastructure. Hence, the client will after start-up connect to BankID infrastructure to check if the user has any pending operation. There are two methods 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) False Null (default) xxxxxxx 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: spx This means that the end-user wants to start the 32-41