Guide. - How to setup secure communication for REST services in Automatisk kortbetaling. Revision 1.3. Nets A/S. Lautrupbjerg 10.

Transcription

1 Guide - How to setup secure communication for REST services in Automatisk kortbetaling Revision 1.3 Nets A/S Lautrupbjerg Ballerup DK T F

2 Table of Contents 1. Introduction Overview of security solution Going into production and test Prerequisites Introduction to certificates Public / Private key Certificate Root certificate SSL authentication One-way SSL authentication Two-way SSL authentication OCES standard Functional signature Setting up security Obtaining a digital certificate Sending certificate information to Nets Verifying the digital certificate Integration in your own IT systems SSL direct in application SSL termination in network infrastructure Appendix A Step-by-step guide to retrieving FOCES information Appendix B Step-by-step guide to verifying the FOCES Signature P. 2-16

3 1. Introduction Nets provides the service Automatisk Kortbetaling that allows customers to easily sign up for automated repeat payments. As part of Automatisk Kortbetaling Nets also provide a series of back office services to allow direct integration with the creditor s IT system. These services allow you to retrieve and edit information about your customers. This document describes how to setup security in order to use the back office services in a secure fashion. The target audience for this document is the technical staff in the creditor s IT department. It is assumed the reader has understanding of computer networks and concepts. 2. Overview of security solution In order to communicate securely with Nets services it is necessary to send and receive all communication over a secure channel. This is handled via a SSL connection, which is also widely used on the Internet. When you visit your netbank it utilizes the same technology. This type of connection is also commonly referred to as a TLS or HTTPS connection. In order to use a SSL connection it is necessary to obtain a digital certificate, which identifies you as a creditor. This is described in detail in the following sections. P. 3-16

4 There are four steps in setting up the security: 1) Obtain a digital certificate 2) Send certificate information to Nets 3) Verify the digital certificate can communicate securely with Nets server. 4) Integrate the digital certificate in your own IT systems. Section 3 contains a brief introduction to certificates. If you are familiar with certificates and public/private keys this section can be skipped. Section 4 contains the details about how to setup the security. Each of the steps in the list above is described in a separate subsection. 2.1 Going into production and test Before putting a payment solution on-line it is important to verify everythings works as expected. A go-live plan will typically contain these high-level elements: 1) Deploy solution in test envrinroment 2) Test solution and verify certificates, etc. works correctly 3) Deploy solution to production environment Security will need to configured for both the test environment and the production environment. This means details about the security setup in section 4, will need to be applied for two environments. Normally same digital certificate are configured in is used for both test and production environment. If desired, Nets have the possibility of configuring two separate certificates for test and production. This will require you to acquire two separate funktionssignaturer (more details about signatures below). P. 4-16

5 2.2 Prerequisites Before starting the setup procedure it may be useful to evaluate if the right resources are available. The security setup may require people from several IT departments, e.g. network, security and applications. Based on the information in this document it may be beneficial to assess your internal IT systems being integrated with the Nets services, and identify potential technical gaps. Nets have no knowledge of your network infrastructure or your IT systems. Therefore it is important to have the right technical resources available with internal knowledge about your company s IT systems. 3. Introduction to certificates The following section is a brief introduction to some of the key terms used when dealing with certificates. If you need further information we encourage you to purchase one of the numerous books written covering this topic. 3.1 Public / Private key The foundation for much of the encryption used on the Internet today is asymmetric encryption. Functionally this involves a key with two parts: A public key that can/should be shared A private key that must be kept secret When content is encrypted using the private key the public key can decrypt it. Vice versa if content is encrypted using the public key the private key can decrypt it. Given a user s public key it allows you to encrypt content and send secretly to the recipient. Only the user (with possession of the private key) can decrypt it. P. 5-16

6 3.2 Certificate Just having a public key does not tell anything about the identity of the owner. To solve this issue one normally uses certificates. A certificate binds a public key with a given user/identity. The Certificate Authority is a trusted 3 rd party responsibly for issuing the certificate. They guarantee certain requirements are met so no fraudulent certificates are issued. A certificate contains the following information The user s public key Identity of the user (e.g. a name and/or CVR number) Information about the Certificate Authority certifying the information above 3.3 Root certificate One key question from certificates is: how do we know a given Certificate Authority issued a certificate? For this purpose there is a special type of certificates called Root Certificates. Each Certificate Authority has a special root certificate identifying itself. Each certificate contains a chain-of-trust that ultimately ends with the root certificate. By trusting one root certificate you can verify a given Certificate Authority in fact issued all descendent certificates. 3.4 SSL authentication The use of SSL (TLS) is prevalent on the Internet especially for e-commerce or e-banking purposes. But normally one-way authentication is used. For the Nets services two-way SSL authentication is used. The difference is explained in the following subsections. P. 6-16

7 3.4.1 One-way SSL authentication Normally when you visit an e-commerce site you perform a one-way SSL authentication. The website have a certificate that enables you to verify you in fact have reached the correct e-commerce site. But you as a customer do not have a certificate and the e-commerce website cannot verify who you are from the SSL connection Two-way SSL authentication In a two-way SSL authentication both parties have a certificate. In the negotiation of the SSL connection the certificates are exchanged. Using the previous example this would still allow the customer to verify he has reached the correct e-commerce site as before. But additionally the two-way authentication allows the e-commerce site to verify the identity of the customer. For the Nets back office services a two-way SSL connection is used. This allows both parties to be identified. 3.5 OCES standard OCES is an abbreviation for Offentlige Certifikater til Elektronisk service. It is a standard developed by the Danish public authorities. There are a lot of different technical variations and possibilities when constructing public/private keys and certificates. The OCES standard creates a common set of technical requirements. The formalized requirements create a standardized environment, which minimizes risks of interoperability issues. The Certificate Authority for issuing OCES certificates is Nets DanID, acting on behalf of the Danish public authorities. Technically, OCES is based on the X.509 standard. The current root CA is identified as TRUST2408 OCES Primary CA and uses a 4096 bit public key. P. 7-16

8 3.6 Functional signature Several use cases exist for the use of certificates. They can be used to identify individual citizens, employess and companies. A functional signature (in Danish funktionscertifikat) is a company signature used for one specific purpose. A company can have as many functional signatures as desired. The functional signature can also be referred to as a FOCES certifcate. While one general company certificate would function equally well, it may not be as practical. If the same certificate is used in e.g. 50 different IT systems, it may require substantial effort to coordinate a renewal of the certificate. The functional signature solves this problem by having a new separate signature issued for each specific system/purpose. 4. Setting up security 4.1 Obtaining a digital certificate To setup the secure communication with Nets you need a Funktionssignatur. The funktionssignatur is issued by a subsidiary of Nets called Nets DanID. You order the signature by using the Nets DanID self-service website. To login to the self-service website you will need to have a working NemID medarbejdersignatur. You may already have an account as the Danish tax authorities require a medarbejdersignatur when companies report tax information. If you do not already have a NemID medarbejdersignatur, you can order one here: Once you have the credentials for the NemID medarbejdersignatur, you can order the funktionssignatur by clicking Bestil on the following web page: P. 8-16

9 Note the funktionssignatur have an expiration date. Make sure to renew the certificate (and send the updated information to Nets) before the certificate expires. There is a fee for issuing and renewing certificates. Pricing information can be found here: Sending certificate information to Nets Once you have obtained a funktionssignatur you need to send some information from the certificate to Nets. This is necessary in order for Nets to link your company with the funktionssignatur. Nets require the following information from the funktionssignatur: CN (Common Name) Fingerprint Serial Number Also, we will need a contact for the person (or group) we should contact in case of any questions. If you need help in how to obtain this information from the certificate see appendix A. Here is a step-by-step walk-through with screenshots on how to get the information. The information should be sent to the following address: Paymentsservices-a-dk@nets.eu You will receive a confirmation once the signature information have been linked to your account. 4.3 Verifying the digital certificate The next step is to verify the digitial certificate to ensure everything works as expected. Please wait for a confirmation mail from Nets confirming the signature has been configured on our side before proceeding. P. 9-16

10 This step uses the funktionssignatur in a standard browser to verify the secure communication between Nets and your computer. Import the certificate on your machine and access the following link from a browser: ER (Replace PBSNUMMER with your own pbs number in the above link) Appendix B contains a detailed step-by-step description of the verification procedure. Since no mandates are created, you will receive http code 204 (no content) If you connect using a browser, the browser will appear to not show anything. Once this step is completed successfully you now have verified there is a secure communication channel between Nets and your network. Nobody will be able to eavesdrop or alter the information transferred over this secure channel. If you cannot get the connection to work please contact Nets customer service at Payments-services-a-dk@nets.eu 4.4 Integration in your own IT systems At this point we have established a secure communications channel between a computer/browser in your company network and Nets. The next step is to integrate the same certificate in your system so you can access the REST services programmatically. Note a separate document describes the semantics of the REST services provided. The scope of this document is only the security part of the solution. Nets have no knowledge of your network infrastructure or your IT systems. Therefore it is important to to have the right technical resources available with internal knowledge about your company s IT systems. The next two subsections present the most common integration patterns. P

11 4.4.1 SSL direct in application The most common approach is to import the certificate directly into the application. The application is then able to communicate directly with Nets server over a secure SSL connection. How to import the certificate into the application depends on the technology used in your application. Please refer to your internal system specialists for guidance. Note that the proper root certificate is also required. All FOCES certificates are issued by the TRUST 2408 root CA. If this root certificate is not already present it should be added SSL termination in network infrastructure In some network setups the SSL termination is not handled by the application itself but is instead handled by a separate component in the network. Several commercial appliances exist. Instead of the application communicating directly with Nets, the application communicates with the separate network component responsible for the SSL termination. The network component encapsulates the message with the proper SSL packaging and forwards to Nets server. And vice versa for the reply: the network component unwraps the SSL layer and forwards the message in clear text to the application. The application communicates with a local proxy in clear text on the internal company network. But the network component ensures the communication is properly secured when communicating over the Internet. P

12 5. Appendix A Step-by-step guide to retrieving FOCES information To obtain the information from the certificate follow these steps: 1. Import the signature to the pc by double-clicking on the.p12 file and following the steps in the import wizard 2. Then create a command line prompt (Windows key + R) and enter certmgr.msc and press enter. This should start the windows certificate manager as shown below. 3. Find the signature under personal->certificates 4. Double click on Certificates P

13 5. Select Details and find the fingerprint (referred to as thumbprint in Windows). 6. Then find Subject, which contains both SERIALNUMBER and common name (CN), P

14 P

15 6. Appendix B Step-by-step guide to verifying the FOCES Signature Once the signature has been registred at Nets you can verify the connection in an ordinary Internet browser. First, import the signature to your computer as described in the previous appendix. Then open a browser (Internet Explorer) and go to the following link: ER (replace PBSNUMMER with your own pbs number in the above link) This link is part of the REST service interface and is normally used for machine machine integration. The call will normally return a list of active agreements in a machine-readable JSON format. In case no agreements have been created the service will return a status code 404 (Page Not Found). When the browser connects to the URL above it will recognize a certificate is needed and will suggest a list of suitable certificates. Here is a screenshot from Internet Explorer: P

16 If more than one signature is presented you can identify the correct one by looking for the name ending with (funktionssignatur). If the correct certificate is selected a connection is established. Internet Explorer may prompt you to save the JSON data. This file can be discarded afterwards. The important step is to verify the conncetion. If the connection does not succeed an Access Forbidden error message will be displayed. In this case please contact Nets customer service. P