Getting started (**Deprecated**)

1. Install Security Server and setup Trust Services:
   1. - AUTH Certificate for Security Server
   2. - SIGN Certificate for each Subsystem behind it
2. Connect Security Server with your information system (Adapter development (Java, .NET, PHP etc.))
3. Configure data access settings (in Security Server)
4. Exchange data with your business partners

Tips:

• You can install RoksNet Portal for your end-users (employees, customers, citizens etc.)
• You can use RoksNet Portal for your own service testing purposes

RoksNet utilizes the X-Road components for secure data transfer. The illustration below shows the main components and interfaces of the RoksNet.

Before setting up your Security Server, please provide the following information to us:

• Entity name
• Status (Goverment, Private Company, Non-Profit Organization)
• Organization unique registry code (if exists)
• Country and official Address
• Name of the person, who represents the organization in RoksNet
• Representative identifier/unique personal ID code (if exists)

The fields in bold text are required. Please send the following information to support@roksnet.com and we'll send you a 8-digit Member/User Code, that will be needed later to RoksNet setup process.

REQUIREMENTS FOR THE SECURITY SERVER

Minimum recommended hardware parameters:

• the server’s hardware (motherboard, CPU, network interface cards, storage system) must be supported by Ubuntu 14.04 in general;
• a 64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended;
• 2 GB RAM;
• a 100 Mbps network interface card;
• if necessary, interfaces for the use of hardware tokens.

Requirements to software and settings:

• an installed and configured Ubuntu 14.04 LTS x86-64 operating system (VMs are supported as long as they support Ubuntu 14.04 LTS);
• a static ip address should be configured;
• The enabling of auxiliary services which are necessary for the functioning and management of the operating system (such as DNS, NTP, and SSH) stay outside the scope of this guide.

PREPARING THE OS

1. Add system user whom all roles in the user interface are granted to:

sudo adduser username

2. Set operating system locale. Add the following line to /etc/environment:

LC_ALL=en_US.UTF-8

INSTALLATION

3. Add the address of the X-Road package repository and the nginx repository to to /etc/apt/sources.list.d/xroad.list:

deb http://x-road.eu/packages trusty main
deb http://ppa.launchpad.net/nginx/stable/ubuntu trusty main
deb http://ppa.launchpad.net/openjdk-r/ppa/ubuntu trusty main

4. Add X-Road's repository's signing key to the list of trusted keys:

curl http://x-road.eu/packages/xroad_repo.gpg | sudo apt-key add -

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 00A6F0A3C300EE8C

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys EB9B1D8886F44E2A

5. Install the security server software:

sudo apt-get update

sudo apt-get install openjdk-8-jre-headless

sudo apt-get install xroad-securityserver

6. During the installation you will be asked to specify the username (added at step 1.) that will be granted the rights to perform all activities in the user interface.

7. The other questions can be answered with their default values as they are detected from the OS.

POST INSTALLATION CHECKS

8. Check if all the processes started. The following services should be running.

sudo initctl list | grep "^xroad-"
xroad-jetty start/running, process 19796
xroad-confclient start/running, process 19563
xroad-signer start/running, process 19393
xroad-proxy start/running, process 19580

9. Ensure that the Security Server user interface at https://SECURITYSERVER:4000/ can be opened in a web browser. To log in, use the account name chosen during the installation. While the user interface is still starting up, the web browser may display the “502 Bad Gateway” error.

1. To perform the initial configuration, open the address https://SECURITYSERVER:4000/ in a web browser. To log in, use the account name chosen during the installation.

2. The system will ask for a global configuration anchor file. RoksNet's development environment's anchor can be downloaded from http://apt.roksnet.com/xroad6-debs/configuration_anchor.xml. The hash value for verification is

Hash (SHA-224): 71:3B:88:8C:6B:59:73:29:57:D2:06:8D:BE:A0:FF:F4:E4:E8:E1:D9:3A:A6:8A:75:E3:02:E7:FB

3. If the configuration is successfully downloaded, the system asks for the following information:

• The security server owner’s member class (COM for private sector business, GOV for governmental organization and NGO for non-profit organization)
• The security server owner’s Member/User code (this should be your organization's registry code)
  • NB! Please enter an 8-digit Member/User code you got from RoksNet support. If you do not have one, please contact support@roksnet.com to get your code. More information at section important
• Security server code (free form, security server code should be unique per member).
• Software token’s PIN (free form - the PIN will be used to protect the keys stored in the software token. The PIN must be stored in a secure place, because it will be no longer possible to use or recover the private keys in the token once the PIN has been lost)

Example (values in the picture are for demostration purposes):

4. The system will prompt a warning. This is fine, as we'll register the member status later.

5. Enter softtoken PIN in the Keys and Certificates view (chosen in step 3.)

6. Add a TSA in System Parameters view

7. Generate keys and certificate requests in the Keys and Certificates view

Security Servers use 2 types of certificates

• AUTH certificates for authentication between security servers when initiating a secure TLS channel. AUTH certificates are used 1 per security server.
• SIGN certificates for e-Stamps. SIGN certificates are used 1 per Member/User (i.e. organization).

Generate 2 keys by selecting the SoftToken-0 and press GENERATE KEY. Give the key a label and press OK. Your keys should now look similar to this:

Next, generate a CSR for a SIGN certificate by choosing a key and selecting GENERATE CSR. Make sure the Usage: SIGN is selected. If the Common Name (CN) field is empty, please use the Member/User Name in that field.

Then generate a CSR for an AUTH certificate. Make sure the Usage: AUTH is selected. If the Common Name (CN) field is empty, please use the Member/User Name in that field.

Send the downloaded CSR-s to us at support@roksnet.com with the following details:

• Member/User name
• Member/User code
• Member/User class
• Security server code

We will use the CSR-s to issue you certificates.

Once you have received the certificates you should be able to import them in the “Keys and Certificates” view. After importing them, select the AUTH certificate and press “ACTIVATE” and “REGISTER”. Your keys and certificates should now look like this:

Once we have accepted the registration request in the RoksNet User Registry, the OCSP response and status of the AUTH certificate will change to “good, registered”.

The next step would be registering a Subsystem. Select “ADD CLIENT” in the Security Server Clients view.

Select “CONFIRM” in the next prompt.

Once we have accepted the registration request in the RoksNet User Registry, you'll be ready to Consume or Provide User Content Services on RoksNet's Development Environment.

RoksNet Portal is a universal client application that's easy to set up and makes it easy to consume Content Services without the need to develop one's own information system. It's also a good developers tool, as it makes testing your services easy.

Requirements to software and settings:

• an installed and configured Ubuntu 14.04 LTS x86-64 operating system (VMs are supported as long as they support Ubuntu 14.04 LTS) NB! Needs a separate Ubuntu 14.04 LTS server - will not work if installed alongside the Security Server;
• a static ip address should be configured.
• the enabling of auxiliary services which are necessary for the functioning and management of the operating system (such as DNS, NTP, and SSH) stay outside the scope of this guide.

1. All activities during installation are performed as root user, so

sudo -i

2. Configure RoksNet Portal and JDK-8 repositories. To do that, add the following lines to /etc/apt/sources.list.d/roksnet-portal.list

deb [arch=amd64] http://apt.roksnet.com/roksnet-portal trusty main
deb http://ppa.launchpad.net/openjdk-r/ppa/ubuntu trusty main 

3. Download signing key for JDK-8

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys EB9B1D8886F44E2A

4. Update package lists

apt-get update

Ignore the following error for now:

W: GPG error: http://www.aktors.ee trusty Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 671B319BE775D097

5. Install RoksNet Portal keyring

Install roksnet-keyring package:

apt-get install roksnet-keyring

When asked, choose “y” as an answer:

Install these packages without verification [y/N]?

Update the package lists again:

apt-get update

6. Install postgreSQL

For ubuntu 16.04 LTS

vi /etc/apt/sources.list.d/pgdg.list

add line:

deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main

Add key

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

apt-get update
apt-get install postgresql-9.3

For ubuntu 14.04 LTS

apt-get install postgresql-9.3

7. Edit the file /etc/postgresql/9.3/main/pg_hba.conf so that postgres user's authenticaton method would be “trust”. It should look like this:

# Database administrative login by Unix domain socket
local   all             postgres                                trust

8. Restart PostgreSQL

service postgresql restart

9. Install RoksNet Portal database package

apt-get install roksnet-postgresql

For testing purposes questions prompted during installation can be answered with default values.

10. Install Java JDK 8

apt-get install openjdk-8-jdk

11. Add JAVA_HOME variable

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

12. Install RoksNet Portal application

apt-get install roksnet-application

Quite a few questions will be asked during this installation.

• Please provide database host IP to be used - default answer
• Please provide database port to be used - default answer
• Please provide database name to be used - default answer
• Please provide username to be communicating with database - default answer
• Please enter username password - enter password chosen at step 9
• Please provide SMTP host address - answer default, won't be using for testing purposes
• Please provide server email address - answer default
• Do you want to add new administrator account - answer “y”
• Do you want to enable HTTPS connection between RoksNet Portal application and security server? - answer “n”

13. Edit the file /var/lib/tomcat7/webapps/ROOT/WEB-INF/classes/config.cfg with the following content:

You can change the country code:

#If no suitable countries are defined, then uses system default locale country
countries = [ISO code of your country, e.g. "GB"]

14. Edit /etc/apache2/sites-available/ssl.conf with your IP aadress to gain access to the admin interface. It should look like this:

    <Location "/*/admin/*">
        Order deny,allow
        Deny from all
        Allow from 127.0.0.1 192.168.1.90
    </Location>

15. Restart apache2.

service apache2 restart

1. You should now be able to log into RoksNet Portals's admin interface at https://server_ip/admin. Use the administrator account you created during installation to log in.

2. When logged in, under Portal management, select “Add new”

3. Fill out the forms with the following information:

• Portal name (EN) - free form
• Portal short name - system name, free form
• Portal type - Organizations portal
• Organization name (EN) - Name of your organization
• Organization code (RoksNet User Code) - User/Member Code (must match User/Member Code in Security Server)
• Data protocol version - 4.0
• RoksNet instance - roksnet-dev
• RoksNet member class - Your Member/User class (must match Member/User class in Security Server)
• RoksNet subsystem code - Your Subsystem Code (must match Subsystem Code in Security Server)
• Security host - http://security_server_ip
• Services sending address - http://security_server_ip
• Debug mode - off
• Send audit log to security server - unchecked
• Use topics - unchecked

After filling out the forms, hit “Save portal configuration”.

4. Select “Add new manager”.

5. Fill out the forms and hit “Add new person as manager”. For password authentication, check the “change password” checkbox to see the new password fields.

6. Choose “Exit” at upper right corner.

7. Log in with the user you just created at https://server_ip/

The username must be enter as [countrycode+serialnumber].

8. Select “All producers” → “Refresh producers”, check the following boxes and hit “Save active producers”.

9. Select a producer, hit Refresh services → From security server (allowed).

This will send a metaquery from RoksNet Portal to your Security Server, which will proxy it the the Producer's Security Server. As a response, the Producer's Security Server will send a list of allowed methods for your Subsystem.

10. Check all Services and hit Refresh XForms descriptions of selected Services → Generate from Security Server.

This will generate XForms based on the services WSDL-s.

11. Hit the play button on a Service to test it.

You're now able to consume Content Services via RoksNet Portal :)

12. The following demo Content Services are available in RoksNet Development Environment:

• Population Registry
• Passport database
• Vehicle database
• Company database
• Prescription database

NB! In most of demo Content Services you can use % symbol as input parameter and you will receive a list of persons or companies. Take some person or company code from the list and use it in another demo queries. The successful result shows that you received a demo data from another RoksNet User.

RoksNet User Content Services are based on SOAP. Information about X-road specific requirements are in the following documents:

• Message Protocol v4.0 - http://x-road.eu/docs/x-road_message_protocol_v4.0.pdf
• Service Metadata Protocol - http://x-road.eu/docs/x-road_service_metadata_protocol.pdf

Source code of example: https://github.com/Roksnet/Python-adapter-example The example contains library and two examples. Installation instructions are in included in the package.

To create a new service in the SOAP server:

• create service implementation function (example: example_hello/hello/services/helloservice.py)
• import and register service implementation module (example: example_hello/hello/server.py)
• create service description WSDL (example: example_hello/hello/static/hello.wsdl)
• publish service in Security Server and grant access to clients

To create SOAP client:

• create X-road client class (corresponding to a service provider) with methods corresponding to services and start calling those methods (example: example_hello/hello/client.py)

GitHub link: https://github.com/vrk-kpa/xrd4j

All of the related documentation is on the GitHub page

Since the example is not created by Roksnet, we do not guarantee the operation of the example with the Roksnet Portal.

Tool and examples can be downloaded from http://xtee.codeplex.com/

How to use X-tee.NET tool

1. Get WSDL (if you plan to consume existing services) or write WSDL (if you plan to provide services).
2. Use generator to generate code based on WSDL.
3. Use generated code in your project to implement SOAP client or server.

Using generator

Execute the generator program Xtee.Gen.exe and fill the form with necessary data. User interface is in Estonian only. The fields in the form have following meaning:

• DTO-e väljund kataloog – output directory for generated DTO code
• Serialiseerijate väljund kataloog – output directory for generated serializers (you may use the same directory as for DTO)
• Vali wsdli asukoht – path to WSDL file to read
• Adapter name – name of the class which will be generated
• XroadObjectType, XroadInstance, MemberClass, MemberCode, SubsystemCode – attributes of the Roksnet User who provides Content Services
• Näita detailsemat logi – show detailed log
• Genereeri - generate

Fill the gaps and press button „Genereeri“. If generation is successful, you will get generated code in the output directories. Based on this code, you can create and compile a new class library for using in your project.

Implementation of SOAP client

Add generated class library, Xtee.Code.dll and log4net.dll into your application.

Write client code to consume the services:

using Calculator.Xroad.Eu;
using Xtee.XteeClient.Calc;
namespace Client
{
    class Program
    {
        static void Main(string[] args)
        {
            var client = new CalcAdapter();
            // ID of authenticated end user
            client.XteeCommand.Configuration.UserId = "EE30101010007";
            // call the service
            decimal result = client.Add(new Variables(3, 4)).Result.Value;
            Console.WriteLine(result); 
        }
    }
}

This code creates a SOAP client instance using the class name which was entered into the generator. Each call must include actual user ID who has been authenticated by your application. Finally, we will call the service – in this example, service name is Add and it’s parameters are numbers 3 and 4.

Add <xtee.configuration> element to the configuration file of you project:

<configSections>
    <section name="xtee.configuration"                   
             type="Xtee.Core.Client.Config.ClientConfigurationSection, Xtee.Core"/>
</configSections>
<xtee.configuration proxyURL="http://my_security_server/cgi-bin/consumer_proxy"
      xRoadInstance="roksnet-dev"
      memberClass="COM"
      memberCode="12998179"
      subSystemCode="roksnet-consumer"
      objectType="SERVICE">
    <xteeTypeAssemblies>
      <clear/>
      <add assemblyName="Name_of_generated_DTO_DLL"/>
      <add assemblyName="Name_of_generated_serializers_DLL"/>
    </xteeTypeAssemblies>
</xtee.configuration>

Replace attributes of <xtee.configuration> with your own data (according to the certificate issued to your security server). Possible attributes are:

• proxyURL - SOAP server URL (typically in your security server unless you want to test your local SOAP server)
• storeMessages - (true/false) whether to save message log (default: false)
• storagePath - path to save messages, may be relative to app or absolute
• timeout - timeout of service call in milliseconds (default: 100000 (1 minute 40 seconds))
• objectType - attribute of the client element of message
• xRoadInstance - instance which you have joined
• memberClass - value from your certificate
• memberCode - value from your certificate
• subSystemCode - value from your certificate
• userId - default value for user ID
• issue - default value for issue
• message-path-format - message log filename format
• temporaryStoragePath - optional path for saving attachments (if not provided, storagePath will be used). If value is :inmemory: then attachments will be handled in memory only

Attribute values may be set within the client code as well.

Implementation of SOAP server

Add generated class library, Xtee.Code.dll and log4net.dll into your application.

To provide a service, create service class, inheriting it from the generated interface of the service, and implement ProcessRequest method:

namespace Server.Services
{ 
    public class ServiceMultiply : MultiplyServiceHandler
    {
        public MultiplyResponse ProcessRequest(MultiplyRequest input, MultiplyInputHeader header)
        {
            return new MultiplyResponse(input.Request, new Result(input.Request.VarX * input.Request.VarY));
        }
    }
}

The configuration file of your application must include <adapter.configuration> element:

<configSections>
    <section name="adapter.configuration" type="Xtee.Core.Adapter.Service.Config.AdapterServiceConfigurationSection, Xtee.Core"/>
</configSections>
<adapter.configuration storagePath="stored_messages" storeMessages="true">
    <services>
      <clear/>
      <!—- Bind each service to the handler class which will serve it -->
      <add objectType="SERVICE" xRoadInstance="roksnet-dev" memberClass="COM" memberCode="12998179" subSystemCode="Calc" serviceCode="Add" version="v1" servicehandler="Server.Services.ServiceAdd,Server"/>
    </services>
    <xteeTypeAssemblies>
      <clear/>
              <add assemblyName="Name_of_generated_DTO_DLL"/>
      <add assemblyName="Name_of_generated_serializers_DLL"/>
    </xteeTypeAssemblies>
</adapter.configuration>

Replace attributes of <adapter.configuration> with your own data (according to the certificate issued to your security server). Possible attributes are:

• commandInterceptor - full name of the class which implements ICommandInterceptor and comma-separated name of DLL where the class can be found
• storeMessages - (true/false) whether to save message log (default: false)
• storagePath - path to save messages, may be relative to app or absolute
• message-path-format - message log filename format
• temporaryStoragePath - optional path for saving attachments (if not provided, storagePath will be used). If value is :inmemory: then attachments will be handled in memory only

Since the example is not created by Roksnet, we do not guarantee the operation of the example with the Roksnet Portal.