Express DX Openswan Getting Started Guide

CryptoAPI Engine 1.1.1

Getting Started

User Guide

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by any means without the written permission of Exar Corporation. Licensing and Government Use

Any Exar software (“Licensed Programs”) based on Hifn Technology described in this document is furnished under a license and may be used and copied only in accordance with the terms of such license and with the inclusion of this copyright notice. Distribution of this document or any copies thereof and the ability to transfer title or ownership of this document’s contents are subject to the terms of such license. Such Licensed Programs and their documentation may contain public open-source software that would be licensed under open-source licenses. Refer to the applicable product release notes for open-source licenses and proprietary notices. Use, duplication, disclosure, and acquisition by the U.S. Government of such Licensed Programs is subject to the terms and definitions of their applicable license. Disclaimer

Exar reserves the right to make changes to its products, including the contents of this document, or to discontinue any product or service without notice. Exar advises its customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied upon is current. Every effort has been made to keep the information in this document current and accurate as of the date of this document’s publication or revision. Limited Warranty

Exar warrants Products based on the Hifn Technology, including cards, against defects in materials and workmanship for a period of twelve (12) months from the delivery date. Exar's sole liability shall be limited to either, replacing, repairing or issuing credit, at its option, for the Product if it has been paid for. Exar will not be liable under this provision unless: (a) Exar is promptly notified in writing upon discovery of claimed defects by Buyer; (b) The claimed defective Product is returned to Exar, insurance and transportation charges prepaid, by Buyer; (c) The claimed defective Product is received within twelve (12) months from the delivery date; and (d) Exar's examination of the Product discloses to its satisfaction that the alleged defect was not caused by misuse, neglect, improper installation, repair, alteration, accident or other hazard. THIS WARRANTY DOES NOT COVER PRODUCT DAMAGE WHICH RESULTS FROM ACCIDENT, MISUSE, ABUSE, IMPROPER LINE VOLTAGE, FIRE, FLOOD, LIGHTNING OR OTHER ACTS OF GOD OR DAMAGE RESULTING FROM ANY MODIFICATIONS, REPAIRS OR ALTERATIONS PERFORMED OTHER THAN BY EXAR OR EXAR'S AUTHORIZED AGENT OR RESULTING FROM FAILURE TO STRICTLY COMPLY WITH EXAR'S WRITTEN OPERATING AND MAINTENANCE INSTRUCTIONS. BUYER ACKNOWLEDGES THAT THE PRODUCT ARE HIGHLY SENSITIVE ELECTRONIC PRODUCT REQUIRING SPECIAL HANDLING AND THAT THIS WARRANTY DOES NOT APPLY TO IMPROPERLY HANDLED PRODUCT. PRODUCT MANUFACTURED TO MEET BUYER'S SPECIFIC PERFORMANCE SPECIFICATIONS ACCEPTED BY EXAR ARE WARRANTED ONLY TO PERFORM IN CONFORMITY WITH SUCH SPECIFICATIONS, AND ARE WARRANTED ONLY AGAINST DEFECTS NOT RELATED TO SUCH SPECIFICATIONS IN ACCORDANCE WITH THE TERMS AND CONDITIONS SET FORTH HEREIN ABOVE. Life Support Policy

Exar's Product are not authorized for use as critical components in life support devices or systems. Life support devices or systems are devices or systems which, (a) are intended for surgical implant into the body, or (b) support or sustain life, and whose failure to perform, when properly used in accordance with instructions for use provided in the labeling, can be reasonably expected to result in a significant injury or death to human life. A critical component is any component of a life support device or system whose failure to perform can be reasonably expected to cause the failure of the life support device or system, or to affect its safety or effectiveness. Buyer agrees to indemnify, defend and hold Exar harmless for any cost, loss, liability, or expense (including without limitation attorneys' fees and other costs of litigation or threatened litigation) arising out of violation of the above prohibition by Buyer or any person or entity receiving Exar's Product through Buyer. Patent Infringement - Indemnification

Exar agrees, at its own expense, to defend Buyer from and against any claim, suit or proceeding, and to pay all judgments and costs finally awarded against Buyer by reason of claim, suit or proceeding insofar as it is based upon an allegation that the Product as furnished by Exar infringes any United States letter patent, provided that Exar is notified promptly of such claim in writing and is given authority and full and proper information and assistance (at Exar's expense) for defense of same. In case such Product are finally constituted an infringement and the use of Product is enjoined, Exar shall at its sole discretion and at its own expense: (1) procure for Buyer the right to continue using the Product; (2) replace or modify the same so that it becomes non-infringing; or (3) remove such Product and grant Buyer a credit for the depreciated value of the same. Buyer shall have the right to employ separate counsel in any claim, suit or proceeding and to participate in the defense thereof, but the fees and expenses of Buyer's counsel shall not be borne by Exar unless: (1) Exar specifically so agrees; or (2) Exar, after written request and without cause, does not assume such defense. Exar shall not be liable to indemnify Buyer for any settlement effected without Exar's written consent, unless Exar failed, after notice and without cause, to defend such claim, suit or proceeding. The indemnification shall not apply and Buyer shall indemnify Exar and hold it harmless from all liability or expense (including costs of suit and attorney's fees) if the infringement arises from, or is based upon Exar's

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 2 Exar Confidential compliance with particular requirements of Buyer or Buyer's customer that differ from Exar's standard specifications (Custom Product) for the Product, or modifications or alterations of the Product, or a combination of the Product with other items not furnished or manufactured by Exar. Buyer agrees that Exar shall not be liable for any collateral, incidental or consequential damages arising out of patent infringement. The foregoing states the entire liability of Exar for patent infringement. Motorola

The use of this product in stateful compression protocols (for example, PPP or multi-history applications) with certain configurations may require a license from Motorola. In such cases, a license agreement for the right to use Motorola patents (US05,245,614, US05,130,993) may be obtained directly from Motorola. Patents

May include one or more of the following United States patents: 4,930,142; 4,996,690; 4,701,745; 5,003,307; 5,016,009; 5,126,739; 5,146,221; 5,414,425; 5,414,850; 5,463,390; 5,506,580; 5,532,694; 6,320,846; 6,816,459; 6,651,099; 6,665,725; 6,771,646; 6,789,116; 6,954,789; 6,839,751; 7,299,282; 7,260,558. Other patents pending. Trademarks

Hi/fn®, MeterFlow®, MeterWorks®, and LZS®, are registered trademarks of Exar Corporation. HifnTM, Hifn Technology, FlowThroughTM, BitWackr, and the Hifn logo are trademarks of Hi/fn, Inc. All other trademarks and trade names are the property of their respective holders. IBM, IBM Logo, and IBM PowerPC are trademarks of International Business Machines Corporation in the United States, or other countries. Microsoft, Windows, Windows XP, Windows Vista, Windows Server 2003, Windows Server 2008 and the Windows logo are trademarks of Microsoft Corporation in the United States, and/or other countries. Intel QuickAssist is a trademark of Intel Corporation in the United States and in other countries. Exporting

This product may only be exported from the United States in accordance with applicable Export Administration Regulations. Diversion contrary to United States laws is prohibited. Exar Confidential

If you have signed a Exar Confidential Disclosure Agreement that includes this document as part of its subject matter, please use this document in accordance with the terms of the agreement. If not, please destroy the document.

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 3 Exar Confidential Table of Contents

List of Figures ...... 5

Preface ...... 6

Glossary ...... 8

1 Introduction ...... 9

1.1 Requirements ...... 9

1.2 Documentation Overview ...... 10 1.2.1 Software Documents ...... 10 1.2.2 System Documents ...... 10

2 Overview ...... 12

2.1 IPsec ...... 12

2.2 Exar’s CryptoAPI Engine Software Offering ...... 13

2.3 Linux Crypto API Overview ...... 15

3 Installing the CryptoAPI Engine Package Files...... 17

3.1 Install the IPsec Implementation Package...... 17

3.2 Install the CryptoAPI Engine Software ...... 17

4 Test the Network Connection ...... 20

4.1 IP Routing Tool Test ...... 20

4.2 Netkey Test...... 21

I Document Revision History ...... 24

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 4 Exar Confidential List of Figures

Figure 2-1. CryptoAPI Package Components...... 14 Figure 4-1. Test Network Topology ...... 20

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 5 Exar Confidential Preface

About This Document

Welcome to Exar’s CryptoAPI Engine Getting Started User Guide for Exar’s Express DX family of devices and cards. This document gives instructions on how to install and use the CryptoAPI Engine software offering version 1.1.1.

The term “Exar Express DX card” will be used to in this document to refer to any of the Exar DX 18xx or 17xx cards. If any particular usage is required for a unique platform, it will be specifically noted.

Audience

This document is intended for integrators and application developers responsible for and familiar with software and hardware architecture of a target system.

Prerequisite

Before proceeding, you should generally understand:

• Advanced Encryption Standard (AES), Triple Data Encryption Standard (3DES) and their modes of operation • Cryptographic hash functions • Software and hardware of the target system • C and C++ programming language • Linux programming language

Document Organization

This document is organized as follows:

Chapter 1, “Introduction” lists the installation requirements and a description of the CryptoAPI Engine documents.

Chapter 2, “Overview” provides an overview of the CryptoAPI Engine functionality.

Chapter 3, “Installing the CryptoAPI Engine Package Files” describes how to install the CryptoAPI Engine software offering.

Chapter 4, “Test the Network Connection” gives instructions for testing the CryptoAPI Engine installation and network interface.

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 6 Exar Confidential Related Documents

The following documents can be used to supplement this document.

CryptoAPI Engine 1.1.1 Release Notes, RLN-0003 CryptoAPI Engine 1.1.1 Getting Started Guide, USR-0011 CryptoAPI Engine 1.1.0 Performance Application Note, APN-0008 Express DX SDK 1.3.0L Getting Started Guide, UG-0208

Customer Support

For technical support about this product, please contact your local Exar sales office, representative, or distributor.

For general information about Exar and Exar products refer to: www.exar.com

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 7 Exar Confidential Glossary

Term Definition 3DES Triple DES AAD Additional Authenticated Data AES Advanced Encryption Standard AH Authentication Header API Application Programming Interface CBC Cipher Block Chaining encryption mode CTR Counter encryption mode DES Data Encryption Standard ECB Electronic Codebook encryption mode ECPK Elliptical Curve Public Key eLZS Enhanced Lempel-Ziv-Stac Compression ESP Encapsulating Security Payload GCM Galois Counter Mode HIV Hash Initialization Vector HMAC Hash Message Authentication Code LZS Lempel-Ziv-Stac Compression SA Security Association SAD Security Association Database SPD Security Policy Database SHA Secure Hash Algorithm VPN Virtual Private Network XTS XEX-based Tweaked CodeBook mode (TCB) with CipherText Stealing (CTS), or XEX-TCB-CTS

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 8 Exar Confidential 1 Introduction

Welcome to the CryptoAPI Engine Getting Started Guide for release version 1.1.1. This guide is intended to familiarize you with the components of the CryptoAPI Engine software package.

Note: The Express DX card and Software Development Kit (SDK) version 1.3.0L must be installed prior to installing the CryptoAPI Engine software package. Refer to the Express DX SDK 1.3.0L Getting Started Guide, UG-0208, for details on how to install the Express DX card and SDK.

The CryptoAPI Engine software package is designed to support the following Exar hardware products:

• 8201, 8202, 8203, 8204 processor (820x) • Express DX 1710, 1720, 1730, 1740 cards (DX 17xx) • Express DX 1825, 1835, 1845 cards (DX 18xx)

This guide will walk you through the process of installing and bringing up the CryptoAPI Engine software package. In this guide, you will:

• Download and install an open source Linux IPsec implementation package such as OpenSwan, or StrongSwan • Install and test Exar’s proprietary CryptoAPI Engine offering

After reading the Express DX SDK Getting Started Guide and this guide, you will be familiar with the basic features and operation of both the software and the hardware. You will be ready to begin developing your own custom application(s).

1.1 Requirements

Before proceeding, make sure you have the following items:

• Installed Express DX SDK version 1.3.0L or later • Installed Exar Express DX card • Operating system - Linux kernel 2.6.35 (RHEL 5.5 upgrade) or later • GNU make, GNU gcc, GNU libc

Refer to the CryptoAPI Engine Release Notes, RLN-0003, for important information regarding the compatibility of the Linux kernel version and the OpenSwan or StrongSwan library version.

Documentation

CryptoAPI Engine 1.1.1 Release Notes, RLN-0003 CryptoAPI Engine 1.1.1 Getting Started Guide, USR-0011 CryptoAPI Engine 1.1.0 Performance Application Note, APN-0008

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 9 Exar Confidential 1.2 Documentation Overview

This section provides an index of the available documentation, a description of individual document contents and how to use the document set.

Exar documentation identifiers such as RLN-0003-A01 include the following information:

“RLN”: document type in the first two letters of the identifier,

APN = Application Note USR = User Guide RLN = Release Note

“0003”: four numbers that indicate the document number

“-A01”: the document release number. The first alpha character indicates the major document release version; the second two integers indicate the minor document release number. Initial revisions start at A01 and increment.

Where to find the documentation:

All released Exar documentation is available on Exar’s Extranet. An account can be requested from the main page of the Exar web site http://www.exar.com. Click on the Extranet Login button to bring up the login page.

How to use the documentation:

System and software designers should reference the CryptoAPI Engine Getting Started User Guide, USR-0011, for directions on how to install the CryptoAPI Engine software package. The CryptoAPI Engine Release Notes, RLN-0003, should be read for deviations in usage and features to the CryptoAPI Engine software package. The CryptoAPI Engine Performance Application Note, APN-0008, gives performance benchmark data for the CryptoAPI Engine running on select DX cards.

1.2.1 Software Documents

USR-0011, CryptoAPI Engine 1.1.1 Getting Started User Guide

This document should be used as a reference to install the CryptoAPI Engine software package after the DX hardware and SDK have been installed. The Getting Started Guide introduces the product documentation and gives a brief overview of the Cryp- toAPI Engine software package. Detailed instructions are given for installing the Cryp- toAPI Engine software package.

1.2.2 System Documents

RLN-0003, CryptoAPI Engine 1.1.1 Release Notes

The CryptoAPI Engine 1.1.1 Release Notes document contains release specific information about the CryptoAPI Engine software package. Software engineers should always carefully read the release notes. Project managers should also inspect the release

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 10 Exar Confidential notes in order to assess the impact of any defects or limitations. The document covers late breaking information about the release not covered in other documents, such as new features, changes since the last release, and limitations of the current release.

APN-0008, CryptoAPI Engine 1.1.0 Performance Application Note

The CryptoAPI Engine 1.1.0 Performance Application Note document contains release specific performance data for the CryptoAPI Engine software package for select DX cards. This document also describes the factors that affect performance and the performance measurement procedure, and lists the exact platforms on which the performance tests were run.

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 11 Exar Confidential 2 Overview

Exar’s CryptoAPI Engine software offering provides a transparent interface between the standard Linux Crypto API and Exar’s DX hardware acceleration cards.

This chapter begins with a general discussion of IPsec, followed by a description of Exar’s CryptoAPI Engine software and the Linux Crypto API.

2.1 IPsec

Internet Protocol Security (IPsec), is a set of protocols developed by the IETF to support secure exchange of packets at the IP layer. IPsec has been widely deployed to implement Virtual Private Networks (VPNs).

IPsec supports two encryption modes: Transport and Tunnel. Transport mode encrypts only the data portion (payload) of each packet, but leaves the header untouched. The more secure Tunnel mode encrypts both the header and the payload. On the receiving side, an IPsec-compliant device decrypts each packet. Exar’s CryptoAPI solution supports both transport and tunnel modes.

Sending and receiving devices using IPsec must negotiate a shared key. The shared key is established through a protocol known as Internet Key Exchange (IKE).

Most Linux distributions support IPsec by default. View the .configure file to confirm that Linux IPsec and the IPsec tool Netkey are supported. If they are not, enable the following in the .configure file and then compile and install the Linux kernel.

Networking support (NET) [Y/n/?] y * * Networking options * PF_KEY sockets (NET_KEY) [Y/n/m/?] y IP: AH transformation (INET_AH) [Y/n/m/?] y IP: ESP transformation (INET_ESP) [Y/n/m/?] y IP: IPsec user configuration interface (XFRM_USER) [Y/n/m/?] y

…

Netkey is native to the Linux kernel for kernel versions 2.6 and later. Netkey utilizes the Linux Crypto API to implement IPsec.

Linux IPsec implementations such as OpenSwan and StrongSwan are commonly used to encrypt VPNs or local private networks. These Linux IPsec implementations have an IKE daemon such as Pluto or Charon that uses NetLink XFRM to manage the (Security Policy Database) SPD and the Security Association Database (SAD) in the kernel. The policies are configured in the file ipsec.conf. The security association (SA) is negotiated with the peer following a matched policy. Both OpenSwan and StrongSwan only support automatic SAs; manual SAs are not supported.

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 12 Exar Confidential 2.2 Exar’s CryptoAPI Engine Software Offering

Exar’s CryptoAPI Engine solution consists of the following:

• Express DX 17xx or DX 18xx card • Express DX SDK version 1.3.0L • Linux Kernel that supports the Express DX SDK and CryptoAPI Engine package (see Chapter 1) • Linux IPsec implementation, one of: • OpenSwan version 2.6.32 or later This software should be downloaded from the OpenSwan web site: www.openswan.org • StrongSwan version 4.5.1 or later This software should be downloaded from the StrongSwan web site: www.strongswan.org • A generic application using the Linux crypto API This software should be provided by the customer. • Linux Crypto API The Linux Crypto API as a cryptography framework is part of the Linux kernel. The Linux kernel version must be 2.6.35 or later. • CryptoAPI Engine version 1.1.1 The CryptoAPI Engine package is an Exar software package that was written to interface the Linux Crypto API with the DX family of acceler- ator cards.

Figure 2-1 shows the relationship between these components.

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 13 Exar Confidential Figure 2-1. CryptoAPI Package Components

The CryptoAPI Engine interfaces to Express DX SDK Raw Acceleration API.

The Linux Crypto API software generates a Linux kernel module that will accelerate the IPsec algorithms listed below. Key sizes of 128, 192, 256 are supported for all AES algorithms.

Authenticated Encryption with Associated Data (AEAD):

• AES-GCM • AES-CBC+SHA1 • AES-CBC+SHA256

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 14 Exar Confidential • AES-CBC+MD5 • AES-CBC+AES-XCBC • 3DES-CBC+SHA1 • 3DES-CBC+SHA256 • 3DES-CBC+MD5 • 3DES-CBC+AES-XCBC • AES-CTR+SHA1 • AES- CTR+SHA256 • AES- CTR+MD5 • AES- CTR+AES-XCBC

Encryption only:

• AES-CBC • AES-CTR • 3DES-CBC

Hash:

• HMAC-SHA1 • HMAC-MD5 • HMAC-SHA256 • AES-XCBC

In addition, both Encapsulating Security Payload (ESP) and Authentication Header (AH) modes are supported.

2.3 Linux Crypto API Overview

The Crypto API was added to Linux kernel versions 2.6 and later to add support for cryptographic functionality to the main Linux kernel. The Crypto API unifies the interface between the kernel modules using crypto routines and other kernel modules that provide routines such as cipher and hash.

By default, the Linux Crypto API uses a software implementation to perform crypto operations. Once the Exar CryptoAPI Engine is registered with the Linux Crypto API, the Linux Crypto API will call the CryptoAPI Engine for crypto operations. The crypto functions are then performed on the DX card, enabling fast, hardware data offload.

As shown in Figure 2-1, the API layering is conceptually:

Transform API: the user interface Transform Operations: cipher, digest, or compression Algorithm API: for registering the algorithms

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 15 Exar Confidential This approach allows the user interface and algorithm registration API to be very simple, and hides the core logic from both.

Most Linux distributions support the Crypto API by default. View the .configure file to confirm that the Linux Crypto API is supported. If it is not, enable the following features in the .configure file of the Linux kernel and then compile and install the Linux kernel.

Cryptographic API (CRYPTO) [Y/n/?] y HMAC support (CRYPTO_HMAC) [Y/n/?] y Null algorithms (CRYPTO_NULL) [Y/n/m/?] y MD5 digest algorithm (CRYPTO_MD5) [Y/n/m/?] y SHA1 digest algorithm (CRYPTO_SHA1) [Y/n/m/?] y DES and Triple DES EDE cipher algorithms (CRYPTO_DES) [Y/n/m/?] y AES cipher algorithms (CRYPTO_AES) [Y/n/m/?] y …

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 16 Exar Confidential 3 Installing the CryptoAPI Engine Package Files

This chapter describes how to install the CryptoAPI Engine software package.

Warning The Exar Express DX card and Software Development Kit (SDK) must be installed before the CryptoAPI Engine software is installed. For instructions, please refer to the Express DX SDK Getting Started Guide.

3.1 Install the IPsec Implementation Package

Refer to the online documentation for the applicable IPsec implementation package to install the OpenSwan, or StrongSwan. Refer to the CryptoAPI Engine Release Notes, RLN- 0003, for compatibility of the Linux kernel version and the OpenSwan or StrongSwan library versions.

3.2 Install the CryptoAPI Engine Software

Before building the CryptoAPI Engine, the Exar Express DX SDK package must have been unpackaged and built. The instructions below assume that the DX SDK is located in the directory /home/panther_sdk. Be sure to follow the instructions in the Express DX SDK 1.3.0L Getting Started Guide, UG-0208, in order to properly load the driver kernel modules.

! Caution The order of operation is very important. The CryptoAPI Engine package must be loaded before starting the IPsec tunnel, otherwise the default kernel crypto module will be used by the system.

To install the CryptoAPI Engine package Step 1 Unpackage the tar file The CryptoAPI Engine package can be saved to any location on the system. Create a working directory and copy the package files to the new directory. mkdir /home/exar_crypto_driver cp yourpath/CryptoAPI_Engine_V1.1.1_20140805.tar.gz exar_crypto_driver/ cd /home/exar_crypto_driver/ tar zvxf CryptoAPI_Engine_V1.1.1_20140805.tar.gz

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 17 Exar Confidential Step 2 Edit the Makefile to update the DX SDK root directory path In the Makefile, replace “Exar_SDK_DIR” with the SDK root directory path.EXAR_SDK_DIR ?= /home/panther_sdk Step 3 Build Build the crypto driver module. make

The kernel module that is built is called exar_crypto_driver.ko. Step 4 Insert the built module The DX SDK driver must be installed before loading the CryptoAPI Engine software, otherwise the insmod command will fail. For applications that support HMAC-hash, type the command: insmod exar_crypto_driver.ko hmac=on

Note that registering the asynchronous HMAC-hash algorithms may degrade the performance of other registered algorithms with small packet sizes (<=512 bytes). This is due to a performance issue with the Linux Crypto API asynchronous HMAC-hash. For all other applications, simply type: insmod exar_crypto_driver.ko Step 5 Confirm the Build After the module is loaded, type dmesg to confirm the build. dmesg

dre_drv.Exar_Crypto_Driver_Loaded.

Execute a cat /proc/crypto command to view information about the algorithms supported by the driver. name : rfc4106(gcm(aes)) driver : exar-crypto module : exar_crypto_driver priority : 50000 refcnt : 1 selftest : passed type : aead async : yes blocksize : 16 ivsize : 8 maxauthsize : 16 geniv :

name : authenc(hmac(sha256),cbc(des3_ede)) driver : exar-crypto module : exar_crypto_driver priority : 50000 refcnt : 1 selftest : passed type : aead async : yes

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 18 Exar Confidential blocksize : 8 ivsize : 8 maxauthsize : 32 geniv :

name : authenc(hmac(sha256),cbc(aes)) driver : exar-crypto module : exar_crypto_driver priority : 50000 refcnt : 1 selftest : passed type : aead async : yes blocksize : 16 ivsize : 16 maxauthsize : 32 geniv :

All log messages from the crypto driver module are dumped into the file /var/log/messages.

The Exar Express DX SDK modules must be installed before the crypto driver is built. If the dre_drv modules is not present, the following errors will be displayed: exar_crypto_driver: Unknown symbol DRE_rawSessPacketRetrieve (err 0) exar_crypto_driver: Unknown symbol DRE_rawSymKeySet (err 0) exar_crypto_driver: Unknown symbol DRE_rawSessSubmitAsync (err 0) exar_crypto_driver: Unknown symbol DRE_rawSymKeyDestroy (err 0) exar_crypto_driver: Unknown symbol DRE_rawSessClose (err 0) exar_crypto_driver: Unknown symbol DRE_rawSessOpen (err 0)

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 19 Exar Confidential 4 Test the Network Connection

The IPsec VPN network connection can be tested using an IP routing tool, OpenSwan or StrongSwan tool.

Figure 4-1 shows the network topology for a typical site-to-site tunnel mode IPsec-VPN test environment. For the sake of convenience, the host machines labeled 10.0.0.2 and 10.10.10.2 may be IXIA traffic generator sender and receiver ports.

Figure 4-1. Test Network Topology

4.1 IP Routing Tool Test

The IPsec-VPN test environment can be tested using an IP routing tool, such as ip xfrm. The tool ip xfrm manipulates the SPD and SAD tables in the kernel through the Netlink XFRM interface/socket. It is only able to create a manual SA.

Shell script files can be created for each of the test machines to test the 3DES-CBC-HMAC- MD5 algorithm.

Example contents of a shell script for test machine (IP addr 172.18.12.97): echo 1 > /proc/sys/net/ipv4/ip_forward #SAs ip xfrm state add src 172.18.12.101 dst 172.18.12.97 proto esp spi 0x201 mode tunnel enc des3_ede 0xf6ddb555acfd9d77b03ea3843f2653255afe8eb5573965df auth md5 0x96358c90783bbfa3d7b196ceabe0536b

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 20 Exar Confidential ip xfrm state add src 172.18.12.97 dst 172.18.12.101 proto esp spi 0x202 mode tunnel enc des3_ede 0xf6ddb555acfd9d77b03ea3843f2653255afe8eb5573965df auth md5 0x96358c90783bbfa3d7b196ceabe0536b #SPs ip xfrm policy add dir out src 10.0.0.0/24 dst 10.10.10.0/24 tmpl src 172.18.12.97 dst 172.18.12.101 proto esp mode tunnel priority 1234 ip xfrm policy add dir fwd src 10.10.10.0/24 dst 10.0.0.0/24 tmpl src 172.18.12.101 dst 172.18.12.97 proto esp mode tunnel priority 1234 ip xfrm policy add dir in src 10.10.10.0/24 dst 10.0.0.0/24 tmpl src 172.18.12.101 dst 172.18.12.97 proto esp mode tunnel priority 1234

Example contents of a shell script for test machine (IP addr 172.18.12.101): echo 1 > /proc/sys/net/ipv4/ip_forward #SAs ip xfrm state add src 172.18.12.101 dst 172.18.12.97 proto esp spi 0x201 mode tunnel enc des3_ede 0xf6ddb555acfd9d77b03ea3843f2653255afe8eb5573965df auth md5 0x96358c90783bbfa3d7b196ceabe0536b ip xfrm state add src 172.18.12.97 dst 172.18.12.101 proto esp spi 0x202 mode tunnel enc des3_ede 0xf6ddb555acfd9d77b03ea3843f2653255afe8eb5573965df auth md5 0x96358c90783bbfa3d7b196ceabe0536b # SPs ip xfrm policy add dir out src 10.10.10.0/24 dst 10.0.0.0/24 tmpl src 172.18.12.101 dst 172.18.12.97 proto esp mode tunnel priority 1234 ip xfrm policy add dir fwd src 10.0.0.0/24 dst 10.10.10.0/24 tmpl src 172.18.12.97 dst 172.18.12.101 proto esp mode tunnel priority 1234 ip xfrm policy add dir in src 10.0.0.0/24 dst 10.10.10.0/24 tmpl src 172.18.12.97 dst 172.18.12.101 proto esp mode tunnel priority 1234

4.2 Netkey Test

The IPsec-VPN test environment can be tested using the OpenSwan Linux native IPsec stack tool Netkey (not KLIPS from OpenSwan). If not already installed, install Netkey on each test machine.

After successfully installing Netkey, execute an OpenSwan ipsec stop command so that the configuration file /etc/ipsec.conf can be modified. Examples of the IPsec configuration files for each test machine are shown below.

Example contents of an ipsec.conf file for test machine Gateway (IP addr 172.18.12.101):

# /etc/ipsec.conf - Openswan IPsec configuration file # This file: /usr/local/share/doc/openswan/ipsec.conf-sample # # Manual: ipsec.conf.5 version 2.0 # conforms to second version of ipsec.conf specification # basic configuration config setup pluto=yes protostack=netkey conn %default authby=secret

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 21 Exar Confidential auto=route ikev2=never rekey=no conn gw1-test left=172.18.12.101 leftsubnet=10.10.10.0/24 right=172.18.12.97 rightsubnet=10.0.0.0/24 ike=aes256-sha1;modp1024 pfs=yes phase2alg=aes128-sha1;modp2048 type=tunnel aggrmode=no

Example contents of an ipsec.conf file for test machine Gateway (IP addr 172.18.12.97):

# /etc/ipsec.conf - Openswan IPsec configuration file # # Manual: ipsec.conf.5 # # Please place your own config files in /etc/ipsec.d/ ending in .conf version 2.0 # conforms to second version of ipsec.conf specification

# basic configuration config setup pluto=yes protostack=netkey conn %default authby=secret auto=route ikev2=never rekey=no conn gw2-test left=172.18.12.97 leftsubnet=10.0.0.0/24 right=172.18.12.101 rightsubnet=10.10.10.0/24 ike=aes256-sha1;modp1024 pfs=yes phase2alg=aes128-sha1;modp2048 type=tunnel aggrmode=no

After editing the IPsec configuration files, execute an OpenSwan ipsec start command to begin the IPsec service. To confirm that OpenSwan is running normally, review the /var/log/secure file, or issue a command such as:

# On Host1 (10.10.10.2): ping 10.0.0.2 -I 10.10.10.2

# On GateWay2, issue tcpdump:

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 22 Exar Confidential tcpdump -i eth0 -n tcpdump: verbose output suppressed, use -v or -vv for full protocol decode listening on eth0, link-type EN10MB (Ethernet), capture size 96 bytes 12:32:32.747556 IP 172.18.12.101 > 172.18.12.97: isakmp: phase 1 I ident 12:32:32.749684 IP 172.18.12.97 > 172.18.12.101: isakmp: phase 1 R ident 12:32:32.749012 IP 172.18.12.101 > 172.18.12.97: isakmp: phase 1 I ident 12:32:32.751384 IP 172.18.12.97 > 172.18.12.101: isakmp: phase 1 R ident 12:32:32.752499 IP 172.18.12.101 > 172.18.12.97: isakmp: phase 1 I ident[E] 12:32:32.752631 IP 172.18.12.97 > 172.18.12.101: isakmp: phase 1 R ident[E] # IKE Phase I negotiation 12:32:32.756417 IP 172.18.12.101 > 172.18.12.97: isakmp: phase 2/others I oakley- quick[E] 12:32:32.771955 IP 172.18.12.97 > 172.18.12.101: isakmp: phase 2/others R oakley- quick[E] 12:32:32.785060 IP 172.18.12.101 > 172.18.12.97: isakmp: phase 2/others I oakley- quick[E] # IKE Phase II negotiation 12:32:33.747011 IP 172.18.12.101 > 172.18.12.97: ESP(spi=0x787d9b6a,seq=0x1), length 132 # ESP encoded packet 12:32:33.747011 IP 10.10.10.2 > 10.0.0.2: ICMP echo request, id 23066, seq 2, length 64 # decoded packet, echo request 12:32:33.747109 IP 172.18.12.97 > 172.18.12.101: ESP(spi=0xc7ca319e,seq=0x1), length 132 # ESP encoded echo reply 12:32:34.747075 IP 172.18.12.101 > 172.18.12.97: ESP(spi=0x787d9b6a,seq=0x2), length 132 12:32:34.747075 IP 10.10.10.2 > 10.0.0.2: ICMP echo request, id 23066, seq 3, length 64 12:32:34.747137 IP 172.18.12.97 > 172.18.12.101: ESP(spi=0xc7ca319e,seq=0x2), length 132 12:32:35.747163 IP 172.18.12.101 > 172.18.12.97: ESP(spi=0x787d9b6a,seq=0x3), length 132 12:32:35.747163 IP 10.10.10.2 > 10.0.0.2: ICMP echo request, id 23066, seq 4, length 64 12:32:35.747229 IP 172.18.12.97 > 172.18.12.101: ESP(spi=0xc7ca319e,seq=0x3), length 132 12:32:36.747243 IP 172.18.12.101 > 172.18.12.97: ESP(spi=0x787d9b6a,seq=0x4), length 132 12:32:36.747243 IP 10.10.10.2 > 10.0.0.2: ICMP echo request, id 23066, seq 5, length 64 12:32:36.747298 IP 172.18.12.97 > 172.18.12.101: ESP(spi=0xc7ca319e,seq=0x4), length 132 12:32:37.747324 IP 172.18.12.101 > 172.18.12.97: ESP(spi=0x787d9b6a,seq=0x5), length 132 12:32:37.747324 IP 10.10.10.2 > 10.0.0.2: ICMP echo request, id 23066, seq 6, length 64 12:32:37.747380 IP 172.18.12.97 > 172.18.12.101: ESP(spi=0xc7ca319e,seq=0x5), length 132 …

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 23 Exar Confidential I Document Revision History

This section lists the additions, deletions, and modifications made to this document for each release of this document.

Document Revision A

Initial release.

Document Revision 00 Update 1. Section 1.1 Requirements: changed the required DX SDK to version 1.1.4L. Update 2. Section 2.2 Exar’s IPsec/Crypto: removed interface from IPsec/Crypto API to the QA API as the interface is now to the Raw API. Updated list of supported IPsec algorithms. Update 3. Section 3.2 Install the IPsec/Crypto: changed the name of the package from qat_crytpo_driver to exar_crypto_driver. Added step 2 to edit the Makefile. Changed the name of the built file fromqat_icp_netkey.ko to exar_crypto_driver.ko. Changed the insmod command to insert the module. Updated the message that confirms the build and the potential errors. Document Revision 01 Update 1. Section 1.1 Requirements: updated the supported SDK list to include the words “and later”.

Document Revision 02 Update 1. Updated the package name to “CryptoAPI Engine” throughout. Updated DX SDK supported version to 1.3.0L. Changed document number.

Document Revision 03 Update 1. Updated to CryptoAPI Engine version 1.1.1 throughout.

CryptoAPI Engine 1.1.1 Getting Started User Guide, USR-0011-A03 Page 24 Exar Confidential 48720 Kato Road Fremont, CA 94538 p: 510.668.7000 www.exar.com

Exar Confidential