Openssl Getting Started Guide
OpenSSL Engine 2.0.0
Getting Started
User Guide
Exar Confidential USR-0010-A02 © Exar®, Inc. All rights reserved. 05/14
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
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 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.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 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 ...... 11
2 Overview ...... 12
2.1 Components of the OpenSSL Solution ...... 12
2.2 Exar’s OpenSSL Engine...... 13
3 Installation ...... 15
3.1 Configure the DX SDK Driver Options ...... 15
3.2 Install the OpenSSL Package...... 15
3.3 Install the OpenSSL Engine ...... 16
4 Test and Tune the OpenSSL Engine ...... 19
4.1 Test the Installed OpenSSL Engine...... 19
4.2 Tune the OpenSSL Engine...... 19
I Document Revision History ...... 21
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 4 Exar Confidential List of Figures
Figure 2-1. Protocols Secured by OpenSSL...... 12 Figure 2-2. OpenSSL Package Components ...... 13
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 5 Exar Confidential Preface
About This Document
Welcome to Exar’s OpenSSL Engine Getting Started User Guide for the DX card and XR9240 device family. This document gives instructions on how to install and use the OpenSSL engine version 2.0.0.
The term “DX card” will be used to in this document to refer to the Exar DX2040 card. 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
Document Organization
This document is organized as follows:
Chapter 1, “Introduction” lists the installation requirements and a description of the OpenSSL Engine documentation.
Chapter 2, “Overview” provides an overview of the OpenSSL Engine functionality.
Chapter 3, “Installation”, describes how to install the open source OpenSSL package and Exar’s OpenSSL Engine.
Chapter 4, “Test and Tune the OpenSSL Engine” gives instructions for testing and tuning Exar’s OpenSSL Engine.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 6 Exar Confidential Related Documents
The following documents can be used to supplement this document.
OpenSSL Engine 2.0.0 Release Notes, RLN-0002 OpenSSL Engine 2.0.0 Performance Application Note, APN-0007
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
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 7 Exar Confidential Glossary
Term Definition 3DES Triple DES AAD Additional Authenticated Data AES Advanced Encryption Standard API Application Programming Interface CBC Cipher Block Chaining encryption mode CTR Counter encryption mode DES Data Encryption Standard DIF Data Integrity Field ECB Electronic Codebook encryption mode ECPK Elliptical Curve Public Key eLZS Enhanced Lempel-Ziv-Stac Compression GCM Galois Counter Mode HIV Hash Initialization Vector HMAC Hash Message Authentication Code IV Initial Vector LZS Lempel-Ziv-Stac Compression SHA Secure Hash Algorithm XTS XEX-based Tweaked CodeBook mode (TCB) with CipherText Stealing (CTS), or XEX-TCB-CTS
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 8 Exar Confidential 1 Introduction
Welcome to the OpenSSL Engine Getting Started Guide for release version 2.0.0. This guide is intended to familiarize you with the components of the OpenSSL Engine.
Note: The DX card and Software Development Kit (SDK) version 2.1.0L must be installed and the DX driver loaded prior to installing the OpenSSL Engine. Review “Configure the DX SDK Driver Options” before loading the DX driver. Refer to the DX SDK Getting Started Guide, USR-0038, for details on how to install the DX card and SDK.
The OpenSSL Engine is designed to support the following Exar hardware products:
• XR9240 processor • DX2040 card
This guide will walk you through the process of installing and bringing up the OpenSSL Engine. In this guide, you will:
• Download and install the open source OpenSSL software package • Install and test Exar’s proprietary OpenSSL Engine
After reading the 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 OpenSSL application(s).
1.1 Requirements
Before proceeding, make sure you have the following items:
• Installed Exar DX card • Installed DX SDK 2.1.0L • Operating system - one of: Red Hat Enterprise Linux 6.0 (Kernel 2.6.32-71.el6 for x86 64-bit) Red Hat Enterprise Linux 6.2 (Kernel 2.6.32-220.el6 for x86 64-bit) Red Hat Enterprise Linux 6.3 (Kernel 2.6.32-279.el6 for x86 64bit) Red Hat Enterprise Linux 6.4 (Kernel 2.6.32-358.el6 for x86 64-bit) CentOs release 6.1 (Kernel 2.6.32-131.0.15.el6 for x86 64bit) CentOs release 6.2 (Kernel 2.6.32-220.el6 for x86 64bit) CentOs release 6.3 (Kernel 2.6.32-279.el6 for x86 64bit) CentOS release 6.4 (Kernel 2.6.32-358.el6 for x86_64) SUSE Linux Enterprise Server 10 SP3 (Kernel 2.6.16.60-0.54.5-smp for x86 64-bit) SUSE Linux Enterprise Server 11 SP1 (Kernel 2.6.32.36-0.5-default for x86 64-bit) SUSE Linux Enterprise Server 11 SP2 (Kernel version 3.0.10 for x86 64-bit) Fedora 19 (Kernel version 3.9.4 for x86 64-bit)
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 9 Exar Confidential • GNU make, GNU gcc, GNU libc
The operating systems listed above were tested with the OpenSSL Engine solution. Other Linux distributions and kernel versions may also be compatible with the OpenSSL Engine.
Refer to the OpenSSL Engine Release Notes, RLN-0002, for important information regarding the compatibility of the Linux kernel version and the OpenSSL library version.
Documentation
OpenSSL Engine 2.0.0 Release Notes, RLN-0002 OpenSSL Engine 2.0.0 Getting Started Guide, USR-0010 OpenSSL Engine 2.0.0 Performance Application Note, APN-0007
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-0002-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
“0002”: 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 OpenSSL Engine Getting Started User Guide, USR-0010, for directions on how to install the OpenSSL Engine. The OpenSSL Engine Release Notes, RLN-0002, should be read for deviations in usage and features to the OpenSSL Engine. The OpenSSL Engine Performance Application Note, APN-0007, gives performance benchmark data for the OpenSSL Engine running on select DX cards.
1.2.1 Software Documents
USR-0010, OpenSSL Engine 2.0.0 Getting Started User Guide
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 10 Exar Confidential This document should be used as a reference to install the OpenSSL Engine after the DX hardware and SDK have been installed. The Getting Started Guide introduces the product documentation and gives a brief overview of the OpenSSL Engine. Detailed instructions are given for installing the OpenSSL Engine.
1.2.2 System Documents
RLN-0002, OpenSSL Engine 2.0.0 Release Notes
The OpenSSL Engine 2.0.0 Release Notes document contains release specific informa- tion about the OpenSSL Engine. Software engineers should always carefully read the release notes. Project managers should also inspect the release 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-0007, OpenSSL Engine 2.0.0 Performance Application Note
The OpenSSL Engine 2.0.0 Performance Application Note document contains release specific performance data for the OpenSSL Engine for all DX cards. This document also describes the factors that affect performance and the performance measurement pro- cedure, and lists the exact platforms on which the performance tests were run.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 11 Exar Confidential 2 Overview
2.1 Components of the OpenSSL Solution
OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) network protocols and their related required cryptography standards. Figure 2-1 shows the application layer protocols in the TCP/IP stack that are secured by OpenSSL.
Figure 2-1. Protocols Secured by OpenSSL
Exar’s OpenSSL solution consists of the following:
• DX2040 card or XR9240 device • OpenSSL version 0.9.8 or later This software should be downloaded from the OpenSSL web site: www.openssl.org. There are three parts to the OpenSSL source code: the SSL library, the crypto library, and the OpenSSL application. All three parts are combined in the download package, e.g., openssl- 0.9.8g.tar.gz. No OCF, OCF-Linux patch, or OCF-Linux test tools are required. • OpenSSL Engine version 2.0.0 The OpenSSL Engine is an Exar software package that was written to interface with the DX family of accelerator cards and XR9240 proces- sors. The OpenSSL Engine is a dynamic engine. • DX SDK version 2.1.0L • Linux Kernel that supports the DX SDK and OpenSSL package (see Chapter 1)
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 12 Exar Confidential Figure 2-2 shows the relationship between these components.
Figure 2-2. OpenSSL Package Components
The OpenSSL Engine interfaces to the Raw Acceleration API for Exar’s software development kit. The PK driver manages the creation and removal of the PK keys.
2.2 Exar’s OpenSSL Engine
Exar’s OpenSSL Engine supports a variety of cryptographic algorithms.
The following algorithms are automatically registered when the OpenSSL Engine is built and installed.
• AES128, AES192, AES256 • 3DES • RSA sign and verify • DSA sign and verify
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 13 Exar Confidential •DH
Note that the hash algorithms MD5, SHA1 and SHA256 may be optionally disabled during the build.
The OpenSSL Engine also supports the EC algorithms listed below, however, these algorithms are disabled by default.
• ECDSA sign and verify • ECDH • MD5 • SHA1 • SHA256
For instructions on how to enable the EC algorithms the hash algorithms, please refer to “Build and Install the OpenSSL Engine and PK Driver Components”.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 14 Exar Confidential 3 Installation
This chapter describes how to install the open source OpenSSL software package and install Exar’s OpenSSL Engine.
3.1 Configure the DX SDK Driver Options
The DX SDK driver contains configurable parameters that allow the user to customize the SDK behavior based on the system environment. The DX SDK driver configuration parameters in the file driver.cfg.xml must be reviewed and modified if necessary before building the DX SDK. The DX SDK User Guide, USR-0039, defines the SDK driver configuration file parameters.
For the DX SDK to operate with the OpenSSL Engine 2.0.0, the SDK driver parameter “pcie_error_recovery_enable” must be disabled.
In addition, the user must set the DX SDK driver parameters “max_session_num” and “max_key_num” appropriately. The parameter “max_session_num” limits the number of sessions that may be opened simultaneously. The parameter “max_key_num” limits the number of keys that may be created simultaneously. Please refer to the DX SDK User Guide, USR-0039, for detailed explanation of these parameters.
The default values for “max_session_num” and “max_key_num” are 4096, which represent approximately 1024 SSL handshakes. From a protocol perspective, one successful SSL handshake results in four DX SDK sessions.
Typically, encryption and decryption sessions require a key, while a hash session does not. For simplicity, set “max_key_num” to the same value as “max_session_num”. For example, to support 64K SSL sessions, set “max_session_num” and “max_key_num” to 262144 (65536*4, or 256K).
Note The Exar DX card and Software Development Kit (SDK) must be installed and the DX driver loaded before the OpenSSL engine is installed. For instructions on how to install the DX SDK, please refer to the DX SDK Getting Started Guide, USR-0038. 3.2 Install the OpenSSL Package
Refer to the documentation at www.openssl.org for instructions about installing the OpenSSL package.
Many Linux distributions install OpenSSL by default, however some ECDH and ECDSA algorithm functions may not be included. If hardware offload is required for ECDH or ECDSA algorithms, the entire OpenSSL package must be installed manually.
After building the OpenSSL source code, two library files will be generated: libcrypto.a, and libssl.a.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 15 Exar Confidential The “shared” option is required in the ./config line when building the OpenSSL source code, as shown in the following build example.
./config shared make clean make make test make install
To install multiple OpenSSL instantiations on the same server or to avoid overwriting the existing OpenSSL version, specify an install location using the “--prefix” option, as shown in the examples below.
To install openssl-1.0.0a:
./config shared --prefix=/usr/local/openssl-1.0.0a/
To install openssl-1.0.1c:
./config shared --prefix=/usr/local/openssl-1.0.1c/
After the Makefile has been generated, note the “INSTALLTOP” value, for example “INSTALLTOP=/usr/local/ssl”, which will be used to configure the OpenSSL Engine Makefile.
3.3 Install the OpenSSL Engine
Before building the OpenSSL Engine, the DX SDK must be built and the OpenSSL package must be installed. The OpenSSL Engine is a proprietary Exar component that supports MD5, SHA1, SHA256, 3DES, AES, RSA, DSA, DH, ECDH, ECDSA algorithms.
! Caution Do not place the DX SDK and the OpenSSL Engine in the same directory.
The OpenSSL Engine consist of two components:
1. openssl_eng Exar’s OpenSSL dynamic engine that supports MD5, SHA1, SHA256, AES, 3DES, RSA, DH, DSA, ECDH, ECDSA algorithms.
2. pk_drv A thin driver that manages the creation and removal of the PK keys, and prevents some applications from causing a memory leak.
Extract the OpenSSL Engine Package Step 1 Create a Working Directory mkdir /home/dx_eng cd /home/dx_eng
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 16 Exar Confidential Step 2 Copy the package file to the working directory and untar it cp xxx/openssl_engine-2.0.0_20140516.tar.gz ./ tar xzvf openssl_engine-2.0.0_20140516.tar.gz Step 3 Verify that the files were created In the working directory, enter: ls
Review and Update the Makefile Before installing the OpenSSL engine, the directory paths below listed in the Makefile must be reviewed and edited appropriately. EXAR_DX_SDK_PATH OPENSSL_DYN_ENGINE_PATH OPENSSL_INCLUDE_PATH OPENSSL_LIB_PATH If using the standard OpenSSL package, generally the default values of the three “OPENSSL_” paths will not need to be modified. Step 1 Open the Makefile for editing cd /home/dx_eng vi Makefile Step 2 Edit the DX SDK directory path In the Makefile, set the full path of the Exar DX SDK to the parameter EXAR_DX_SDK_PATH, for example, EXAR_DX_SDK_PATH:= /home/dx_sdk/ Step 3 Set the dynamic engine directory path Set the full path to the directory where the OpenSSL Engine will be installed using the Makefile parameter OPENSSL_DYN_ENGINE_PATH. The path name that should be set depends on the OpenSSL version and operating system, as shown below. For OpenSSL versions 0.9.8b or earlier, the path name should be set to: OPENSSL_DYN_ENGINE_PATH :=/usr/lib/engines/
For OpenSSL versions 0.9.8e or later, the path name for a 32-bit OS should be set to: OPENSSL_DYN_ENGINE_PATH :=/usr/lib/openssl/engines/
And the path name for a 64-bit OS should be set to: OPENSSL_DYN_ENGINE_PATH :=/usr/lib64/openssl/engines/
The default path name in the Makefile is set to: OPENSSL_DYN_ENGINE_PATH :=/usr/lib/engines/
If OpenSSL was installed manually, see the next step for the proper setting of OPENSSL_DYN_ENGINE_PATH. Step 4 Set the Include and Library directory paths Set the paths for OPENSSL_INCLUDE_PATH and OPENSSL_LIB_PATH in the openssl_eng Makefile.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 17 Exar Confidential If OpenSSL was installed manually, the “INSTALLTOP” value in the OpenSSL root pack- age Makefile can be used to generate the three OPENSSL_ paths. For instance, if INSTALLTOP=/usr/local/ssl, then set the paths as follows: OPENSSL_LIB_PATH = /usr/local/ssl/lib/ OPENSSL_DYN_ENGINE_PATH = /usr/local/ssl/lib/engines/ OPENSSL_INCLUDE_PATH= /usr/local/ssl/include/
Build and Install the OpenSSL Engine and PK Driver Components Step 1 Build the engine and pk_drv components Issue a make command to build the OpenSSL Engine and PK driver that is based on the type of algorithms required (see “Exar’s OpenSSL Engine”). For example, to build with ECDH/ECDSA, hash, and RNG algorithms, enter: make clean make ECC_ENABLE=1 HASH_ENABLE=1 RNG_ENABLE=1
Compilation warnings may appear on certain Linux distributions during the make proce- dure. Refer to OpenSSL Engine Release Notes, RLN-0002, for more information. For a list of the Makefile targets and flags, enter: make help Step 2 Install the engine and pk_drv Install the DX OpenSSL engine into the proper directory and load the pk_drv module. make install
To later uninstall the DX OpenSSL engine and unload the pk_drv module, enter: make uninstall
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 18 Exar Confidential 4 Test and Tune the OpenSSL Engine
4.1 Test the Installed OpenSSL Engine
To test the OpenSSL Engine installation, run a single-process command or a multi-process command. Note that a single-process command will only exercise one engine on the DX card, will not fill the command rings, and therefore the performance will be significantly lower than what the DX card can deliver. To maximize performance, run multiple processes.
Specifying “-engine eng_dx“ in the command for the OpenSSL speed test will automatically invoke the “eng_dx” engine.
Instructions for running a single-process command Step 1 Type: openssl speed -evp aes256 -engine eng_dx -elapsed
If OpenSSL was manually installed and INSTALLTOP=/usr/local/ssl, enter instead: /usr/local/ssl/bin/openssl speed -evp aes256 -engine eng_dx -elapsed
The output should be similar to: engine "eng_dx" set. You have chosen to measure elapsed time instead of user CPU time. To get the most accurate results, try to run this program when this computer is idle. Doing aes-256-cbc for 3s on 16 size blocks: ......
Instructions for running a multi-process command Step 1 Type: openssl speed -evp aes256 -engine eng_dx -multi 20 -elapsed
4.2 Tune the OpenSSL Engine
Each algorithm in the OpenSSL engine has a corresponding throttle setting that can be used to individually control the performance of the algorithms based on the block or key size to be processed. If the block or key size is less than or equal to the throttle setting, then the operation will be processed in software rather than in hardware.
Because there is greater overhead for processing small blocks/packets in the DX hardware, the throttle settings allow for small blocks/packets to be more efficiently handled on the CPU. The precise tuning for these throttle controls for optimum performance is application and system dependent. Customers are encouraged to experiment with these settings during performance testing.
The default throttle setting macros are easily located near the top of the file eng_dx.c. Note that the encryption/hash/authenticate throttle settings are given in units of bytes, while the PK/ECPK settings are given in units of bits.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 19 Exar Confidential #define MD5_THROTTLE 2048 #define SHA1_THROTTLE 2048 #define SHA256_THROTTLE 2048 #define AES128_THROTTLE 1024 #define AES192_THROTTLE 1024 #define AES256_THROTTLE 1024 #define DES3_THROTTLE 512
#define RSASIGN_THROTTLE 512 #define RSAVER_THROTTLE 512 #define DH_THROTTLE 512 #define DSASIGN_THROTTLE 512 #define DSAVER_THROTTLE 512
#ifdef ECC_ENABLED #define ECDH_THROTTLE 160 #define ECDSASIGN_THROTTLE 160 #define ECDSAVER_THROTTLE 160 #endif Step 1 Modify the THROTTLE settings #define SHA256_THROTTLE 512
This setting would force SHA256 operations with a block size less than or equal to 512 bytes to be performed in software. Because software capability is server dependent, several algorithm throttle settings should be tested to compare the OpenSSL performance of the software library to the eng_dx hardware performance, and to compare the corresponding CPU utilization. For most modern servers, the software library will have better performance for ECDH and ECDSA algorithms since their key lengths are quite short; offloading these algo- rithms to the eng_dx will typically only have a CPU utilization benefit.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 20 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 00
Initial release.
Document Revision 01 Update 1. Updated for OpenSSL Engine release 1.1.0 and DX SDK 1.1.4L throughout. Update 2. Chapter 2 Overview: updated the architecture drawing to show that the interface to the DX SDK is now through the Raw Acceleration API. Update 3. Section 3.1 Install the OpenSSL Package: added special instructions for ECDH and ECDSA. Update 4. Section 3.2 Install the DX Engine: updated this entire section. Update 5. Section 3.4 Tune the DX Engine: add this section on throttle settings. Document Revision 02 Update 1. Updated for OpenSSL Engine release 1.1.2 and DX SDK 1.2.2L throughout. Update 2. Section 1.1 Requirements: removed SUSE9 and added CentOS 6.2, 6.3. Update 3. Section 2.2 Exar’s OpenSSL Engine: added this new section. Update 4. Section 3.2 Configure the DX SDK Driver Options: added this new section. Update 5. Section 3.3 Install the OpenSSL Engine: updated the tar filename. Under the Build and Install instructions, separated the make commands depending on the type of algos that are required. Document Revision 03 Update 1. Updated for OpenSSL Engine release 1.1.3 and DX SDK 1.3.0L throughout. Update 2. Section 1.1 Requirements: added support for SUSE 9 and CentOS 5.5, kernel 2.6.39.2. Update 3. Section 2.1 Components of the OpenSSL Solution: removed QuickAssist from Figure 2-2. Update 4. Section 3.1 Install the OpenSSL Package: added description of installing multiple versions of OpenSSL. Document Revision A02 Update 1. Updated for OpenSSL Engine release 2.0.0, DX SDK 2.1.0L, and XR9240/ DX2040 hardware throughout. Update 2. Section 2.2 Exar’s OpenSSL Engine: changed MD5, SHA1, SHA256 to be disabled by default. Update 3. Section Install the OpenSSL Engine: updated build examples to reflect that ECDH/ECDSA, hash, and RNG are disabled by default.
OpenSSL Engine 2.0.0 Getting Started User Guide, USR-0010-A02 Page 21 Exar Confidential 48720 Kato Road Fremont, CA 94538 p: 510.668.7000 www.exar.com
Exar Confidential