authentec vpn client guide final

Dummy Page - To be discarded before printing

Use this template with A6MotoLandscapeProduct1 StructApps.See the Reference Pages for template user instructions.

Authentec VPN Client Guide 12/2/10

1About This Document

About This DocumentThis document contains instructions for QuickSecIPsec VPN Client for Android users, describing how toconfigure and operate the product.

Document conventions

Convention Use Example

Bold Menus, GUIelements,strongemphasis.

Click Apply orOK.

→ Monospace. Series of menuselections,Filenames,commands,directories,URLs etc.

Select File → Save. Referto readme.txt

Italics Reference tootherdocuments orproducts,emphasis.

SeeReferenceManual.

Client User InterfaceThe client's Graphical User Interface (GUI) displaysstatus information about Policy Manager and the activeconnection, allows controlling the runtime operationsof the client, as well as editing the configurationsettings.

Android client user interfaceThe QuickSec VPN Client can be started by clicking theVPN Client icon (bottom left of the screen).

2 About This Document

The initial screen of the QuickSec VPN Client lists thecurrently configured connections:

Connecting

New connections can be created by pressing theMenu button and selecting the New option.

3About This Document

Old connections can be edited by performing longtouch on the connection name in list of connectionsand selecting the Edit option.

Connections can be activated by selecting theConnect option and disabled by selecting theDisconnect option.

To remove the settings for a connection that is nolonger required, select the Delete option from theConnection menu.

Configuring connections

The connection options can be set up using thegraphical user interface by defining a value for each ofthe required parameters. Select the Connection Edit

menu option to bring up the connection dialog.

In the connection dialog, the following parameters canbe defined:

• Connection name: Name of the connection shownat the start.

• Connection template: Type of the connection andpre-set parameters. These selections affect types ofparameters below.

• Gateway: IP address of the security gateway.

• Certificate: Certificate to be used forauthentication.

• Certificate Authority: CA to be used in thisconnection.

• Username: Username for authentication of the user

• Password: User's password.

• Pre-Shared Key Type: Key input method (text/hex)

• Pre-Shared Key: The key to be used to authenticate

4 About This Document

• Identity Type: Which IKE-identity type is to be usedwith this connection.

• Identity: Identity to be used.

• Internal Subnet IP: IP subnets to be accessedthrough this connection. This is used forsplit-tunneling.

For information on how to specify permanentconfiguration settings, see section 3 (ClientConfiguration).

Connection settings example

The following example specifies the manualconnection parameters for a simple gatewayconnection also described in “Gateway ConnectionExample” on page 16:

Gateway: 192.168.57.30

Pre-Shared Key Type: Text

Pre-Shared Key: torstA1

Identity Type: User FQDN

Identity: [email protected]

Internal subnet: 10.1.1.0/24

5Client Configuration

Client Configuration

Android connection templatesTo minimize the number of fields end-user needs toconfigure for the VPN connections, it is possible topre-install connection templates to the VPN Clientapplication. The built-in templates consist ofinformation on IKE and IPsec parameters, but it ispossible to pre-set more of the connection values in atemplate.

When a new connection definition is created, thecontents of a template are copied into the connectiondefinition. After this, a limited set of parameters in thenew connection definition can be modified using theVPN Client GUI, as described in “Configuringconnections” on page 3.

By using template files it is possible for a networkadministrator to set connection parameters for VPNnetworks that the user may activate without the needto define the configuration manually.

The VPN client come pre-loaded with the set oftemplates for most commonly used connectionconfigurations.

It is also possible to extend the set of availabletemplates by side-loading customized templates to thefollowing directory on SD card:

/sdcard/vpn/templates/

The template package filename must match thefollowing regular expression pattern:

[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}.txt

or in plain words:

"8 hex digits"-"4 hex digits"-"4 hex digits"-"4 hexdigits"-"12 hex digits".txt

6 Client Configuration

Template model

The following notation is used for describing theconnection template file syntax:

• Each syntactic construct is defined by a ruleconsisting of the name of the construct, an equalsign and the definition of the construct.

• When there are multiple alternative definitions of aconstruct the right hand side of a rule consists of allthese alternatives separated by vertical bars.

• In the definition part of a rule, words beginning witha capital letter indicate constructs defined by otherrules.

• Words written in lowercase letters are keywords;they must be written in the file exactly as shown.

• Words written in uppercase letters are values. Theymay use the quoted or unquoted value syntaxdescribed above.

• Curly braces ({ and })and semicolons (;) must appearin the file exactly as shown.

• Spaces and line breaks within the rule are not partof the definition; they just help formatting thisdocument.

• In the template model below, the letter ‘W’indicates optional white space, i.e. zero or morewhite space characters. At least one white space

character must appear where two adjacentconstructs cannot be separated otherwise, forexample a keyword followed by an unquoted value.

The following listing is an empty model for a template,containing placeholders for global settings, connectiondefinitions and template definitions in a single file.

Configuration-File =

W Version W Configuration-Elements W

Version =

version W VERSION W ;

Configuration-Elements =

Empty |

Configuration-Element W Configuration-Elements

Configuration-Element =

active-connection W CONNECTION-TITLE W ; |

startup-connect W ; |

connection W CONNECTION-TITLE W { WConnection-Parameters W }

template W TEMPLATE-TITLE W { WConnection-Parameters W }

Connection-Parameters =

Empty |

Connection-Parameter W Connection-Parameters


Connection-Parameter =

gateway-address W ADDRESS W ; |

internal-subnet W NETWORK W ; |

host-authentication W MODE W ; |

user-authentication W ; |

own-identity W{ W type WTYPEW ; Wvalue W VALUEW; W } |

pre-shared-key W { W type W TYPE W ; W value WVALUE W ; W } |

ca-identity W { W type W TYPE W ; W valueW VALUEW ; W }|

username W USERNAME W ; |

password W PASSWORD W ; |

tunnel-mode W MODE W ; |

ike-parameters W { W IKE-Parameters W } |

ipsec-parameters W { W IPsec-Parameters W }

IKE-Parameters =

Empty |

IKE-Parameter W IKE-Parameters

IPsec-Parameters =

Empty |

IPsec-Parameter W IPsec-Parameters

IKE-Parameter =

version W VERSION W ; |

aggressive-mode W ; |

encryption W ENCRYPTION W ;|

integrity W INTEGRITY W ; |

group W GROUP W ; |

lifeW LIFE W ;

IPsec-Parameter =

encryption W ENCRYPTION W ; |

integrity W INTEGRITY W ; |

perfect-forward-secrecy W ; |

anti-replay W ; |

lifeW { W type W TYPE W ; W value WVALUE W ;W }

Empty =


QuickSec VPN Client Templates Syntax

Template File Format

Special Characters

The following ASCII characters are special, unlessescaped within a quoted value as explained below:

Characters 9 (horizontal tab), 10 (line feed), 11 (verticaltab), 12 (form feed), 13 (carriage return) and 32 (space)are treated as white space.

Character 34 (double quote ") is used to begin and enda quoted value.

Character 59 (semicolon ;) terminates a keyword-valuesequence.

Character 92 (backslash \) is used as an escapecharacter within a quoted value; outside quoted valuesit is not special.

Character 123 (left curly brace {) begins and character125 (right curly brace }) ends a structure consisting ofmultiple configuration elements.Keywords

Character 123 (left curly brace {) begins and character125 (right curly brace }) ends a structure consisting ofmultiple configuration elements.

Keywords

A keyword is a sequence of one or more charactersthat do not belong to the set of special characters

defined above.

Note: The backslash character (\) is not special withinkeywords.

Values

Values may be quoted or unquoted. A value is quotedif it is surrounded by double quotation marks (as in"value"). An unquoted value is similar to a keyword; itconsists of characters that do not belong to the set ofspecial characters.

A value must be quoted if it contains specialcharacters. It may be quoted in other cases too.

Any special characters appearing in the value must beescaped by preceding them by the backslash character(\). This applies to the backslash character itself as well(\\). Escaping non-special characters has no effect.When processing the file, the extra backslashcharacters are removed and the following charactersare treated as non-special.

White Space

White space characters are used to separate elementsof the file from each other and to format the file foreasy reading. Any number of white space charactersmay be used wherever white space is allowed.

In some cases at least one white space character isnecessary, for example between a keyword and anunquoted value. In other cases it is not necessary to


use white space at all, for example between a keywordand a left curly brace.

Template Parameters

In place of the Connection-Parameters string in atemplate definition, the following elements mayappear, in any order (the minimum and maximumnumbers of occurrences of a particular element areshown in parentheses):

• Gateway address (1, 1)

• Internal subnet (0, 4)

• Host authentication mode (1, 1)

• User authentication mode (1, 1)

• Own identity (0, 1)

• Pre-shared key (0, 1)

• Certificate authority identity (0, 1)

• Username (0, 1)

• Password (0, 1)

• Tunnel mode (1, 1)

• IKE parameters (1, 1)

• IPsec parameters (1, 1)

For a connection definition, the following restrictionsapply:

If pre-shared host authentication is specified, then apre-shared key must be present.

If public-key host authentication is specified, the ownidentity element is used to look up a certificate to besent to the gateway. Also in this case the certificateauthority identity element must be present and will beused to look up a CA certificate that will be usedrequest a certificate from the gateway and validate it.

Gateway address

The gateway-address element defines the IP addressof the remote VPN gateway in a connection definition.It is of the following form:

gateway-address ADDRESS;

The ADDRESS definition must be an IPv4 address inthe dotted-decimal form, an IPv6 address expressed intext format (as specified in the RFC 2373 document),or a Fully Qualified Domain Name (FQDN).

Internal Subnet

The internal-subnetelement defines a protected IPsub-network accessed through the VPN connection. Itis of the following form:

internal-subnet NETWORK;


The NETWORK definition specifies the sub-networkusing the Classless Inter-Domain Routing (CIDR)notation. It consists of an IPv4 or IPv6 address in thesame format as in the gateway address elementabove, a forward slash (ASCII character 47, or /) and adecimal number specifying the prefix length, i.e. thenumber of bits in the address that specify the network-for example 192.168.100.1/24.

Bits of the address that are not part of the prefix mustbe zero.

Host Authentication Mode

The host-authenticationelement specifies whetherhost (machine) authentication is done usingPre-Shared Keys (PSK) or Public Key Infrastructure(PKI). It is of the following form:

host-authentication MODE;

The MODE definition is one of the following values:

• pre-shared

• public-key

User Authentication

When the user-authentication element is present,password-based user authentication is done in additionto machine authentication. The element is of thefollowing form:

user-authentication;

Own Identity

The own-identity element defines the identity of theVPN Client machine in the IKE negotiation. It is of thefollowing form:

own-identity { type TYPE; value VALUE; }

The TYPE definition specifies how VALUE is to beinterpreted. Acceptable values of TYPE and thecorresponding interpretations of VALUE are thefollowing:

• ip-address: an IPv4 or IPv6 address.

• fqdn: a Fully Qualified Domain Name (FQDN).

• user-fqdn: a fully qualified username string, i.e. ausername followed by an at sign (ASCII character64, or @) and a Fully Qualified Domain Name(FQDN) -for example [email protected].

• distinguished-name: string representation of anX.500 Distinguished Name (DN) in the formatspecified in the RFC 4514 document.

• key-identifier: an opaque key or certificate identifierexpressed as a string of hexadecimal digits.

If public-key host authentication is used, it must bepossible to associate the identity with a certificate anda private key in the local certificate store using thesubjectName, subjectAltName orsubjectKeyIdentifiercomponents of the certificate.


Pre-Shared Key

This element defines a pre-shared key used in the IKEnegotiation. It is of the following form:

pre-shared-key { type TYPE; value VALUE; }

The TYPE definition specifies how VALUE is to beinterpreted. Regardless of TYPE, VALUE is the base64encoding (according to the RFC 2068 document) of thebytes of an UTF-8 string. TYPE applies to the stringafter base64 decoding.

Acceptable values of TYPE and the correspondinginterpretations of decoded VALUE are the following:

• string: decoded VALUE is an UTF-8 string and thebytes of the UTF-8 representation become thepre-shared key.

• hexadecimal: decoded VALUE must be a string ofhexadecimal digits that are read two at a time to getthe values of the bytes of the pre-shared key.

Certificate Authority Identity

The ca-identity element specifies the identity that isused to look up a Certificate Authority (CA) certificatein the certificate store of the VPN Client machine. It isof the following form:

ca-identity { type TYPE; value VALUE; }

Android Configuration Syntax

The TYPE and VALUE definitions follow the same rulesas in the own-identity element above. The identity isused to look up a CA certificate in the local certificatestore. An identifier of the CA certificate is sent to theVPN gateway to request it to send its own certificate.The CA certificate is subsequently used to validate thecertificate sent by the gateway.

Username

The usernameelement specifies the username to beused in user authentication after host authentication iscompleted. It is of the following form:

username USERNAME;

The USERNAME definition may be any string. Thevalue sent to the gateway consists of the bytes of theUTF-8 representation of the string.

Password

This element specifies the password to be used inuser authentication after host authentication iscompleted. It is of the following form:

password PASSWORD;

The PASSWORD definition is the base64 encoding(according to RFC 2068) of the bytes of an UTF-8string. The value sent to the gateway consists of thebytes of the UTF-8 representation.


Tunnel Mode

The tunnel-mode element specifies the VPN tunnelingand client configuration method. It is of the followingform:

tunnel-mode MODE;

The MODE definition is one of the following values:

• ipsec: specifies IPsec in tunnel mode with internalIP address configured using IKE Config Mode(IKEv1) or IKE Configuration Payload (IKEv2).

• l2tp-over-ipsec: specifies Layer 2 Tunneling Protocol(L2TP) over transport-mode IPsec with internal IPaddress configured using Point-to-Point Protocol(PPP).

IKE Parameters

The IKE-parameterselement specifies the parametersto be used to negotiate the Internet Key Exchange(IKE) Security Association (SA). It is of the followingform:

IKE-parameters { IKE-Parameters }

IKE-Parametersmust contain the following elements,in any order:

IKE version (mandatory)

IKE phase 1 aggressive mode (optional)

IKE encryption (mandatory)

IKE pseudo-random function (mandatory)

IKE integrity (mandatory)

IKE group (mandatory)

IKE life (mandatory)

IKE Version

The version element specifies the IKE protocol version(IKEv1 or IKEv2) to be used with the VPN connection.It is of the following form:

version VERSION;

The VERSION definition is one of the following values:

1

2

IKE Phase 1 Aggressive Mode

When the aggressive-mode element is present,aggressive mode phase 1 exchange is used with IKEv1instead of main mode. It is of the following form:

aggressive-mode;

Note: This value has no effect on IKEv2 connections.

IKE Encryption

The encryption element specifies the encryptionalgorithm of the IKE Security Association. It is of thefollowing form:


encryption ENCRYPTION;

The ENCRYPTION definition is one of the followingvalues:

• 3des-cbc

• aes-cbc-128

• aes-cbc-192

• aes-cbc-256

IKE Integrity

The integrity element specifies the integrity algorithmof the IKE Security Association. It is of the followingform:

integrity INTEGRITY;

The INTEGRITY definition is one of the followingvalues:

• hmac-md5-96

• hmac-sha1-96

• aes-xcbc-mac-96

• hmac-sha-256-128

• hmac-sha-384-192

• hmac-sha-512-256

Note: The aes-xcbc-mac-96value is not valid with IKEversion 1.

IKE Group

The group element specifies the Diffie-Hellman groupused in the IKE SA negotiation. It is of the followingform:

group GROUP;

The GROUP definition is one of the following values(the corresponding IKEv1/IKEv2 group id is shown inparentheses):

modp-768(group id 1)








ecp-256(group id 19)



IKE Life

The life element specifies the maximum lifetime of theIKE SA. It is of the following form:

life LIFE;


The LIFE definition must be a decimal number andspecifies the IKE SA lifetime in seconds.

IPsec Parameters

The IPsec-parameterselement specifies theparameters to be used to negotiate IPsec SecurityAssociations. It is of the following form:

ipsec-parameters { IPsec-Parameters }

IPsec-Parametersmust contain the followingelements, in any order:

• IPsec encryption (mandatory)

• IPsec integrity (mandatory)

• IPsec perfect forward secrecy (optional)

• IPsec anti-replay (optional)

• IPsec life (mandatory)

• IPsec Encryption

The encryption element specifies the encryptionalgorithm of an IPsec Security Association. It is of thefollowing form:

encryption ENCRYPTION;

The ENCRYPTION definition is one of the followingvalues:

• 3des-cbc

• aes-cbc-128

• aes-cbc-192

• aes-cbc-256

• aes-gcm-128

• aes-gcm-192

• aes-gcm-256

• null

Note: The value null must be used if IPsec integrityalgorithm is aes-gmac-128, aes-gmac-192 oraes-gmac-256and must not be used with any otherIPsec integrity algorithm values.

IPsec Integrity

The integrityelement specifies the integrity algorithmof an IPsec SA. It is of the following form:

integrity INTEGRITY; The INTEGRITY definition is oneof the following values:

• hmac-md5-96

• hmac-sha1-96

• aes-xcbc-mac-96

• hmac-sha-256-128

• hmac-sha-384-192

• hmac-sha-512-256

• null

• aes-gmac-128


• aes-gmac-192

• o aes-gmac-256

Note: The values aes-gmac-128, aes-gmac-192andaes-gmac-256are not valid with IKE version.

The value null must be used if IPsec encryptionalgorithm is aes-gcm-128, aes-gcm-192 oraes-gcm-256and must not be used with any otherIPsec encryption algorithm values.

IPsec Perfect Forward Secrecy

When the perfect-forward-secrecyelement is present,IPsec Perfect Forward Secrecy (PFS) is used. It is ofthe following form:

perfect-forward-secrecy;

The Diffie-Hellman group used for IPsec SA keyingwith PFS is the one specified for IKE in IKE

Parameters.

IPsec Anti-Replay

When the anti-replayelement is present, IPsecanti-replay is used. It is of the following form:anti-replay;

IPsec Life

The lifeelement specifies the maximum lifetime of anIPsec SA. It is of the following form:

life { type TYPE; value VALUE; }

The TYPE definition specifies how VALUE is to beinterpreted. Acceptable values of TYPE and thecorresponding interpretations of VALUE are thefollowing:

• seconds: a decimal number that specifies themaximum SA lifetime in seconds.

• kilobytes: a decimal number that specifies themaximum SA lifetime in kilobytes of datatransferred through the SA.


Certificate SupportQuickSec IPsec VPN Client for Android supportsBER-encoded public-key certificates and PKCS #8formatted private keys. Supported certificate andprivate key types and their filename extensions are thefollowing:

• .caCertificate Authority (CA) certificate

• .crt: end-user certificate

• .pkcs8: private key

•

Certificate Storage

QuickSec IPsec VPN Client for Android storescertificates and private keys in the following directory:

/sdcard/vpn/certificates/

There is no integration to existing certificate store orsecure key storage in current version. Certificate storesupport will be added in the follow-up revision.

New certificates and private keys can be added to thecertificate directory by using the Android DebugBridge (ADB) package. End-user or IT admin shouldpre-install any required certificates and private keys inthe device.

Android Configuration Examples

Gateway Connection Example

An example connection to a gateway can be specifiedusing the following configuration data:

connection Example Gateway {

gateway-address 192.168.57.30;

internal-subnet 10.1.1.0/24;

host-authentication pre-shared;

pre-shared-key {

type string;

value UGVyamFUD;

own-identity {

type user-fqdn;

value [email protected];

}

ipsec-parameters {

encryption aes-cbc-128;

integrity hmac-sha1-96;

anti-replay;

life {

type seconds;


value 28800;

}

}

ike-parameters {

version 2;



group modp-1024;

life 86400;

}

}

Example of Template Use

The example below contains global settings,connection definitions and template definitions in asingle file.

version 1.0;

active-connection "EMEA Low Security;

startup-connect;

connection "VPN to Company" {




internal-subnet 2001::0/64;


own-identity {type user-fqdn; [email protected];}

pre-shared-key {type string; value foo;}

tunnel-mode ipsec;

ike-parameters {

version 1;

encryption 3des-cbc;

pseudo-random hmac-sha1;


group modp-1024;

life 86400;

}

ipsec-parameters {




anti-replay;

life {type seconds; value 28800;}

}

}


connection "VPN to Corporation" {





host-authentication public-key;


own-identity {

type distinguished-name;

value "CN=User Account, O=AuthenTec, C=FI";

}

ca-identity {

type distinguished-name;

value "CN=APAC CA, O=AuthenTec, C=KR";

}

username "user";

password "bing bong tilt";

tunnel-mode ipsec;

ike-parameters {

version 2;


pseudo-random aes-xcbc-prf-128;

integrity aes-xcbc-mac-96;

group modp-2048;

life 86400;

}

ipsec-parameters {




anti-replay;


}

}

template "Company" {






tunnel-mode ipsec;

ike-parameters {


version 1;



group modp-1024;

life 86400;

}

ipsec-parameters {




anti-replay;


}

template "Corporation" {





host-authentication public-key;


tunnel-mode ipsec;

ike-parameters {

version 2;



group modp-2048;

life 86400;

}

ipsec-parameters {




anti-replay;


}

}

authentec vpn client guide final

Documents