Top Banner
ElevenPaths [email protected] elevenpaths.com Latch 1.1 plugin installation and user guide for systems based on UNIX Version 7.1 – November 2016 ElevenPaths, radical and disruptive innovation in security solutions
16
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Page 1: Latch UNIX english

ElevenPaths [email protected] elevenpaths.com

Latch 1.1 plugin installation and user guide

for systems based on UNIX

Version 7.1 – November 2016

ElevenPaths, radical and disruptive innovation in security solutions

Page 2: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 2 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

TABLE OF CONTENT

1 Obtaining the Latch plugin .......................................................................................... 3

1.1 Introduction .............................................................................................................................. 3

1.2 Prerequisites ............................................................................................................................. 3

1.3 Obtaining application ID ........................................................................................................... 3

1.4 Downloading the plugin............................................................................................................ 6

2 Installing the plugin..................................................................................................... 8

2.1 Changing the PAM setup of the service requiring protection .................................................. 8

2.2 Setting up SSH to use the plugin............................................................................................... 9

2.2.1 Public/private key protection ................................................................................................... 10

2.2.2 SELinux (Fedora/CentOs) setup ................................................................................................ 10

2.3 Setting up OpenVPN to use the plugin ................................................................................... 10

2.4 Uninstalling the plugin ............................................................................................................ 10

3 Use of the Latch plugin by end users........................................................................... 12

3.1 Pairing a user .......................................................................................................................... 12

3.2 Unpairing a user ...................................................................................................................... 14

4 Resources .................................................................................................................. 15

Page 3: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 3 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

1 Obtaining the Latch plugin

1.1 Introduction

This guide will show you how to install and set up the Latch 1.1 plugin in UNIX-based operating systems (Ubuntu, Debian, CentOs,…), as well as in the various services available for these systems.

Plugin installation is generic; in other words, it is installed the same way, regardless of the operating system in question. Once the plugin is installed, instructions are given to set up SSH and OpenVPN for use. These instructions are optional and only of interest for administrators that have integrated them.

The plugin is prepared to protect all of the services that use PAM authentication. The plugin includes an "Examples" directory that contains examples of the most common services (login, sudo, ssh, etc.).

When installing on an OpenBSD operating system, only the “latch_ssh_command” feature of the plugin can be used.

1.2 Prerequisites

• Using a UNIX-based operating system.

• gcc and make for C compiler installed.

• libpam, libcurl, openssl libraries installed. (When installing in a FreeBSD operating system,

first disable the option threaded_resolver[] from the library libcurl before installation).

1.3 Obtaining application ID

To obtain the "Application ID" and the "Secret", which are essential to integrate Latch into a service,

it’s necessary to register a developer account in Latch's website: https://latch.elevenpaths.com. On

the upper right side, click on “Developer area”.

Figure 01: “Developer area” in Latch webpage.

In the next screen, tap the button “Register as a developer” and select “Create a new developer account”, a form will appear where you can fill up the required data. Mandatory fields are name, e-mail and password.

Page 4: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 4 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

Figure 02: Sign in form for developers.

Once completed, an email will be sent, with an activation code to activate the brand new account.

Figure 03: Form to fill up with activation code.

When the account is activated, the user will be able to create applications with Latch and access to developer documentation, including existing SDKs and plugins.

Page 5: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 5 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

To do so the developer must log on to the Latch website and then access the "Developer area" section (https://latch.elevenpaths.com/www/developerArea), where you can view your applications through the "My applications" section on the side menu.

Figure 04: “My applications” section with user's configured applications.

From the "Add a new application" button, the developer will create a new application, with the specified name, which you want to appear in the end users' mobile application.

Figure 05: Creating an application. The name will be shown on the mobile app.

Information about the application is displayed when it is created and part of this data is editable. The basic data that the developer should use when installing the plugin are the "Application ID" and "Secret". In addition the following additional parameters are in place, which the developer may change at any time, that set the characteristics of your application:

Name: This corresponds to the name of the application that end users see on their devices when they pair the service. They can customize it themselves on their own device if they so wish.

Image: This corresponds to the application icon that will appear in the end-user's device; its size should not exceed 1MB. It is recommended to be in 24-bit png format without alpha channel, and its proportions are 1: 1.

Page 6: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 6 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

2nd OTP factor (One-time password): This is only available to developers with a subscription model other than "Community". It enables the service to also be protected by a password, which is sent to the end user at the time he/she wants to access the service. The OTP setup can be:

1. Disabled: The option will not appear on the end user's mobile device.

2. Opt in: The end user may choose to use this option to protect the service.

3. Mandatory: The end user will receive a password every time he/she wants to access the service.

Lock latches after request: This is only available to developers with a subscription model other than "Community". This enables the service to be locked automatically once it has been accessed. The “Lock latches after request” setup can be:

1. Disabled: The option will not appear on the end user's mobile device.

2. Opt in: The end user may choose to use this option to protect the service.

3. Mandatory: The service will be locked automatically once it has been accessed. In the latter case, the "Scheduled lock" option would disappear from the service details view.

Contact email and Contact phone: These details will be displayed in the notifications that users will receive when there is a fraudulent attempt to access the service or any of its operations.

Operations: This corresponds to each of the actions included in the service but independent of each other, and that the developer wants to protect with Latch. The number of operations that can be included depending on the model of subscription chosen. In each of the operations, a "2nd OTP factor" (OTP) and an "Lock latches after request" (LOR) can be used. It is not compulsory to create operations and this will depend on the nature of the service to be protected.

In this plugin in particular, at least one operation needs to be created. Two operations have been added in this example (figure 5), which correspond to the actions to be protected (“login”

and “sudo”). To protect another action, for example, access using SSH, you should add another operation.

Once the setup is complete and the changes have been saved, the new application will appear on the list of the developer's applications. This can be edited whenever you want.

Figure 06: Created application. It may be edited again at any moment.

1.4 Downloading the plugin

From the side menu in developers area, the developer can access the “Documentation & SDKs” section. Inside it, there is a “Plugins and SDKs” menu. Links to different SDKs in different programming languages and plugins developed so far, are shown.

Page 7: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 7 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

Figure 07: Examples of SDKs and plugins available.

The developer must tap the “DOWNLOAD” button for this plugin to access its source code from the

“Standard Plugins” section. A manual on the installation and use of the plugin can also be

downloaded.

Since this plug-in has multiple user options, the same source code is accessed by various keys, specifically those corresponding to (FreeBSD, Linux, OpenBSD, OpenVPN and SSH).

Page 8: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 8 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

2 Installing the plugin

Whether you decide to set up the plugin in advance or if you prefer to do it later, the administrator has to open a console and place it on the root directory of the downloaded packet. From here you need to execute the commands “./configure prefix=/usr sysconfdir=/etc && make && sudo make install”. You need to have “root“ permissions.

If installing on an OpenBSD or FreeBSD operating system, bear in mind that you need to add the options CFLAGS="-I/usr/local/include" and LDFLAGS="-L/usr/local/lib" to "configure", otherwise the gcc compiler will not find the dependencies.

./configure CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" prefix=/usr

sysconfdir=/etc && make && make install

After compiling the plugin source package, the "pam_latch.so" latch PAM module will be installed in the operating system, normally in the "/usr/lib" directory.

The next step is to place this library in the PAM directory of the operating system. The location of this directory varies, depending on the operating system where the plugin is installed. In UNIX-based systems, it is usually in the “/lib/security”, “/lib64/security” or “/lib/*/security” directory.

You need to carry out these two steps (compile the source package and place the library) before modifying the PAM setup as detailed in the next point. Otherwise the PAM services

that you wish to protect may become compromised.

2.1 Changing the PAM setup of the service requiring protection

One of the essential steps is to set up the services that need protection. To do this, go to the folder containing the PAM setup files (/etc/pam.d/) and edit the file or files of these services. Normally, all you need to do is to add the line below to the file. This will add Latch to the service you want to protect.

auth required pam_latch.so config=/etc/latch/latch.conf

accounts=/etc/latch/latch.accounts operation=<alias of the operation> otp=yes|no

<alias of the operation> is the name that will be used later to set up the plugin. This is the name that will be used to inform the plugin of the "operation ID" of the operation to be protected.

otp=yes|no refers to whether the operation will use the previously mentioned 2nd OTP authentication factor, and you must indicate yes or no as it cannot be left blank.

The downloaded plugin includes the "examples" directory, which contains examples of how to setup the PAM file of various services.

Image 08: Directories containing examples

Page 9: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 9 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

After completing the plugin installation steps, all you need is to set up the plugin correctly. Open the latch.conf file in the /etc/latch/ directory and add the data that was generated when the application was created, (see Image 5).

Image 09: Inclusion of the Application ID, the Secret and operations.

The following section show how to set up the SSH and OpenVPN services to use the plugin. These sections are only useful if you want to protect these services.

2.2 Setting up SSH to use the plugin

The PAM SSH service has to be set up previously (see Section Changing the PAM setup of the service requiring protection).

To use the Latch plugin in SSH once it is installed in the operating system, you will have to edit the sshd_config file, which is normally located in the “/etc” o “/etc/ssh” directory, and add the following lines or edit their contents:

UsePAM yes ChallengeResponseAuthentication yes PasswordAuthentication no

Then, the SSH service must be restarted.

Page 10: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 10 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

2.2.1 Public/private key protection Additional steps to those mentioned above have to be taken to protect public/private keys with Latch. Edit all of the keys you want to protect by adding an instruction that allows Latch to access before authentication. These keys are found in the authorized keys file (“/etc” o “/etc/ssh”):

command="latch- ssh-cmd -o <alias sshd-keys>" + key.

The end result should be:

command="latch-ssh-cmd -o sshd-keys" ssh-rsa AAA...HP5 someone@host

Where <alias sshd-keys> is the name used to indicate the operation, as mentioned above, (see Section Changing the PAM setup of the service requiring protection).

Take into account that public/private key protection does not support OTP.

2.2.2 SELinux (Fedora/CentOs) setup In version 20 of Fedora or in version 6.7 of CentOs, the program “SELinux“ at times defines a security policy that prevents communication from being opened between the SSH server and the Latch server. To solve this problem, you must add a SELinux module to the policy. To do so you must enter the “SELinux“ folder of the packet for the downloaded plugin and execute the command “semodule -i latch_ssh.pp“. Then you must enable the variable that was created through the command “setsebool -P ssh_can_network 1“.

After this SELinux will be setup for the proper operation of the plugin.

2.3 Setting up OpenVPN to use the plugin

The PAM OpenVPN service has to be set up previously (see Section Changing the PAM setup of the service requiring protection).

To set up this plugin, you will need the following:

OpenVPN version 2.2.x.

To have the "Auth-pam OpenVPN" installed, which is included by default in OpenVPN.

All you need to do is to add the following line in the setup file of the OpenVPN server (this is normally the server.conf file):

"plugin /path/to/openvpn-auth-pam.so openvpn"

2.4 Uninstalling the plugin

Users can uninstall Latch by inverting the installation steps:

1. Changing the PAM setup of the service requiring protection (see Changing the PAM setup of

the service requiring protection).

This step must be performed before uninstalling the plug-in. Otherwise the PAM services

protected with Latch may become compromised.

Page 11: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 11 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

2. Opening a console and place it on the root directory of the downloaded packet. From here

you need to execute the commands “./configure prefix=/usr sysconfdir=/etc && make &&

sudo make install”. You need to have “root“ permissions.

Uninstalling the plugin does not mean that users will no longer have the pairing service of the Latch app (see figures in step 4). This will only happen when users carry out the unpairing or

when the administrator removes the service from the Latch web (see Figure 06).

Page 12: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 12 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

3 Use of the Latch plugin by end users

Latch does not affect in any case or in any way the usual operations with a service. It just allows or denies actions over it, acting as an independent extra layer of security that, once removed or without effect, will have no effect over the service, which will remain with their original state.

3.1 Pairing a user

When the plugin is configured, users may use it. They need the Latch application installed on their mobile devices, and follow these steps:

Step 1: Just open a console and execute “latch –p + TOKEN GENERATED BY LATCH”. The following

image shows the various parameters that can be used with Latch.

Figure 10: The user should introduce the pairing code generated by Latch here.

Step 2: From the Latch app on the mobile device, the user has to generate the pairing code,

pressing on “Add a new service" at the bottom of the application, and pressing "Pair with Latch"

and then "Generate new code" will take the user to a new screen where the pairing code will be

displayed.

Step 3: Next the same characters displayed on the mobile device must be entered (before they

expire) on the site created by the administrator for pairing with Latch and then tap the button to

confirm the pairing. A notification will be received on the mobile device, announcing that the

service is already paired.

Page 13: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 13 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

Figure 11: Button that accesses the pairing code.

Figure 12: Generated pairing code. Figure 13: Notification after successful pairing.

Step 4: After pairing, the user will be able to access the accounts list paired with Latch. Users can

check that the pairing was recently added. From this point users can lock and unlock access to

these services simply by tapping the button beside each service name.

Figure 14: Unlocked service. Figure 15: Locked service.

To test Latch, the user needs to lock the service from Latch app, and try to access again introducing the right credentials.

If the configuration is correct, the user will not be able to access in even if the correct credentials were introduced. Additionally, a notification on the mobile device will be received, warning about somebody trying to access the service. The notification includes the email and the phone that the developer stated at when created (Figure 5).

Page 14: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 14 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

Figure 16: A user accessing. Figure 17: Notification of an unauthorized access attempt.

After unlocking the service from Latch app and introducing the right credentials again, the user will be able to access.

3.2 Unpairing a user

Simply access the section where the pairing initially took place and unpair throught the corresponding element. Finally, an alert indicating that the service has been unpaired will be displayed

Figure 18: Unpairing Latch. Figure 19: Alert displaying the service has been unpaired.

Page 15: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 15 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

4 Resources

For more information about how to use Latch and testing more free features, please refer to the user guide in Spanish and English:

1. Guía del usuario de Latch con Nevele Bank. 2. Latch user´s guide for Nevele Bank.

You can also access the following constantly expanded documentation:

Manuals in Spanish and English for integrating and using Latch with the available plugins, at the Latch website and via the ElevenPaths Slideshare channel.

Videos with subtitles in Spanish and English for integrating and using Latch with the available plugins on ElevenPaths' YouTube and Vimeo channels.

Manuals for integrating and using Latch in the organizations that have already implemented it (Movistar, Tuenti, UNIR, USAL, etc.), at the Latch website and via the ElevenPaths Slideshare channel.

Information about Latch API at the Latch website.

Page 16: Latch UNIX english

Latch 1.1 plugin installation and user guide for systems based on UNIX

V.7.1 – November 2016

Page 16 of 16 2016 © Telefónica Digital España, S.L.U. All rights reserved.

The information disclosed in this document is the property of Telefónica Digital España, S.L.U. (“TDE”) and/or any other entity within Telefónica Group and/or its licensors. TDE and/or any Telefonica Group entity or TDE’S licensors reserve all patent, copyright and other proprietary rights to this document, including all design, manufacturing, reproduction, use and sales rights thereto, except to the extent said rights are expressly granted to others. The information in this document is subject to change at any time, without notice.

Neither the whole nor any part of the information contained herein may be copied, distributed, adapted or reproduced in any material form except with the prior written consent of TDE.

This document is intended only to assist the reader in the use of the product or service described in the document. In consideration of receipt of this document, the recipient agrees to use such information for its own use and not for other use.

TDE shall not be liable for any loss or damage arising out from the use of the any information in this document or any error or omission in such information or any incorrect use of the product or service. The use of the product or service described in this document are regulated in accordance with the terms and conditions accepted by the reader.

TDE and its trademarks (or any other trademarks owned by Telefonica Group) are registered service marks.

PUBLICATION:

November 2016

elevenpaths.com Blog.elevenpaths.com @ElevenPaths Facebook.com/ElevenPaths YouTube.com/ElevenPaths

At ElevenPaths we have our own way of thinking when we talk about security. Led by Chema Alonso, we are a team of experts who are passionate about their work, who are eager to redefine the industry and have great experience and knowledge about the security sector.

Security threats in technology evolve at an increasingly quicker and relentless pace. Thus, since June 2013, we have become a startup company within Telefónica aimed at working in an agile and dynamic way, transforming the concept of security and, consequently, staying a step ahead of our attackers.

Our head office is in Spain, but we can also be found in the UK, the USA, Brazil, Argentina and Colombia.

If you wish to know more about us, please contact us at: