JCE-Developer - Guide-4 6 0

NAE Developer Guide for the
JCE Provider
Software Version: 4.6.0

Documentation Version: 20070920
Copyright Information
Ingrian Copyright
© 2007 Ingrian Networks, Inc. All rights reserved
This document is subject to change without notice. The user is responsible for complying with all applicable copyright laws. No
part of this document may be reproduced or transmitted in any form or by any means (electronic or otherwise) for any purpose
without the express written permission of Ingrian Networks.
Ingrian Networks may have copyrights, trademarks, and other intellectual property rights in and to the contents of this
document. This document grants no License to such copyrights, trademarks and other intellectual property rights.
Trademark Information
DataSecure, EdgeSecure, i10, i100, i110, i116, i140, i210, i211, i215, i220, i221, i225, i311, i315, i321, i325, i411, i416, i421,
i426 Ingrian, the Ingrian Logo, Ingrian Networks, Network-Attached Encryption, and SiteSecure are trademarks and/or
registered trademarks of Ingrian Networks, Inc.
BEA is a registered trademark of BEA Systems, Inc. Cryptix is a trademark of The Cryptix Foundation Limited. HP-UX is a
trademark of the Hewlett-Packard Company. AIX, DB2, and IBM are registered trademarks of International Business
Machines, Inc. DOS, Microsoft, Microsoft Internet Explorer, Microsoft SQL Server, MSCAPI, .NET, Windows, Windows 2000
Server, Windows 2000 Advanced Server, and Windows Server 2003 are trademarks of Microsoft Corporation. XML is a
trademark of MIT and a product of the World Wide Web Consortium (W3C). Firefox and Mozilla are trademarks of The Mozilla
Foundation. Netscape is a registered trademark of Netscape Communications Corporation. UNIX is a registered trademark of
The Open Group. Oracle, Oracle 8i, Oracle 9i, and Oracle 10g are trademarks of the Oracle Corporation. Red Hat Enterprise,
Red Hat Enterprise Linux, and Red Hat Linux are trademarks of Red Hat, Inc. RC4 and RSA are trademarks or registered
trademarks of RSA Security, Inc. JAR, Java, JCE, JDBC, JDK, JVM, Solaris, and Sun are trademarks or registered
trademarks of Sun Microsystems, Inc. Sybase is a registered trademark of Sybase, Inc. Linux is a registered trademark of
Linus Torvalds. Trustix is a trademark of Trustix AS.
Other product and company names used in this document may be the trademarks of their respective owners.
License Notices
This product contains software that is subject to various public licenses. The source code form of such software and all
derivative forms thereof can be copied from the following website: https://iwsc.ingrian.com/sourcecode.php
Table of Contents
ABOUT THIS GUIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Using This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Notes and Cautions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Contacting Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
CHAPTER 1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
General System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Hardware and Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Ingrian Equipment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Supported Cryptographic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Supported Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Alternate Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Extremely High Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
CHAPTER 2 INSTALLING THE INGRIAN JCE PROVIDER . . . . . . . . . . . . . . 11

Obtaining Provider Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Installing the Ingrian JCE Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Installing the jar Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Updating the Java Security File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Installing the IngrianNAE.properties File . . . . . . . . . . . . . . . . . . . . . .17
Using Unlimited Strength Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
IV TABLE OF CONTENTS
CHAPTER 3 CONFIGURING THE INGRIAN CLIENT . . . . . . . . . . . . . . . . . . 21

IngrianNAE.properties File Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Network Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
NAE Server IP and Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Network Configuration Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Creating a Load Balancing Group . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Enabling Multi–Tier Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . .25
Configuring a Tier for Automatic Failover . . . . . . . . . . . . . . . . . . . . .26
Connection Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Persistent Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Connection Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Connection Read Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Connection Idle Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Connection Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Unreachable Server Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Maximum Server Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Client Certificate Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Client Certificate Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Client Private Key Passphrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Local Encryption Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Symmetric Key Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Symmetric Key Cache Expiration . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Local Crypto Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
SSL/TLS Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
CA Certificate for Server Authentication . . . . . . . . . . . . . . . . . . . . . .32
Client Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Client Private Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Client Private Key Passphrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Logging Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Log Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

V TABLE OF CONTENTS
Log Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Log Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Additional log4j Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Enabling Clients to Manage Keys and Users on the Server . . . . . . . . . . . . . . .36
CHAPTER 4 SETTING UP SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

SSL Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
SSL Configuration Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Creating a Local CA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Creating a Server Certificate Request on the Management Console .42
Signing a Server Certificate Request with a Local CA . . . . . . . . . . . .42
Importing a Server Certificate to the Ingrian Device . . . . . . . . . . . . .43
Downloading the Local CA Certificate . . . . . . . . . . . . . . . . . . . . . . . .44
Adding the CA Certificate to the Java Keystore . . . . . . . . . . . . . . . . .44
SSL Walkthrough for JCE Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
SSL with Client Certificate Authentication Overview . . . . . . . . . . . . . . . . . . .51
SSL with Client Certificate Authentication Procedures . . . . . . . . . . . . . . . . . .53
Generating a Client Certificate Request with Keytool . . . . . . . . . . . .54
Signing a Certificate Request and Downloading the Certificate . . . . .55
Adding the CA and Client Certificates to the Java Keystore . . . . . . .55
Installing a CA Certificate on the Server . . . . . . . . . . . . . . . . . . . . . .56
Adding a CA to a Trusted CA List Profile . . . . . . . . . . . . . . . . . . . . .56
SSL with Client Certificate Authentication Walkthrough for JCE Clients . . .57
CHAPTER 5 USING THE JCE PROVIDER . . . . . . . . . . . . . . . . . . . . . . . . 63

Importing the Ingrian API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Creating an NAESession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Creating a Global Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Creating a Global Session Using SSL with Client Certificates . . . . .65
Creating an Authenticated Session Using an NAE Username and Pass-
word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Creating an Authenticated Session Using SSL with Client Certificates 66
Using Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Creating a Global Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Creating a Key Owned by an NAE User . . . . . . . . . . . . . . . . . . . . . . .69

VI TABLE OF CONTENTS
Creating a Key and Assigning Permissions . . . . . . . . . . . . . . . . . . . .69

Generating a Global RSA Public–Private Key Pair . . . . . . . . . . . . . .70
Exporting a Global Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Exporting a Non-Global Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Importing a Global Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Deleting a Global Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Getting the Size of a Global Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Returning a List of Global Keys on the NAE Server . . . . . . . . . . . . .72
Returning a List of Keys Available to an NAE User . . . . . . . . . . . . .73
Accessing a Non–Global Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Caching Keys on the Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Eligible Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Client Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
API Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Encrypting and Decrypting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Generating a Random IV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Encrypting a Text String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Decrypting a Text String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Encrypting a String and Writing to a File . . . . . . . . . . . . . . . . . . . . . .78
Encrypting a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Generating and Verifying Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . .81
Generating a Digital Signature with an RSA Private Key . . . . . . . . .81
Verifying Signed Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Generating and Verifying a MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Generating a MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Verifying a MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Chaining Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Creating Chained Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Returning an Intermediate Result in a Chain of Operations . . . . . . . .85
CHAPTER 6 USING THE SAMPLE APPLICATIONS. . . . . . . . . . . . . . . . . . . 87

About the CryptoTool Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Examples of CryptoTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Key Management Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91

VII TABLE OF CONTENTS
Cryptographic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

About the Tomcat Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Configuring the Tomcat Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Running the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
INDEX99

VIII TABLE OF CONTENTS

About This Guide
This introductory chapter gives a brief summary of the book’s contents, identifies the
audience, explains how to best use the written material, discusses the documentation
conventions used, and provides instructions for contacting technical support.
This chapter includes the following sections:
Using This Guide 2
Organization 2
Documentation Conventions 3
Contacting Technical Support 3

2 ABOUT THIS GUIDE
Using This Guide

Generally speaking, our user guides are written for network administrators, security
engineers, database administrators, application developers, and other technology
professionals responsible for daily operations in support of data security. The written
material we provide describes how to configure and operate our products and assumes a
working knowledge of networking, computer security, database management, and
cryptography.
This specific book is designed for advanced developers familiar with the Java
Cryptography Extension, the Ingrian device, and the general system architecture of the
Ingrian DataSecure Platform as documented in the IngrianOS User Guide.
Organization
This user guide is divided into the chapters described below:
Chapter 1, “Overview”
Presents high-level information about the Ingrian JCE Provider.
Chapter 2, “Installing the Ingrian JCE Provider”
Details the installation process.
Chapter 3, “Configuring the Ingrian Client”
Explains how to configure the Ingrian JCE Provider.
Chapter 4, “Setting up SSL”
Discusses how to configure SSL for your DataSecure Platform.
Chapter 5, “Using the JCE Provider”
Describes the classes delivered with the Ingrian software.
Chapter 6, “Using the Sample Applications”
Provides brief examples of how to use the Ingrian JCE Provider to perform basic
connection tasks, work with keys, perform cryptographic operations, and work
with files. The chapter also discusses the sample Tomcat Servlet.

3 ABOUT THIS GUIDE
Documentation Conventions
This section describes the formatting conventions used in this manual to explain special
notes and cautions.
Notes and Cautions

The following paragraph formats are used to highlight information in the text:
Note: A note conveys information that supplements the preceding text. This information
may refer to certain situations or a specific technical setup.
Important! An important note is a very significant piece of information required for the
completion of a task.
Tip: A tip helps you apply the information in the preceding text.
Warning! A warning advises you to exercise care when working around specified
equipment conditions. Heeding a warning can prevent personal injury, system disruption,
or equipment damage.
Contacting Technical Support

If you experience difficulty with the setup or operation of your Ingrian JCE Provider, visit
the Technical Support page on our web site:
http://www.ingrian.com/support/
You can browse knowledge base articles, or file a customer service ticket if needed. If you
do file a ticket, please include as much pertinent information as possible, and include
detailed contact information to help expedite your issue.
You can also contact a Technical Support representative using the email address and phone
numbers below.
support@ingrian.com
(866) INGRIAN (Toll-free in the US)
(650) 261-2499

4 ABOUT THIS GUIDE

CHAPTER 1
Overview
This document describes how to integrate the Ingrian JCE Provider with your back-end
application servers and it gives code samples that illustrate how you might customize the
Ingrian JCE Provider as your application requires. This chapter provides a description of
the high-level architecture of the Ingrian DataSecure Platform and covers the following
topics:
General System Architecture 6
Hardware and Software Requirements 7
Supported Cryptographic Operations 7
Supported Content 8
Alternate Configurations 8
6 OVERVIEW
General System Architecture

The Ingrian DataSecure Platform consists of two required components – the Ingrian
Cryptographic Provider (the JCE Provider in this case) and the NAE Server – and, in some
cases, an optional Database Connector.
The diagram below shows a high-level network diagram of a typical deployment of the
Ingrian Data Privacy Solution. Whenever necessary, the NAE client (application, web,
database servers) makes requests via one of the Ingrian Cryptographic Providers or the
XML interface for cryptographic operations to be performed by the NAE Server. The
NAE Server performs all desired cryptographic operations and returns data to the
application that made the request. At that point, if the client is an application, it might
want to store the data in a database, or it might want to return the data to a client over the
internet. This unique method of providing cryptographic functionality over the network
creates an extremely simple, scalable, and secure solution to backend data encryption,
integrity checking and fingerprinting (hashing). An example configuration is illustrated
below.
Fig. 1.1
Example Deployment of the Ingrian DataSecure Platform
The Ingrian JCE Provider is installed on all the back-end servers that might be making
requests for cryptographic operations. All applications, servlets, or scripts see a
conventional JCE interface and issue simple Java–based (JCE) commands to the NAE
Server to perform cryptographic operations. Instead of bogging down back-end server
applications with cryptographic operations, the NAE Server performs all such operations.

7 OVERVIEW
The performance impact from doing cryptographic operations over a secure connection is
not as significant as you might think because the Ingrian JCE Provider uses a non-
blocking, multi-threaded connection management architecture, long–lived and
configurable SSL sessions, and a JVM–wide global connection resource pool. Because of
this, the communication channel between the Ingrian JCE Provider and the NAE Server is
extremely lightweight. As a result, very low latencies and high throughputs can be
achieved.
Hardware and Software Requirements

The hardware and software required to deploy the Ingrian Data Privacy Solution are listed
below.
Ingrian Equipment
• Ingrian DataSecure Platform: This is available in various hardware configurations and
comes standard with two 10/100 Ethernet interfaces for connecting to the back-end
servers. Options are available for redundant power supplies, redundant fans, and
copper and fiber Gigabit Ethernet versions.
• Ingrian JCE Provider: This is provided in the form of a jar file (IngrianNAE.jar)
signed by Ingrian Networks.
System Requirements
The Ingrian JCE Provider runs on a Java Virtual Machine (JVM) that has installed support
for SSL and Java Cryptographic Extensions (JCE). It is not dependent on the underlying
back-end server.
Supported Cryptographic Operations

The Ingrian JCE Provider exposes functionality to allow the user to implement data
privacy, confidentiality and integrity in a simple, scalable and secure manner. The
operations supported are listed below.
Note: The full Ingrian JCE–based API and all supported operations are available in the
standard Javadoc format.

8 OVERVIEW
Table 1.1
Supported Cryptographic Operations
Security Provided Algorithm Functions Supported
Data Privacy and Confidentiality AES, DESede, DES, • Encrypt
(Symmetric) RC4 • Decrypt
Data Privacy and Confidentiality RSA • Encrypt
(Asymmetric) • Decrypt
Data Integrity HmacSHA1 • MAC
• MAC Verify
Data Signatures RSA • Sign
• Sign Verify
Supported Content
There are no restrictions on the type of data and content that the NAE Server can secure.
Whether it is a 10 byte string of data, a 10K image, a 1 MB text file, a 10MB pdf file, a
financial spreadsheet, or a line of code, the NAE Server can perform all desired
cryptographic operations. In short, the NAE Server can handle any type of data or content.
Note: For files, the Ingrian JCE Provider can be used with the CipherOutputStream
streaming JCE mechanisms, which allow for medium to large files to be protected in an
efficient manner.
Alternate Configurations
This document does not go into the details of how to set up an NAE Server’s IP address
and other basic network settings. This configuration is very straightforward and is detailed
in the IngrianOS User Guide. This document assumes that you are have successfully
configured the System and Network sections on your NAE Servers. This document
provides the configuration information that is pertinent to the standard deployment of the
Ingrian JCE Provider. Please note that there are several alternate configurations that you
might want to deploy, depending on your requirements. Two of these configurations,
high–availability and extremely high load, are described below.
High Availability
The Ingrian DataSecure Platform supports an active–passive configuration. In case of
failure of the active device, the passive device automatically takes over in a VRRP–like
fashion. Of course, the two devices must be configured in exactly the same manner. When

9 OVERVIEW
the Ingrian DataSecure Platform is deployed in High Availability mode, the Ingrian
Cryptographic Provider or Database Connector continues processing requests as normal
on the newly active device (since the change is transparent to the provider).
Please see Chapter 12, “Network Configuration” in the IngrianOS User Guide for more
information.
Extremely High Load

An individual Ingrian device is capable of performing a very high number of
cryptographic transactions per second. If you notice that your performance needs outstrip
the capabilities of an individual Ingrian device, you can address this issue in either of the
ways described below:
• Assign different backend servers different NAE Servers statically by configuring their
IngrianNAE.properties file to point to different IP addresses that correspond to
different NAE Servers.
• In most environments this static partitioning will not lead to the ideal load balancing
across NAE Servers. In this case, the ideal solution is to add multiple IP addresses in
the NAE_IP parameter of the properties file (where each Ingrian device is configured
identically) and enable load balancing. You can do so by editing the
Load_Balancing_Algorithm parameter in the properties file.
Load balancing configuration is described in “Load Balancing” on page 27.

10 OVERVIEW

CHAPTER 2
Installing the Ingrian JCE

Provider
This chapter describes how to obtain, install, upgrade, and uninstall the Ingrian JCE
Provider.
This chapter covers the following topics:
Obtaining Provider Software 12
Installing the Ingrian JCE Provider 13
Using Unlimited Strength Ciphers 19

12 INSTALLING THE INGRIAN JCE PROVIDER
Obtaining Provider Software

You can obtain the appropriate installation program by logging into our Customer Support
web site. The installation program adheres to the following naming convention:
version - software - build - file format
Value Description
version The version number of the software.
software The installation program.
The Ingrian JCE Provider is delivered independent
of any other Ingrian Providers.
build The specific build in the release for which the
installer was created.
file format The installation program is delivered in a zip file.
For example,
460-IngrianJCE-4.6.0-003.zip
Important! Our Customer Support web site also includes an md5 signature for each
software download. After downloading the software, you can run the md5sum program to
verify the signature.
You can unzip the archive using any standard archive utility in Windows or Linux/UNIX.
One option for UNIX and Linux environments is Info–Zip, available at http://www.info-
zip.org. Once the utility is set up, extract the files using the following command:
unzip <zip_file>
In both Windows and Linux/UNIX environments, extracting the archive creates the
following directory structure:
/IngrianJCE
/bin
/documentation
/javadoc
/lib
/ext
/samples
/cryptotool
/tomcat_servlet
The IngrianJCE/lib/ext directory contains the Java archives (.jar files) and the
IngrianNAE.properties file. The jar files are described in the following table.

Filename Description
cryptix-jce-api.jar The Cryptix JCE API (mandatory for DB2 deployments and optional for SSL).
IngrianNAE.jar The Java components of the Ingrian JCE Provider.
jaxp.jar Sun’s Java API for XML parsing.
jce1_2_2.jar The Sun JCE Framework.
jcert.jar, jnet.jar, Files required to establish SSL connections in JDK 1.3.x environments.
jsse.jar Note: Do not use jsse.jar with the IBM JDK. Use ibmjsse.jar instead.
log4j-1.2.9.jar The log4j logging application.
parser.jar Sun’s XML parser implementation.
The IngrianJCE/documentation directory contains the Ingrian Javadoc, which gives

a complete description of all the Ingrian classes and methods.
The IngrianJCE/samples directory contains the .class and .java files for the
CryptoTool and Tomcat servlet applications. You can read more in “Using the Sample
Applications” on page 87.
Installing the Ingrian JCE Provider

This section describes the following procedures that must be completed to fully install the
Ingrian JCE Provider:
• Installing the jar Files
• Updating the Java Security File
• Installing the IngrianNAE.properties File
Installing the jar Files

All of the Java components of the Ingrian JCE Provider are in the IngrianJCE/lib/ext
folder. The sections below list the files you need and the directories in which they must be
installed. Follow the instructions appropriate for your Java version.
Files Needed For J2SE/J2EE Version 1.4.x and 1.5.x
To use the Ingrian JCE Provider with J2SE/J2EE version 1.4.x or 1.5.x, you must install
the following jar files in the <jre-home>/lib/ext directory:
• IngrianNAE.jar – to access the Ingrian Java components.
• log4j-1.2.9.jar – to enable logging.

Files Needed for J2SE/J2EE Version 1.3.x
To use the Ingrian JCE Provider with J2SE/J2EE version 1.3.x, you must install the
following jar files in the <jre-home>/lib/ext directory:
• IngrianNAE.jar – to access the Ingrian Java components.
• log4j-1.2.9.jar – to enable logging.
• jce1_2_2.jar – to access the Sun JCE Framework.
• parser.jar and jaxp.jar – to enable Sun’s XML parser.
• jcert.jar, jnet.jar, and jsse.jar – to establish SSL connections.
The files above are required; the file below is required if you are using IBM JDK 1.3.x and
want to use SSL between the Ingrian JCE Provider and the NAE Server. We do not
distribute this file; you must obtain it from IBM.
• ibmjsse.jar
Files Needed to Improve SSL Performance
As part of the SSL handshake, the Ingrian JCE Provider must be able to generate random
bytes. To do this, the Ingrian JCE Provider first looks for the Cryptix JCE Provider; if it
cannot find the Cryptix JCE Provider, it uses the Sun JCE Provider. The Cryptix JCE
Provider is more efficient and offers better performance than the Sun JCE Provider. For
this reason, it is recommended, though not required, that you copy the cryptix-jce-
api.jar file to <jre-home>/lib/ext .
Updating the Java Security File

To use the Ingrian JCE Provider you must update the java.security file. You can do
this entry manually or programmatically at runtime. When using Sun J2SE/J2EE or
Cryptix, you must also add those providers to java.security.
This section provides instructions for:
• Manually Adding the Ingrian Provider
• Manually Adding the Ingrian Provider When Using Sun J2SE/J2EE
• Adding the Ingrian Provider Programmatically
• Adding the Cryptix JCE Provider

Manually Adding the Ingrian Provider
To manually add the Ingrian JCE Provider to the list of approved providers:
1 Open the java.security file in a text editor. The file is located in the <jre-
home>/lib/security directory.
2 Add the following line to the end of the list of providers:

security.provider.n=com.ingrian.security.nae.IngrianProvider
Where the number n identifies the Ingrian Provider as the last entry on the list. For
example, if there are two providers already listed, you would add the following line:
security.provider.3=com.ingrian.security.nae.IngrianProvider
Important! The Ingrian JCE Provider should follow the other providers in the
java.security file; you might encounter errors otherwise.
3 Save and close the file.
Manually Adding the Ingrian Provider When Using Sun J2SE/J2EE
To manually add the Ingrian JCE Provider to the list of approved providers when using
Sun J2SE/J2EE:
2 Add the following lines to the end of the list of providers. The first line adds the
SunJSSE Provider. The second line adds the Ingrian JCE Provider.
security.provider.n=com.sun.net.ssl.internal.ssl.Provider
security.provider.n+1=com.ingrian.security.nae.IngrianProvider
Where the numbers n and n+1 identify the providers as the last entries on the list. For
example, if there are two providers already listed, you would add the following lines:
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.ingrian.security.nae.IngrianProvider

Adding the Ingrian Provider Programmatically
You would use this option when you are setting the Ingrian properties programmatically.
To add the Ingrian JCE Provider to the list of approved providers programmatically at
runtime:
1 Make any calls to System.setProperty() in your application.
2 Add the following line to your application:
java.security.Security.addProvider(new IngrianProvider());
addProvider() automatically appends the Ingrian Provider to the list of approved

providers.
Note: If you are using Sun J2SE/J2EE you will need to add the SunJSSE Provider.
Adding the Cryptix JCE Provider
The Cryptix JCE Provider is used by the Ingrian Database Connector for DB2, and it can
also be used to improve SSL performance. If you plan to use the Ingrian Database
Connector for DB2, or if you want to realize performance improvements when doing SSL,
you must add the Cryptix JCE Provider to the java.security file.
To add the Cryptix JCE Provider to the list of approved providers:
2 Add the following line to the end of the list of providers:

security.provider.n=cryptix.jce.provider.CryptixCrypto
Where the number n identifies the Cryptix Provider as the last entry on the list. For
example, if there are three providers already listed, you would add the following line:
security.provider.4=cryptix.jce.provider.CryptixCrypto
Important! The Cryptix Provider should be listed after the Ingrian JCE Provider.
3 Save and close the file.

Installing the IngrianNAE.properties File

The Ingrian Properties are listed in the IngrianNAE.properties file and are explained in the
next chapter. These values determine how the Ingrian JCE Provider communicates with
the Ingrian device. You can set these properties in the IngrianNAE.properties file, override
the properties file at runtime, or you can set them programmatically at runtime without
using the properties file.
Important! If you are installing Ingrian JCE Provider as part of an Ingrian Database
Connector for DB2 deployment, it is important that you configure the
IngrianNAE.properties file before you install the client software.
This section provides instructions for:

• Configuring the IngrianNAE.properties File
• Overriding the IngrianNAE.properties File
• Configuring the Parameters Programmatically
Configuring the IngrianNAE.properties File
We provide a default configuration file in the IngrianJCE/lib/ext directory. You

should install this file in the <jre-home>/lib/ext directory, then customize it to meet
the needs of your deployment.
To configure the IngrianNAE.properties file:
1 Open the IngrianNAE.properties file in a text editor.
2 Enter values for the parameters. You must, at minimum, specify a value for the
NAE_IP.1, NAE_Port , Protocol, and Log_File parameters. Information on all of
the parameters is provided later in this chapter.
3 Save your changes.
When you launch the Ingrian JCE Provider, it looks for the IngrianNAE.properties
file in the directory that contains IngrianNAE.jar. The Ingrian provider stores the
parameters and uses them throughout the session.

Overriding the IngrianNAE.properties File
You can override the values in IngrianNAE.properties at runtime.

To override the values in the IngrianNAE.properties file:
1 Include the appropriate calls to the System.setProperty() method for each Ingrian
system property that you want to set in your application.
Warning! The calls to System.setProperty() must occur before any calls that
require the JCE providers. The Ingrian Provider cannot be instantiated properly if
the system properties have not been set.
System.setProperty("com.ingrian.security.nae.NAE_IP.1", "10.20.1.9");
System.setProperty("com.ingrian.security.nae.NAE_Port","9000");
2 Use an addProvider() statement in your application. This will store your new settings.
When you launch the Ingrian JCE Provider, it looks for the IngrianNAE.properties
file in the directory that contains the IngrianNAE.jar. The Provider stores these
parameters. Any parameters passed at runtime override the values contained in the
IngrianNAE.properties file.
Configuring the Parameters Programmatically
You can also set the parameters programmatically at runtime without configuring the
IngrianNAE.properties file. You may opt for this setup if your environment does not
allow you to store a properties file locally.
To configure the parameters programmatically:
system property that you want to set in your application.
Warning! The calls to System.setProperty() must occur before any calls that
require the JCE providers. The Ingrian Provider cannot be instantiated properly if
the system properties have not been set.
System.setProperty("com.ingrian.security.nae.NAE_IP.1", "10.20.1.9");
System.setProperty("com.ingrian.security.nae.NAE_Port","9000");
System.setProperty("com.ingrian.security.nae.Protocol","tcp");

2 Set the Ingrian Provider entry in the java.security file. This statement must occur after
the System.setProperty() calls.
Using Unlimited Strength Ciphers

To use unlimited strength ciphers (e.g. 192- and 256-bit AES keys) you must download the
encryption policy files for your Java implementation.
For a Sun Java implementation, download the Java Cryptography Extension (JCE)
Unlimited Strength Jurisdiction Policy File from
http://java.sun.com/javase/downloads/index.jsp.
For an IBM Java implementation, download the JCE Policy Files from
http://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk
For more information on the IBM download, see
http://www-128.ibm.com/developerworks/java/jdk/security/50/


CHAPTER 3
Configuring the Ingrian Client

This chapter contains detailed instructions on how to configure the Ingrian client. The
majority of the client configuration is done using the parameters found in the
This chapter contains the following topics:
IngrianNAE.properties File Overview 22
Network Configuration 24
Connection Configuration 26
Client Certificate Configuration 30
Local Encryption Configuration 30
SSL/TLS Configuration 31
Logging Configuration 33
Enabling Clients to Manage Keys and Users on the Server 36

22 CONFIGURING THE INGRIAN CLIENT
IngrianNAE.properties File Overview

Once you install the Ingrian JCE Provider, you can customize it to meet the needs of your
environment by modifying the parameters in the IngrianNAE.properties file. The contents
of the file, including the delivered settings but excluding the comments, are shown below.
Version=2.2
NAE_IP.1=
NAE_Port=9000
Protocol=tcp
Use_Persistent_Connections=yes
Size_of_Connection_Pool=300
Load_Balancing_Algorithm=round-robin
Connection_Timeout=0
Connection_Read_Timeout=7000
Connection_Idle_Timeout=600000
Connection_Retry_Interval=600000
Unreachable_Server_Retry_Period=-1
Maximum_Server_Retry_Period=0
EdgeSecure_Name=
Client_Cert_Alias=
Client_Cert_Passphrase=
Key_Store_Location=
Key_Store_Password=
Symmetric_Key_Cache_Enabled=no
Symmetric_Key_Cache_Expiry=43200
Local_Crypto_Provider=
CA_File=
Cert_File=
Key_File=
Passphrase=
Log_Level=LOW
Log_File=
Log_Rotation=Daily
Log_Size_Limit=100k
Log_Config_Advanced=
Note: Version indicates the version of the properties file and should not be modified.
To maintain your existing configuration, the upgrade process does not overwrite your
existing properties file. If you are upgrading, you must manually add any new parameters.
For example, this release includes four new parameters: Symmetric_Key_Cache_
Enabled, Symmetric_Key_Cache_Expiry, Local_Crypto_Provider, and

Log_Config_Advanced. To use the related functionality, your IngrianNAE.properties

file must contain the following lines:
Symmetric_Key_Cache_Enabled=no
Symmetric_Key_Cache_Expiry=43200
Local_Crypto_Provider=
Log_Config_Advanced=
Read the “Local Encryption Configuration” and “Logging Configuration” sections for
information on these parameters.
When the client is launched, it checks for the presence of the properties file in the <java-
home>\lib\ext directory; if it finds the properties file, it stores those values and uses
them throughout the session. If the client does not find the properties file, it assumes that
the properties will be set programmatically at runtime. Values set programmatically at
runtime override any existing values in the properties file.
To set the properties at runtime, simply call the setProperty() method of the System
class. For each property, you must make a separate call. You must make these calls before
establishing a connection with the NAE Server. An example is shown below:
System.setProperty(“com.ingrian.security.nae.NAE_IP”, “192.168.1.9”)
Note: The Ingrian parameters are case-sensitive.

If your environment does not allow you to store a properties file locally, as mentioned
above, you can deploy the client without a properties file. To deploy in this way, you must
perform the steps below, in order.
1 Remove the Ingrian Provider from the java.security file located in the <java-
home>/lib/security/ directory.
system property you want to set in your application.
3 Set the Ingrian Provider entry programmatically in the java.security file after you
have set all other properties. To set the Ingrian Provider at runtime, call the
insertProviderAt() method of the Security class, as shown below:
Provider prvdr = new com.ingrian.security.nae.IngrianProvider();
java.security.Security.insertProviderAt(prvdr, n);
where n establishes the Ingrian Provider as the last entry in the list.
Important! Set the system properties before the provider is declared. The Ingrian
Provider cannot be instantiated properly if the system properties have not been
set.

Network Configuration
The Network Configuration settings include the following parameters:
• NAE Server IP and Port
• Protocol
NAE Server IP and Port

Under the Network Configuration heading, specify the IP address and port of the NAE
Server. The default NAE_Port is 9000.
Important! Clients and servers must use the same port.
Protocol
There are two valid values for the Protocol parameter: tcp and ssl. The protocol
specified here is the protocol used to communicate between the client and the NAE
Servers. The SSL option uses TLSv1 as the protocol. By default, TLSv1 is enabled on all
NAE Servers. If you have disabled the use of TLSv1 on your servers, then you cannot
establish SSL connections with between your NAE clients and servers.
Important! Clients and servers must use the same protocol. If your NAE Servers are
listening for SSL requests, and your clients aren’t sending SSL requests, you will
inevitably run into problems.
Tip: Though SSL is the recommended protocol for your production environment, we
recommend that you gradually increase security after confirming connectivity between the
client and the NAE Server. Once you have established a TCP connection between the
client and server, it is safe to move on to SSL. Initially configuring a client under the most
stringent security constraints can complicate troubleshooting.
Network Configuration Procedures

This section discusses:
• Creating a Load Balancing Group
• Enabling Multi–Tier Load Balancing
• Configuring a Tier for Automatic Failover

Creating a Load Balancing Group

You can create a load balancing group by specifying multiple IP addresses in the
NAE_IP.n field. The IP addresses must be separated by a colon, for example:
NAE_IP.1=192.168.1.10:192.168.1.11:192.168.1.12
In a load balancing group, the following parameters will be identical for each NAE Server:
• NAE_Port • Protocol • Connection Configuration
• Client Certificate Configuration • SSL/TLS Configuration • Logging Configuration
If the NAE Servers in your load balancing group are also members of the same cluster, the
consistency of the port and protocol settings are assured.
Important! All members of a load balancing group must be either FIPS-compliant or
non-FIPS. You cannot mix FIPS-compliant and non-FIPS servers.
We recommend that you set the Load Balancing Algorithm parameter to round-robin. For
more information, see “Load Balancing” on page 27
Enabling Multi–Tier Load Balancing

The Multi–Tier Load Balancing feature enables you to create multiple levels of load-
balancing groups, called tiers. When a tier is unreachable, the system fails over to the next.
You can have a maximum of three tiers. You must configure the tiers in order - e.g. you
can’t have tier 3 without having tiers 1 and 2.
The following parameters are tier-aware - the values can vary by tier.
• NAE_Port • Protocol • Size_of_Connection_Pool
• Connection_Timeout • Connection_Read_Timeout • Connection_Idle_Timeout
• Connection_Retry_Interval • Maximum_Server_Retry_Period • Client_Cert_Alias
• Client_Cert_Passphrase • Key_Store_Location • Key_Store_Password
To vary the values by tier, add the suffix .n to the parameter name, where n is the tier
number. You can opt to apply one value to all tiers by omitting the .n suffix.
For example, to set up the port for tiers 1 and 2 and 3, you could set the following:
Port.1=9000
Port.2=9000
Port.3=7000
You could also do this:

Port=9000
Port.3=7000
Because tiers 1 and 2 do not have their own settings, they would use the Port value. Tier
3 would use the Port.3 value.
You could not set the following:
Port.2=9000
Port.3=7000
As there would be no setting for tier 1.
Configuring a Tier for Automatic Failover

You can use the following settings to ensure a speedy failover from one tier to another:
Parameter Value
Connection_Timeout 600
Connection_Read_Timeout 700
Connection_Idle_Timeout 600
Connection_Retry_Interval 600
Unreachable_Server_Retry_Period 800
Maximum_Server_Retry_Period 0
This configuration is useful when testing your Multi-Tier Load Balancing setup.
Connection Configuration
The Connection Configuration settings include the following parameters:
• Persistent Connection
• Connection Pooling
• Load Balancing
• Connection Timeout
• Connection Read Timeout
• Connection Idle Timeout
• Connection Retry
• Unreachable Server Retry
• Maximum Server Retry

Persistent Connection
The Use_Persistent_Connections parameter enables the persistent connections
functionality.
Possible settings are:
• yes (default) - Enables the feature. The client establishes persistent connections with
the NAE Servers.
• no - Disables the feature. A new connection is made for each connection request. The
connection is closed as soon as the client receives the server response.
Connection Pooling
The Size_of_Connection_Pool parameter is the total number of client-server
connections that your configuration could possibly allow. (Not what actually exists at a
given moment.) Connections in the pool can be active or waiting, tcp or ssl. A connection
is created as needed, and the pool scales as needed. So, your pool automatically starts at
size 0, and can grow to whatever value you set here. Once the pool is full, additional
connection requests must wait for an existing connection to close.
Connection pooling is configured on a per-client basis. The size of the pool applies to each
client, it is not a total value for an NAE Server or for a load balancing group. If there are
multiple clients running on the same machine, separate connection pools are maintained
for each client.
Possible settings are:
• Any positive integer. The default is 300.
Load Balancing
The Ingrian JCE Providersupports one load balancing algorithm: round–robin. As such,
there are two possible values for this setting: none and round-robin. Load Balancing is
enabled when you specify multiple IP addresses in the NAE_IP field and a load balancing
algorithm in the Load_Balancing_Algorithm field. The Round Robin load balancing
algorithm keeps load distribution even across all NAE Servers. All servers in a load
balancing group are treated equally by the client. If there are five servers in a load
balancing group, the first request for a cryptographic operation is sent to server 1, the
second request is sent to server 2, and so on, until all five servers have received one
request. The sixth request is then sent to server 1 and the cycle starts again.

If an NAE Server goes down, an exception is thrown for each connection, all open
connections on that server are closed, the operation fails, and the event is logged (if
logging is enabled). It is unlikely that an NAE Server will go down; however, if a server
does go down, it cannot off-load client requests to another NAE Server in the load
balancing group. As such, it is important that your client applications have some provision
for catching exceptions thrown when an NAE Server goes down.
If an NAE Server is unable to fulfill a request, the client takes that server out of the
rotation and sends subsequent requests to the other servers in the load balancing group.
The client waits the time period specified in the Connection_Retry_Interval field
before putting that server back into the rotation. If the server is still unreachable, the client
again marks the server down and takes it out of the rotation.
Connection Timeout
The Connection_Timeout parameter specifies how long the client waits for the TCP
connect() function before timing out. It is recommended that you use the default value of
0, which means that the client waits as long as the operating system’s TCP stack normally
waits on a connect() call.
If your application is time-sensitive, then setting this parameter to a few hundred
milliseconds less than your operating system’s connection timeout parameter makes
connections to a down server fail more quickly, in which case failover happens sooner. If a
connection cannot be established before the timeout expires, then the server is marked as
down and taken out of the rotation.
Connection Read Timeout

The Connection_Read_Timeout parameter is expressed in milliseconds. It must be
greater than or equal to zero. This parameter allows you to control how long the client
waits when reading data from an NAE Server before determining that it is down. Requests
should only time out if the NAE Server is physically down (e.g. powered off, not
responding because of misconfiguration, etc.).
The main purpose of this parameter is to control how you want the client to react when the
NAE Server is down. If you want it to time out eventually and return an error back to your
application, then you should set this value to an appropriate number of milliseconds to
allow for requests to complete in high load and high latency situations.

If you want the client to wait indefinitely until the NAE Server can be reached, set this
value to 0. When this value is set to 0, requests remain outstanding until the request is
successfully satisfied by the NAE Server.
Connection Idle Timeout

The Connection_Idle_Timeout parameter specifies the amount of time connections in
the connection pool can remain idle before the client begins closing them. The value you
specify is in milliseconds; the default value is 600000 (10 minutes).
Note: There are two different connection timeout values that you need to be mindful of:
one timeout value is set on the NAE Server, and the other is set here in the properties file.
It is important that you set the value of the timeout in the properties file to some value less
than what is set on the server. This lets the client control when idle connections are closed.
Otherwise the client can maintain a connection that is closed on the server side, which can
lead to error.
Connection Retry
The Connection_Retry_Interval parameter determines how long the client waits
before trying to reconnect to a disabled server. If one of the NAE servers in a load
balanced configuration is not reachable, the client assumes that the server is down, and
then waits for the specified number of milliseconds before trying to connect to it again.
Setting this value to 0 is equivalent to an infinite retry interval (meaning the disabled
server will never be brought back into use). This value is expressed in milliseconds. It
must be greater than or equal to zero. The default value is 600000 (10 minutes).
Unreachable Server Retry

The Unreachable_Server_Retry_Period parameter specifies the amount of time the
client will spend attempting to establish a connection to a load balancing group. The retry
period is specified in milliseconds. An error is returned after the specified period if no
server in the group is reachable. If logging is enabled, error messages are written to the log
file. Possible settings are:
• -1 (default) - This is the infinite retry interval. The client keeps trying to connect to a
server until a connection is established. This setting is not compatible with multi-tier
load balancing because the load balancer will never switch tiers.
• A positive integer - If multi-tier load balancing is enabled then set this value between
1 and twice the value of the Connection_Retry_Interval.

Maximum Server Retry

The Maximum_Server_Retry_Period parameter specifies the total amount of time that
the client will spend trying to make connections to any server on any tier. This value is
only used when multi-tiered load balancing is enabled. Possible settings are:
• A positive value - The connection manager will try to make connections for at least
the duration set in Maximum_Server_Retry_Period and will return an error if no
connection can be made on the tier in use when the retry period expires.
• -1 (negative 1) - The connection manager will try every server until one answers.
Client Certificate Configuration

The Client Certificate Configuration settings include the following parameters:
• Client Certificate Alias
• Client Private Key Passphrase
Client Certificate Alias

The Client_Cert_Alias parameter specifies which client certificate to send to the
NAE Server when client certificate authentication is enabled on the server. If you have
multiple client certificates in a keystore, you might want to specify which client certificate
is sent to the NAE Server during the SSL handshake. If you do not specify a client
certificate, either in the properties file or programmatically, the first certificate in the
keystore is sent to the NAE Server.
Client Private Key Passphrase

If you specify a value for the Client_Cert_Alias, you should also specify a value for
the Client_Cert_Passphrase. If you do not provide a passphrase associated with that
certificate, the keystore password is used instead.
Local Encryption Configuration

The client key caching feature enables you to store symmetric keys on your client and use
them to perform cryptographic operations locally. When your client application sends a
cryptographic request to the local Ingrian provider, the provider checks if the key caching
feature is enabled. If it is, the provider searches the key cache for the requested key. If the

key is found, the provider downloads the key from the Ingrian device to the key cache and
performs the crypto. The key is stored in the cache for a limited time.
• Symmetric Key Cache
• Symmetric Key Cache Expiration
• Local Crypto Provider
Symmetric Key Cache

This parameter determines if the symmetric key caching feature is enabled. Only
symmetric keys can be cached. Possible settings are:
• no - Key caching is disabled. Remote encryption (encryption performed on the Ingrian
device) is available as normal.
• yes - Key caching is enabled. Protocol must be set to ssl. (And ssl must be
configured.)
• tcp_ok - Key caching is enabled over both tcp and ssl connections.
Symmetric Key Cache Expiration

This parameter determines the minimum amount of time that a key will remain in the client
key cache. At the end of the expiration interval, the key will be purged from the cache the
next time the Ingrian library is called. Possible settings are:
• 0 (infinite timeout) - Keys are never purged from the client cache.
• A positive integer - The default value is 43200 (12 hours).
Local Crypto Provider

This parameter determines the name of the JCE provider that will perform the local
cryptography. The default value is SunJCE or IBMJCE, depending on your JVM.
SSL/TLS Configuration
The parameters listed below affect how SSL connections are established. These properties
only need to be set if you are configuring the Ingrian JCE Provider as part of a DB2
Database Connector installation; otherwise, they are ignored. Additionally, you You can
disregard these sections if you are not using SSL as the protocol between clients and
servers.

• CA Certificate for Server Authentication

• Client Certificate
• Client Private Key
• Client Private Key Passphrase
CA Certificate for Server Authentication

The CA Certificate for Server Authentication section refers to the CA certificate that was
used to sign the server certificate presented by the NAE Server to the client. Because all
NAE Servers in a clustered environment must have an identical configuration, all servers
in the cluster use the same server certificate. As such, you only need to point to one CA
certificate in the CA_File system parameter. If you do not supply the CA certificate that
was used to sign the server certificate used by the NAE Servers, your client applications
cannot establish SSL connections with any of the servers in the cluster. The path to the CA
certificate you specify can be absolute or relative to the application.
File paths can be absolute or relative. Unless otherwise noted, when prompted for a file,
you should specify both a path and file name.
If a local CA on the Ingrian device was used to sign the NAE Server certificate, you can
download the certificate for the local CA, and put that certificate on the local where the
Database Connector is system of the database server installed file of. The path you specify
for the CA_File parameter is the path to the local CA certificate that was used to sign the
NAE Server certificate.
Client Certificate
In addition to using SSL connections between the NAE clients and servers, you can
further require clients to provide a client certificate to authenticate to the servers. The
sections immediately below are used to establish client certificate authentication.
The Client Certificate Configuration section determines which client certificate the client
application provides to the NAE Server when client certificate authentication is required.
The value you supply for the Cert_File parameter should be a path to a valid client
certificate recognized by the NAE Servers. The path to the certificate you specify can be
absolute or relative to the application. Unless otherwise noted, when prompted for a file,
you should specify both a path and file name.

Important! Client certificates must be PEM encoded. There is a line at the top of all
certificates that includes five dashes, the words BEGIN CERTIFICATE, and five more
dashes followed by a carriage return. Likewise, at the end of the certificate, there is a line
that includes five dashes, the words END CERTIFICATE, and five more dashes followed
by a carriage return. If these lines are not a part of the client certificate specified in the
Cert_File section, the certificate cannot be recognized by the Ingrian device. These
same issues pertain to the private key as well. The lines look like the following:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
Client Private Key

The Key_File parameter refers to the private key associated with the client certificate
specified in the Cert_File parameter. This value is required when client certificate
authentication is enabled on the NAE Server.
Client Private Key Passphrase

The Passphrase parameter refers to the passphrase associated with the private key. The
private key should be stored in PKCS #12 format, in which case the private key is
encrypted with a passphrase. If you do NOT provide this passphrase, the Database
Connector attempts to read the passphrase from standard input; this causes the application
to hang.
It is important to remember that the value you provide is case–sensitive. It is also
important to know that the properties file is NOT encrypted; as such, you should make
sure that this file resides in a secure directory and has appropriate permissions so that it is
readable only by the application or user that is supposed to use it.
Logging Configuration
The Logging Configuration section allows you to enable logging on the client machine. If
you experience a situation where you do not understand the error returned by the
application, you should check the log file. It might be the case that the events logged by
the NAE Servers will help you understand the condition that caused the error.
The Logging Configuration section allows you to enable logging on the client machine.
This logging is performed by the Database Connector and records information returned by
the crypto library running inside the database provider. You should not confuse this log
file with the DB Log File, which records data from the Ingrian Bulk Loader.

These properties only need to be set if you are configuring the Ingrian JCE Provider as
part of a DB2 Database Connector installation; otherwise, they are ignored.
The settings that fall into the Logging Configuration section include:
• Log Level
• Log File
• Log Rotation
• Log Size
• Additional log4j Properties
Log Level
The Log_Level parameter determines the level of logging that to be performed by the
client.
Valid values for this parameter are:
• NONE – disables client logging. It is recommended that you not disable logging.
• LOW – only essential events are logged.
• MEDIUM – the client logs error messages and one entry per request.
• HIGH – the client logs error messages and at least three entries per request. Setting
this parameter to high generates a very large number of log entries. This level of
logging is usually reserved for debugging purposes.
Important! The user running your client application must have permission to write to the
log file, and to create new files in the directory where the log file(s) are created.
Log File
The Log_File parameter specifies a name (and possibly a path) for the log file. If you
specify only a name, the log file is created in the directory where the client was installed.
If you specify a path, it can be absolute or relative to the application.
You can create separate log files for each client application by setting the
INGRIAN_LOGFILE_SUFFIX environment variable to a unique value for each
application. When the variable is set, its value is appended to the value set in the
Log_File parameter. For example, if your Log_File parameter is set to /foo/bar/
Logfile. and your application’s INGRIAN_LOGFILE_SUFFIX is set to app1, then that
client’s log file will be written to /foo/bar/Logfile.app1. Likewise, if you set

INGRIAN_LOGFILE_SUFFIX to app2 in a second application, that client’s log file will

appear in /foo/bar/Logfile.app2.
Similarly, the INGRIAN_LOGFILE_PREFIX environment variable enables you to prepend
the value set in the Log_File parameter. To create a log file in /tmp/application1/
Logfile.txt, you would set INGRIAN_LOGFILE_PREFIX to /tmp/application1/
and accept the Log_File default.
Important! Do not use quotes when specifying a path, even if your path has spaces.
Log Rotation
The Log_Rotation parameter specifies whether logs are rotated daily or once they reach
a certain size. By default, logs are rotated daily. If you want them to be rotated once they
reach a certain size, you must specify “SIZE” for this parameter, and then specify a size in
the Log_Size_Limit parameter.
If you specify MaxBackupIndex in your log4j configuration file, that parameter can
override the Log_Rotation and Log_Size_Limit settings. For example, if you rotate
your logs when they reach 10Kb, 100Kb of data would result in 10 log files at 10Kb each.
But, if you also configure MaxBackupIndex to hold 6 files, the same 100Kb of data would
yield only 6 files - the other log files would not be saved.
Log Size
If you want to rotate logs based on the size of the log file, specify a value for the
Log_Size_Limit parameter. This parameter is disregarded if the Log_Rotation is set
to anything other than “SIZE.” Unless you specify otherwise, the log size limit is
expressed in bytes. As such, you can simply enter a number with no units, such as 10000.
Alternatively, you can specify the size in kilobytes (using a number and a unit designator
of “k” or “K”, such as “10k”), or megabytes (using a number and a unit designator of “m”
or “M”, such as “1M”).
Additional log4j Properties

If you are using log4j, set the Log_Config_Advanced parameter to the location and
name of the log4j configuration file. For example, Log_Config_Advanced=/home/
ingrian/JavaApps/log4j.properties.
In the log4j.properties file, there must be at least one line similar to the following:

log4jIngrian.appender.ingrian.logfileAppender.MaxBackupIndex=n
where n is one greater than the maximum number of log files stored on the client file
system.
For information on log4j configuration and functionality, review the log4j documentation.
Enabling Clients to Manage Keys and Users on the

Server
By default the Ingrian device does not allow clients to perform administrative operations
such as creating and deleting keys and users. This setting is controlled by the Allow Key
and Policy Configuration Operations field on the NAE Server page. (From the
Management Console, navigate to Device >> NAE Server >> NAE Server >> NAE
Server Settings.)
Fig. 3.1 Allow Key and Policy Configuration Operations
Only when this checkbox is selected can the client do the following:
• create, delete and import keys.
• create, delete, and modify users and groups*
* This last ability is only available to users who also have administration permission. The
NAE User Administration Permission field is found on the NAE User & Group
Configuration page. (From the Management Console, navigate to Security >> Local Users
& Groups >> Local NAE Users.)

Fig. 3.2 NAE User Administration Permission
To export keys you must select the Allow Key Export field, which is also on the
Management Console’s NAE Server page. Once enabled, the client can export
‘exportable’ keys. (Exportable keys are keys that have the Exportable option selected.)
Fig. 3.3 Exportable Key
By default, the NAE User Administration Permission and Allow Key Export fields are
disabled on all new Ingrian devices.


CHAPTER 4
Setting up SSL
This chapter provides an overview of our SSL and SSL with Client Certificate
Authentication features, and provides a walkthrough of both configuration procedures.
This chapter contains the following topics:
SSL Overview 40
SSL Configuration Procedures 41
SSL Walkthrough for JCE Clients 45
SSL with Client Certificate Authentication Overview 51
SSL with Client Certificate Authentication Procedures 53
SSL with Client Certificate Authentication Walkthrough for JCE Clients 57

40 SETTING UP SSL
SSL Overview
Standard SSL communication requires a certificate that identifies the server. This
certificate is signed by a certificate authority (CA) known to both the server and the client.
During the SSL handshake, the server certificate is passed to the client. The client uses a
copy of the CA certificate to validate the server certificate, thus authenticating the server.
While the CA can be a third-party CA or your corporate CA, you will most likely use a
local CA on the Ingrian device. If you are not using a local CA, consult your CA
documentation for instructions on signing requests and exporting certificates.
Tip: We recommend that you increase security only after confirming network
connectivity. You should establish a TCP connection before enabling SSL. Otherwise, an
unrelated network connection mistake could interfere with your SSL setup and complicate
the troubleshooting process.
To use an SSL connection when communicating with the Ingrian device, you must
configure both the server and the client.
To configure the server, you must:
• Create a server certificate. (If you’re using a cluster, each member must have its own,
unique certificate.)
This may involve the following steps:
• Creating a Local CA.
• Creating a Server Certificate Request on the Management Console.
• Signing a Server Certificate Request with a Local CA.
• Update the NAE Server settings on the Management Console (Device, NAE Server,
NAE Server).
You’ll need to check Use SSL and select your server certificate in the Server
Certificate field.
To configure the client, you must:
• Place a copy of the CA certificate on your client.
• Downloading the Local CA Certificate.
• Adding the CA Certificate to the Java Keystore.
• Update the SSL-related parameters on the client, using one of the following
procedures:

41 SETTING UP SSL
• Update IngrianNAE.properties file as follows:

• Protocol=ssl
• Key_Store_Location=<path and name of keystore that contains
a copy of the server’s local CA>
• Key_Store_Password=<keystore password>
• Set the client values programmatically, by calling the System.setProperty()
method as shown:
• System.setProperty("com.ingrian.security.nae.Protocol",
"ssl");
• System.setProperty("javax.net.ssl.keyStore",
"<YourKeyStorePath>");
• System.setProperty("javax.net.ssl.keyStorePassword",
"<YourKeyStorePassword>");
• Pass the parameters when launching the Java application using the -D flag. For
example,
java -Dcom.ingrian.security.nae.Protocol="ssl"
-Djavax.net.ssl.keyStore="<YourKeyStorePath>"
-Djavax.net.ssl.keyStorePassword="<YourKeyStorePassword>"
<YourApplication>
Note: When using JDK 1.3.x you must also download and install the Java Secure Socket
Extension (JSSE) 1.0.3 package from Sun. For more information on downloading and
installing this software, see “Files Needed for J2SE/J2EE Version 1.3.x” on page 14.
SSL Configuration Procedures

This section describes the procedures you will follow when configuring SSL. It explains
the following processes:
• Creating a Local CA
• Creating a Server Certificate Request on the Management Console
• Signing a Server Certificate Request with a Local CA
• Importing a Server Certificate to the Ingrian Device
• Downloading the Local CA Certificate
• Adding the CA Certificate to the Java Keystore

42 SETTING UP SSL
Creating a Local CA
To create a local CA:
1 Log on to the Management Console as an administrator with Certificate Authorities
access control.
2 Navigate to the Create Local Certificate Authority section on the Certificate and CA
Configuration page (Security, Certificates & CAs, Local CAs).
3 Modify the fields as needed.
4 Select either Self-signed Root CA or Intermediate CA Request as the Certificate
Authority Type.
5 Click Create.
Note: Only a local CA can sign certificate requests on the Ingrian device. If you are using
a CA that does not reside on the Ingrian device you cannot use the Management Console
to sign certificate requests.
Creating a Server Certificate Request on the Management Console

To create a server certificate request on the Management Console:
1 Log on to the Management Console as an administrator with Certificates access
control.
2 Navigate to the Create Certificate Request section of the Certificate Configuration
page (Security, Certificates & CAs, Certificates) and modify the fields as needed.
3 Click Create Certificate Request. This creates the certificate request and places it in
the Certificate List section of the Certificate and CA Configuration page. The new
entry shows that the Certificate Purpose is Certificate Request and that the
Certificate Status is Request Pending.
Signing a Server Certificate Request with a Local CA

To sign a server certificate request with a local CA:

43 SETTING UP SSL
1 Log in to the Management Console as an administrator with Certificates and

Certificate Authorities access control.
2 Navigate to the Certificate List section on the Certificate and CA Configuration page
(Security, Certificates & CAs, Certificates).
3 Select the certificate request and click Properties.
4 Copy the text of the certificate request. The copied text must include the header (-----
BEGIN CERTIFICATE REQUEST-----) and footer (-----END CERTIFICATE
REQUEST-----).
5 Navigate to the Local Certificate Authority List (Security, Certificates & CAs, Local
CAs). Select the local CA and click Sign Request to access the Sign Certificate
Request section.
6 Modify the fields as shown:
• Sign with Certificate Authority - Select the CA that signs the request.
• Certificate Purpose - Select Server.
• Certificate Duration (days) - Enter the life span of the certificate.
• Certificate Request - Paste all text from the certificate request, including the
header and footer.
7 Click Sign Request. This will take you to the CA Certificate Information section.
8 Copy the actual certificate. The copied text must include the header (-----BEGIN
CERTIFICATE-----) and footer (-----END CERTIFICATE-----).
9 Navigate back to the Certificate List section (Security, Certificates & CAs,
Certificates). Select your certificate request and click Properties.
10 Click Install Certificate.
11 Paste the actual certificate in the Certificate Response text box. Click Save. The
Management Console returns you to the Certificate List section. The section will now
show that the Certificate Purpose is Server and that the Certificate Status is Active.
The certificate can now be used as the server certificate for the NAE Server.
Importing a Server Certificate to the Ingrian Device

As an alternative to the certificate creation procedure outlined above, you can import a
certificate to the Ingrian device.

44 SETTING UP SSL
To import a certificate to the Ingrian device:

1 Log in to the Management Console as an administrator with Certificates access
control.
2 Navigate to the Import Certificate section of the Certificate and CA Configuration
page (Security, Certificates & CAs, Certificates).
3 Select the method used to import the certificate file.
4 Enter the name of the file and the private key password.
5 Click the Import Certificate button.
The certificate can now be used as the server certificate for the NAE Server.
Downloading the Local CA Certificate

To download a local CA certificate from the Ingrian device:
1 Log in to the Management Console as an administrator with Certificate Authorities
access control.
2 Navigate to the Local Certificate Authority List section of the Certificates and CA
Configuration page (Security, Certificates & CAs, Local CAs).
3 Select the Local CA and click the Download button to download the file to your
client.
Adding the CA Certificate to the Java Keystore

To add the CA certificate to the keystore:
1 Open a command prompt window on the client and navigate to the Java security
directory. This is typically <JRE-Home>/lib/security.
2 Use the keytool utility to import the CA certificate by issuing the command below.
This statement selects cacerts as the keystore. You create an alias for the CA at this
time.
keytool -import -keystore cacerts -alias <CAAlias> -file <CACertFileName.crt>
3 Enter the keystore password when prompted. By default, the password is “changeit”.
4 Indicate that the CA is trusted, when prompted.

45 SETTING UP SSL
The utility will then issue a message confirming that the certificate has been added to the
keystore. For information about the keytool utility, please refer to Sun’s documentation at:
http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html
SSL Walkthrough for JCE Clients

This walkthrough assumes the following:
• You have read the SSL overview section.
• You have configured a TCP connection between your client and the Ingrian device.
There are a few different ways that you could configure SSL. For example, you can use a
CA that does not reside on the Ingrian device or you can create a new one. This
walkthrough makes such decisions for you. By following these instructions, you will:
• Create a Local CA.
• Create a Certificate Request.
• Create a Server Certificate by signing the Certificate Request with the Local CA.
• Download the Local CA to the client.
• Import the Local CA to the cacerts keystore.
Once you have completed and understood this walkthrough, you might decide to alter
some of the steps to better fit your organization’s policies.
To configure SSL:
1 Log in to the Management Console as an administrator with Certificates, Certificate
Authorities, and NAE Server access controls.
2 Navigate to the Create Local Certificate Authority section (Security, Certificates &
CAs, Local CAs). Enter the values shown below to create a new local CA. Click
Create.

46 SETTING UP SSL
Fig. 4.4
Create Local Certificate Authority
3 Navigate to the Create Certificate Request section (Security, Certificates & CAs,
Certificates). Enter the values shown below to create a request. Click Create
Certificate Request.
Fig. 4.5
Create Certificate Request

47 SETTING UP SSL
4 Select your new certificate request from the Certificate List section (right above the
Create Certificate Request section). Click Properties. Copy the actual request
(highlighted below). Include the header and footer.
Fig. 4.6
Certificate Request Information
5 Navigate back to the Local Certificate Authority List section (Security, Certificates &
CAs, Local CAs). Select your new local CA and click Sign Request.
6 Select Certificate Purpose Server and paste the certificate request into the
Certificate Request field, as shown below.

48 SETTING UP SSL
Fig. 4.7
Sign Certificate Request
8 Copy the actual certificate (highlighted below). Include the header and footer.

49 SETTING UP SSL
Fig. 4.8
CA Certificate Information
9 Navigate back to the Certificate List section (Security, Certificates & CAs,
Certificates). Select your certificate request and click Properties.
10 Click Install Certificate.
11 Paste the actual certificate, as shown below. Click Save.

50 SETTING UP SSL
Fig. 4.9
Certificate Installation
The Certificate List section will now indicate that NewServerCert is an active
certificate.
12 Navigate to the NAE Server Settings section (Device, NAE Server, NAE Server).
Click Edit.
13 Check Use SSL and select your new server certificate in the Server Certificate field.
Click Save.
14 Navigate back to the Local Certificate Authority List section (Security, Certificates &
CAs, Local CAs). Select your new CA and click Download. Place the CA certificate
on your client.
15 Move the certificate from the download location to <Java_Home>\lib\security.
16 Open a command prompt on your client and navigate to

<Java_Home>\lib\security.

51 SETTING UP SSL
17 Install the CA certificate into the cacerts keystore using the command below. Follow
the prompts as shown.
keytool -keystore cacerts -import -alias NewLocalCA -file NewLo-
calCA.crt.cer
Enter keystore password: changeit
...
Trust this certificate?[no]: yes
Certificate was added to keystore
Note: The value for the -file option must reflect your actual filename. The
keystore password must reflect your actual keystore password.
18 Update the following parameters in your IngrianNAE.properties file:

• Protocol=ssl
• Key_Store_Location=<path to Java
Home>\\lib\\security\\cacerts
In Linux/UNIX, this value is <path to Java Home>/lib/security/
cacerts.
• Key_Store_Password=<password>
You can test your configuration by running our CryptoTool application, which is described
in Chapter 6, “Using the Sample Applications”.
If your system requires password authentication, use the following command:
java CryptoTool LIST -auth username:password
If your system permits unauthenticated sessions, you can use the following command:
java CryptoTool LIST
The Ingrian device will return a list of available keys.
SSL with Client Certificate Authentication Overview

This SSL implementation requires that both the server and the client produce certificates.
Each certificate is signed by a trusted CA known to both the server and the client. Most
likely, you will use one CA to sign both certificates. During the SSL handshake, the
certificates are exchanged. Both the client and the server use the CA certificate to validate
one another’s certificate, thus authenticating the other party.
To enable client certificate authentication, you must first successfully configure SSL. Then,
you must make additional configuration changes to the client and server.

52 SETTING UP SSL
For more information about setting up SSL, see “SSL Overview” on page 40.
Tip: We recommend that you increase security only after confirming network
connectivity. You should establish an SSL connection before enabling Client Certificate
Authentication. Otherwise, an SSL configuration mistake could interfere with your Client
Certificate Authentication setup and complicate the troubleshooting process.
To enable SSL with Client Certificate Authentication, you must configure both the client
and the server.
To configure a client, you must:
• Create a client certificate.
• Generating a Client Certificate Request with Keytool.
• Signing a Certificate Request and Downloading the Certificate.
You can create a certificate request using either Java’s keytool utility or OpenSSL.
You can then sign the request with the local CA on the Ingrian device. Once signed,
the certificate request becomes a valid certificate.
If you are not using a local CA, consult your CA documentation for instructions on
signing requests and exporting certificates.
• Place the client certificate and the CA on the client.
This involves the following step:
• Adding the CA and Client Certificates to the Java Keystore.
Important! Be sure that this keystore contains the CA used to sign the server
certificate as well. This will be true if you used the same CA to sign both the client
and server certificates, or you use the same keystore that you used to configure
SSL.
• Update the SSL-related parameters on the client, using one of the following
procedures:
• Update IngrianNAE.properties file as follows:
• Key_Store_Location=<path and name of keystore that contains
a copy of the server’s local CA, the client certificate,
and the CA that signed the client certificate.>
• Key_Store_Password=<keystore password>
• Client_Cert_Alias=<client certificate alias>
• Client_Cert_Password=<client certificate password, if
used>

53 SETTING UP SSL
• Set the client values programmatically, by calling the System.setProperty()

method as shown:
• System.setProperty("javax.net.ssl.keyStore",
"<YourKeyStorePath>");
• System.setProperty("javax.net.ssl.keyStorePassword","<YourK
eyStorePassword>");
• System.setProperty("com.ingrian.security.nae.Client_Cert_Al
ias", "<client cert alias>");
• System.setProperty("com.ingrian.security.nae.Client_Cert_Pa
ssword", "<client cert passphrase>");
• Pass the parameters when launching the Java application using the -D flag. For
example,
java -Djavax.net.ssl.keyStore="<YourKeyStorePath>"
-Djavax.net.ssl.keyStorePassword="<YourKeyStorePassword>"
-Dcom.ingrian.security.nae.Client_Cert_Alias="<client cert alias>"
-Dcom.ingrian.security.nae.Client_Cert_Password="<client cert password"
<YourApplication>
To configure the server, you must:

• Place a copy of the CA certificate on your server.
• Installing a CA Certificate on the Server.
• Adding a CA to a Trusted CA List Profile.
• Update the NAE Server Authentication Settings section on the Management Console
(Device, NAE Server, NAE Server).
You’ll need to select either Used for SSL session only or Used for SSL session and
NAE username in the Client Certificate Authentication field. The profile listed in
the Trusted CA List Profile field must include the CA used to sign the client
certificate. You can update the other fields as needed.
SSL with Client Certificate Authentication

Procedures
This section describes the procedures you will follow when configuring SSL with Client
Certificate Authentication. It explains the following processes:
• Generating a Client Certificate Request with Keytool
• Signing a Certificate Request and Downloading the Certificate

54 SETTING UP SSL
• Adding the CA and Client Certificates to the Java Keystore

• Installing a CA Certificate on the Server
• Adding a CA to a Trusted CA List Profile
Generating a Client Certificate Request with Keytool

Note: You cannot authenticate the client IP address if you use keytool to generate the
client certificate request.
To generate a client certificate request:
1 Open a command prompt window on your client and navigate to the Java security
directory (<Java_Home>\lib\security ).
2 Generate a public/private key pair by issuing the command below. You create an alias
for the key pair at this time.
keytool -keystore <KeystoreName> -genkey
-alias <KeyPairAlias> -keyalg RSA
The key generation process will then request the following data:
• A keystore password.
• The distinguished name.
The distinguished name is a series of fields whose values are incorporated into the
certificate request. These fields include country name, state or province name, city
or locality name, organization name, organizational unit name, and the users first
and last name.
• The key password.
The certificate password must be the same as the keystore password. You can
simply press Return to set the password. You need not retype the keystore
password.
3 Create the certificate request by issuing the command below. Reference the Key Pair
Alias you created above.
keytool -certreq -alias <KeyPairAlias>
-file <CertReqFileName> -keystore <KeystoreName>
You will now have a certificate request in the <CertReqFileName> file.

55 SETTING UP SSL
Signing a Certificate Request and Downloading the Certificate

This section describes how to sign a certificate request with a local CA and then download
the certificate. You must download the certificate immediately after it is signed by the CA.
To sign a certificate request with a local CA:
1 Open the certificate request in a text editor.
2 Copy the text of the certificate request. The copied text must include the header (-----
BEGIN CERTIFICATE REQUEST-----) and the footer (-----END CERTIFICATE
REQUEST-----).
3 Log in to the Ingrian device as an administrator with Certificate Authorities access
control.
4 Navigate to the Local Certificate Authority List (Security, Certificates & CAs, Local
CAs). Select the local CA and click Sign Request to access the Sign Certificate
Request section.
5 Modify the fields as shown:
• Sign with Certificate Authority - Select the CA that signs the request.
• Certificate Purpose - Select Client.
• Certificate Duration (days) - Enter the life span of the certificate.
• Certificate Request - Paste all text from the certificate request, including the
header and footer.
7 Click the Download button to save the certificate on your local machine.
Adding the CA and Client Certificates to the Java Keystore

To add the client certificate to the Java keystore:
1 Open a command prompt window on your client and navigate to the Java security
directory (<Java_Home>\lib\security ).
2 Import the CA certificate that signed the client certificate using the command below.
You create an alias for the CA at this time. When prompted, enter the keystore
password and indicate that the CA is trusted.
keytool -keystore <KeystoreName> -import -alias <CAAlias>
-file <CertFileName.crt>

56 SETTING UP SSL
3 Import the signed client certificate using the following command. Reference the key
pair alias you used to create the certificate request. When prompted, enter the keystore
password.
keytool -keystore <KeystoreName> -alias <KeyPairAlias>
-import -file <CertFileName.crt>
4 Verify that the client certificate was properly imported by executing the following
command. Reference the key pair alias you used above. The system should display the
certificate.
keytool -keystore <KeystoreName> -alias <KeyPairAlias>
-list -v
Important! To enable Client Certificate Authentication, your keystore must have a copy
of the CA certificate that signed the server certificate. If you used one CA to sign both the
server and client certificates, you’ve already accomplished this in step 2. If not, repeat step
2 for the CA certificate that signed the server certificate. (You may have already done this
when configuring SSL.)
Installing a CA Certificate on the Server

If the client certificate was signed by a non-local CA, you must install the CA certificate
on the Ingrian device. To install a CA Certificate:
control.
2 Navigate to the Install CA Certificate section on the Certificate Authority
Configuration page (Security, Certificates & CAs, Known CAs).
3 Enter the Certificate Name.
4 Paste all text from the certificate in the Certificate field, including the header and
footer.
5 Click the Install button.
Adding a CA to a Trusted CA List Profile

To add the CA that signed the client certificate to the Trusted CA List Profile:

57 SETTING UP SSL

control.
2 Navigate to the Trusted Certificate Authority List Profiles section on the Certificate
and CA Configuration page (Security, Certificates & CAs, Trusted CA Lists).
3 Select the profile to which you want to add the CA.
4 Click the Properties button.
5 Click the Edit button in the Trusted Certificate Authority List section.
6 Select the CA in the Available CAs field and click the Add button. This moves your
CA from the Available CAs field to the Trusted CAs field.
7 Click the Save button.
Note: To enable SSL with Client Certificate Authority, the Profile containing the CA that
signed the client certificate must be selected as the Trusted CA List Profile on the NAE
Server Authentication Settings section.
SSL with Client Certificate Authentication

Walkthrough for JCE Clients
This walkthrough assumes the following:
• You have read the SSL with Client Certificate Authentication overview section.
• You have successfully completed the SSL Walkthrough for JCE Clients. You must use
the Local CA created in that walkthrough. The instructions below assume that the
client and server certificates were signed by the same local CA.
There are a few different ways that you could configure SSL with Client Certificate
Authentication. For example, you can use a CA that does not reside on the Ingrian device
or you can create a new one. This walkthrough makes such decisions for you. By
following these instructions, you will:
• Create a new Java keystore named clientcerts.
• Create a Client Certificate Request using keytool.
• Create a Client Certificate by signing the Client Certificate Request with the Local CA
on the Ingrian device.
• Download the client certificate.
• Add the Local CA to the Trusted CA List.

58 SETTING UP SSL
• Download the Local CA to the client.

• Import the Local CA and the client certificate to the clientcerts keystore.
Once you have completed and understood this walkthrough, you might decide to alter
some of the steps to better fit your organization’s policies.
To configure client certificate authentication:
2 Create a new client keystore file named clientcerts.

$ keytool -keystore clientcerts -genkey -alias ccert -keyalg RSA
What is your first and last name?
[Unknown]: clientcerts
What is the name of your organizational unit?
What is the name of your organization?
What is the name of your City or Locality?
What is the name of your State or Province?
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=clientcerts, OU=clientcerts, O=clientcerts, L=clientcerts, ST=
clientcerts, C=US correct?
[no]: yes
Enter key password for <ccert>
(RETURN if same as keystore password):
Do not enter a key password for <ccert> .

3 Generate a client certificate request using the public/private key that was created in
your new keystore.
$ keytool -keystore clientcerts -certreq -alias ccert -file ccert.csr
4 Open the client certificate request file and copy the actual request (highlighted below).
Include the header and footer.

59 SETTING UP SSL
Fig. 4.10
ccert.csr
5 Log in to the Management Console as an adminstrator with Certificate Authorities and

NAE Server access controls.
6 Navigate to the Local Certificate Authority List section (Security, Certificates & CAs,
Local CAs). Select NewLocalCA and click Sign Request. (NewLocalCA is the CA
you created in the SSL Walkthrough.)
7 Select Certificate Purpose Client and paste the certificate request into the Certificate
Request field, as shown below.
Fig. 4.11
Sign Certificate Request
9 Click Download to download your new client certificate (signed.crt) to your client.

60 SETTING UP SSL
10 Return to the Local Certificate Authority List section (click Back on the CA
Certificate Information section).
11 Select NewLocalCA and click Download.
12 Navigate to the Trusted Certificate Authority List Profiles section (Security,

Certificates & CAs, Trusted CA Lists). Select Profile Name Default and click
Properties.
13 Click Edit in the Trusted Certificate Authority List section.
14 Select NewLocalCA in Available CAs and click Add. Click Save.
15 On the client, move the client certificate and the CA certificate from the download
location to <Java_Home>\lib\security.
17 Import the CA certificate (NewLocalCA) into the client keystore. For example,
$ keytool -keystore clientcerts -import -alias NewLocalCA
-file NewLocalCA.crt
Owner:
Issuer:
Serial number: 0
Valid from: mm/dd/yy hh:mm until: mm/dd/yy hh:mm
Certificate fingerprints:
MD5: F0:2D:2F:ED:55:31:6F:F0:A6:E4:AA:37:1F:83:E7:FA
SHA1:8A:08:61:AB:73:32:E2:18:0E:B7:8D:69:2E:91:A6:24:BC:65:C4:DE
Trust this certificate? [no]: yes
Certificate was added to keystore
18 Import the signed client certificate into the client keystore file.
$ keytool -keystore clientcerts -import -alias ccert -file signed.crt
Certificate reply was installed in keystore
19 Verify that the certificates are correctly installed. You will need to see a certificate
chain length of 2, and two certificates: the client certificate and the CA.

61 SETTING UP SSL
$ keytool -keystore clientcerts -alias ccert -list -v

Alias name: ccert
Creation date: Oct 19, 2006
Entry type: keyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=clientcerts, OU=clientcerts, O=clientcerts, L=clientcerts, ST=cli-
entcerts, C=US
Issuer: EMAILADDRESS=NewLocalCA@NewLocalCA.com, CN=NewLocalCA, OU=NewLocal-
CA, O=NewLocalCA, L=NewLocalCA, ST=NewLocalCA, C=US
Serial number: 17
Valid from: 10/18/06 9:11 AM until: 10/7/16 9:11 AM
MD5: 7B:73:86:91:A6:E7:6C:60:0C:28:FA:E2:AF:03:0A:ED
SHA1: 26:63:4C:59:EB:80:A9:16:C9:DB:E4:D4:1D:C0:1A:BD:F3:
1E:B5:A9
Certificate[2]:
Owner: EMAILADDRESS=NewLocalCA@NewLocalCA.com, CN=NewLocalCA, OU=NewLocalCA,
O=NewLocalCA, L=NewLocalCA, ST=NewLocalCA, C=US
Issuer: EMAILADDRESS=NewLocalCA@NewLocalCA.com, CN=NewLocalCA, OU=NewLocal-
CA, O=NewLocalCA, L=NewLocalCA, ST=NewLocalCA, C=US
Serial number: 0
Valid from: 10/9/06 5:13 PM until: 10/7/16 5:13 PM
MD5: F0:2D:2F:ED:55:31:6F:F0:A6:E4:AA:37:1F:83:E7:FA
SHA1: 8A:08:61:AB:73:32:E2:18:0E:B7:8D:69:2E:91:A6:24:BC:65:C4:DE
20 Update the following parameters in the IngrianNAE.properties file:

• Key_Store_Location=<path to Java
Home>\lib\security\clientcerts
• Key_Store_Password=changeit
• Client_Cert_Alias=ccert
• Client_Cert_Passphrase=
Note: The Client_Cert_Passphrase parameter should be set to no value.

21 Return to the Management Console and navigate to the NAE Server Authentication
Settings section (Device Management, NAE Server) and enter the following values:
• Client Certificate Authentication: Used for SSL Session only
• Trusted CA List Profile: Default
Important! The CA used to sign the client certificate must be a member of the
Trusted CA List Profile.
You can test your configuration by running our CryptoTool application, which is described
in Chapter 6, “Using the Sample Applications”.

62 SETTING UP SSL
If your system requires password authentication, use the following command:

java CryptoTool LIST -auth username:password
If your system permits unauthenticated sessions, you can use the following command:
java CryptoTool LIST
The Ingrian device will return a list of available keys.

CHAPTER 5
Using the JCE Provider

This chapter covers some of the basic details of the Ingrian JCE Provider and provides
some examples of commonly used functionality. These examples are provided in the form
of small chunks of code, not working applications. These code samples are for
demonstration purposes only; your application may use the Ingrian Provider in a different
way.
Note: The complete description of all available methods is available in the Javadoc
included with your Ingrian JCE Provider software.
Importing the Ingrian API 64
Creating an NAESession 64
Creating an NAESession 64
Using Keys 67
Caching Keys on the Client 73
Accessing a Non–Global Key 73
Encrypting and Decrypting Data 75
Generating and Verifying Digital Signatures 81
Generating and Verifying a MAC 82
Chaining Operations 84
64 USING THE JCE PROVIDER
Importing the Ingrian API

The interface to the Ingrian JCE Provider only requires a few function calls to perform
cryptographic operations. Before your application can use the Ingrian JCE Provider to
interact with the NAE Server, you have to import the Ingrian package that contains the
Ingrian JCE–related class files. This is done in the first line of code below. This code must
be present in all applications that use the Ingrian JCE Provider. This package is contained
in the signed Ingrian JAR file (IngrianNAE.jar). The next two lines import the other
standard packages needed to perform JCE operations.
Fig. 5.1
Import Ingrian Package
import com.ingrian.security.nae.*;
import java.security.*;
import javax.crypto.*;
Creating an NAESession
At the start of each session, the client can authenticate by passing an NAE username and
password to the server.
An authenticated user:
• Has access to all global keys, all keys owned by the user, and all keys accessible to
groups to which the user belongs.
• Can create keys owned by the user, but cannot create global keys.
Depending on your NAE Server settings, you may not need to pass a username and
password. In this scenario, you are accessing the NAE Server as a global user.
An unauthenticated user, a.k.a. a global user:
• Has access to global keys only.
• Can create global keys only.
The decisions you make regarding authentication must be consistent with the NAE Server
settings. If your client attempts to connect with the NAE Server using an unsupported
method, the session will be terminated. For example, if your client attempts to create a
global session, but global sessions are disabled, the server closes the connection
immediately. Review the NAE Server settings before using the Ingrian JCE Provider.
The NAE Server can be configured to allow clients to:
• Create a global session.

65 U SING THE JCE PROVIDER
• Create a global session while using SSL.*

• Create an authenticated session using an NAE username and password.
• Create an authenticated session using a SSL.*
* The Ingrian device enables you to configure SSL using a server certificate or a server
certificate and a client certificate. Using a server certificate does not affect how the session
is created, only your keystore settings, as explained in Chapter 4, “Setting up SSL”. If you
use client certificates you have a few options when creating a session. These options are
explained below.
This section describes the following procedures:
• Creating a Global Session
• Creating a Global Session Using SSL with Client Certificates
• Creating an Authenticated Session Using an NAE Username and Password
• Creating an Authenticated Session Using SSL with Client Certificates
Creating a Global Session

Any request sent to the NAE Server that does not include a session object is considered
part of a global session.
Thus, if you don’t create a session object, or don’t pass an existing session object with
your cryptographic request, you are using a global session.
Creating a Global Session Using SSL with Client Certificates

If you are using SSL with client certificate authentication, you’ll need to pass a client
certificate, even when creating a global session.
Note: You do not have to pass the client certificate from your application. You can
instead specify the certificate in the IngrianNAE.properties file and not create a
session object at all. For more information on configuring SSL, see Chapter 4, “Setting up
SSL”.
Note: If you do create a session object, remember that any value specified
programmatically overrides any values specified in the properties file.
To create a global session using a client certificate:

1 Create an NAEClientCertificate object.

2 Create an NAESession object and pass the NAEClientCertificate object as a
parameter.
For example:
/* "Cert2" is a valid client cert and "Cert2Password" is the password
associated with that certificate. */
NAEClientCertificate clientCert = new NAEClientCertificate ("Cert2",
"Cert2Password");
NAESession session = NAESession.getSession(clientCert);
Important! To create a global session by sending the NAE Server a client certificate,
Client Certificate Authentication must be enabled on the server and set to “Used for SSL
session only.”
Creating an Authenticated Session Using an NAE Username and

Password
To create an authenticated session using an NAE username and password:
1 Create an NAESession object and pass a valid NAE username and password as
parameters.
For example:
/* "user1" is a valid user and "password1" is the valid password for that
user. */
NAESession session = NAESession.getSession("user1", "password1");
Creating an Authenticated Session Using SSL with Client Certificates

If you are using SSL with client certificate authentication, you’ll need to pass a client
certificate and authenticate.
Note: You do not have to pass the client certificate in your application. You can instead
specify the certificate in the IngrianNAE.properties file and create the authenticated
session as shown above. For more information, see Chapter 4, “Setting up SSL”.
Note: Any value specified programmatically overrides any values specified in the
properties file. For information on specifying a certificate in the properties file, please
refer to “Client Certificate Configuration” on page 30.
To send a client certificate in addition to a valid NAE username and password:

1 Create an NAEClientCertificate object, which includes the alias and password for the
client certificate you want to send to the NAE Server.
2 Create a session object. Pass the NAEClientCertificate object, username and password
as parameters.
For example:
/ "user1" is a valid user and "password1" is the valid password for that
user. "Cert2" is a valid client cert and "Cert2Password" is the password
associated with that certificate. */
NAEClientCertificate clientCert = new NAEClientCertificate ("Cert2",
"Cert2Password");
NAESession session = NAESession.getSession("user1", "password1", cli-
entCert);
Important! To create an authenticate session by send the NAE Server a client certificate,
Client Certificate Authentication must be enabled on the server and set to “Used for SSL
session and NAE username.”
Using Keys
The NAE Server allows you to perform key operations through the Ingrian JCE Provider;
such operations include creating, deleting, importing and exporting keys.
Important! In order to create, delete, import, and export keys from your client, you must
enable the Allow Key and Policy Configuration Operations checkbox on the NAE
Server page. If this option is not enabled, these operation requests will fail.
In addition, you can use the Ingrian JCE Provider to get information about keys that reside
on the NAE Server. When creating keys, the Ingrian JCE Provider requires that you
specify a name for the key; beyond that, you have the option to specify the key length,
whether the key is exportable or deletable, an NAE session object (in case you want to
assign the key an owner), and permissions for the key. If you do not specify a key size, the
NAE Server uses the default key size for the key type.
Note: If a global key is marked as exportable or deletable during generation, then all
users have permission to export or delete that key. If a non-global key is marked as
exportable or deletable, then only the key owner can later export or delete that key.
• Creating a Global Key
• Creating a Key Owned by an NAE User

• Creating a Key and Assigning Permissions

• Generating a Global RSA Public–Private Key Pair
• Exporting a Global Key
• Exporting a Non-Global Key
• Importing a Global Key
• Deleting a Global Key
• Getting the Size of a Global Key
• Returning a List of Global Keys on the NAE Server
• Returning a List of Keys Available to an NAE User
• Accessing a Non–Global Key
Creating a Global Key

To create a global key:
1 Create an NAEParameterSpec object. Pass the keyname as an argument.
2 Obtain an instance of KeyGenerator. Pass the key algorithm as an argument.
3 Call the generateKey method of the KeyGenerator object to create the key.
The following code sample generates a global AES key named “mykey.”
NAEParameterSpec spec = new NAEParameterSpec("mykey");
KeyGenerator keygen = KeyGenerator.getInstance("AES", "IngrianProvid-
er");
keygen.init(spec);
SecretKey aesKey = keygen.generateKey();
To create a global key that is exportable and deletable, you must pass those boolean values
to the NAEParameterSpec object. For example:
NAEParameterSpec spec = new NAEParameterSpec("mykey", true, true);
To create a global key that is exportable, non-deletable, and 256 bits in length, you would
call NAEParameterSpec as follows:
NAEParameterSpec spec = new NAEParameterSpec("mykey", true, false, 256);
When the bit length is not specified, the default key size is used.

Creating a Key Owned by an NAE User

To create a key owned by an NAE user:
1 Create an NAESession object. Pass the NAE username and password as arguments.
You may also need to pass a client certificate, depending on your SSL settings.
2 Create an NAEParameterSpec. Pass the keyname and NAESession object as
arguments.
The following code sample generates an AES key named mykey that is owned by user1:
NAEParameterSpec spec = new NAEParameterSpec("mykey", 256, true, true,
session);
er");
keygen.init(spec);
Creating a Key and Assigning Permissions

To create a key and assign permissions:
1 Create an NAEPermission array. Size the array so that it can hold all of the groups that
will have permission to use this key.
2 Create a new NAEPermission object for each group.
3 Assign permissions for each group by calling the setEncrypt, setDecrypt, setMAC,
setMACV, setSign, setSignV, setUsePrivate, and setUsePublic methods as needed.
Note: The NAEPermission constructor sets all permission to false, by default.
4 Assign the permissions for each group to the NAEPermission array.
5 Create an NAEParameterSpec. Pass the keyname, NAESession object, and
NAEPermission array as parameters.

The following code sample gives encryption permission to Group1 and assigns those
permissions to a new AES key named foo. Note that the permissions are configured first
and then assigned when the key is created.
NAEPermission[] permissions = new NAEPermission[1];
NAEPermission permission_group1 = new NAEPermission("Group1");
permission_group1.setEncrypt(true);
permissions[0] = permission_group1;
NAEParameterSpec spec = new NAEParameterSpec("foo", "session", true,
true, 256, permissions);
er");
keygen.init(spec);
The following code sample gives encryption permission to Group1 and encryption and
decryption permission to Group2. Notice the size of the NAEPermission array, the
additional NAEPermission object, and the calls to the setEncrypt and setDecrypt methods.
NAEPermission[] permissions = new NAEPermission[2];
permission_group2.setDecrypt(true);
Generating a Global RSA Public–Private Key Pair

To generate a global RSA public-private key pair:
1 Create an NAEParameterSpec object. Pass the keyname as an argument.
2 Obtain an instance of KeyPairGenerator. Pass the key type as an argument.
3 Call the genKeyPair method of the KeyPairGenerator object.
The following code sample generates a global RSA public-private key pair named rsakey.
NAEParameterSpec spec = new NAEParameterSpec("rsakey");
KeyPairGenerator keygen = KeyPairGenerator.getInstance("RSA", "Ingrian-
Provider");
keygen.initialize(spec);
KeyPair keypair = keygen.genKeyPair();

Exporting a Global Key

To export a global key:
1 Obtain an instance of the key using the getSecretKey method of the NAEKey class.
2 Export the key bytes to a byte array using the export method.
The following code sample exports “globalkey”.
NAEKey key = NAEKey.getSecretKey("globalkey");
byte[] rawkey = key.export();
Exporting a Non-Global Key

In order to get an instance of a non–global key (a key that is not accessible to all users),
you must pass the session object to the getSecretKey method. The NAE Server then
returns the key, provided that the key is accessible to the authenticated user.
To export a non-global key:
1 Create an NAESession object.
Pass the NAESession object as an argument.
3 Export the key bytes to a byte array using the export method.
The following code sample exports “user1key”.
NAEKey key = NAEKey.getSecretKey("user1key", session);
byte[] rawkey = key.export();
Importing a Global Key

To import a global key:
1 Obtain the key bytes of the key.
2 Invoke the importKey method of the NAEKey class and pass the following
arguments: the key bytes, the key algorithm, the key name. The key name is specified
as an NAEParameterSpec object.
The following code sample imports mykey:

byte[] rawkey = ... /* get key bytes */

NAEKey.importKey(rawkey, "AES", new NAEParameterSpec("mykey"));
Deleting a Global Key

To delete a global key:
2 Invoke the delete method.
The following code sample deletes mykey:
NAEKey key = NAEKey.getSecretKey("mykey");
key.delete();
Getting the Size of a Global Key

To get the size of a global key:
2 Call the getKeySize method of the key object.
The following code sample returns the size of mykey:
NAESecretKey key = NAEKey.getSecretKey("mykey");
int size = key.getKeySize();
Returning a List of Global Keys on the NAE Server

To return a list of the global keys on the NAE Server:
1 Create an NAEKey array.
2 Populate the array with the elements returned by the getKeys method of the NAEKey
class.
The following code sample returns a list of all of the global keys on the NAE Server.
NAEKey[] keys = NAEKey.getKeys();
Note: getKeys() returns key handles, not key bytes. To access key bytes, use the export()
method.

Returning a List of Keys Available to an NAE User

An authenticated user has access to all global keys, all keys owned by the user, and all
keys accessible to groups to which the user belongs.
To return a list of the keys available to an NAE User:
2 Create an NAEKey array.
3 Populate the array with the elements returned by the getKeys method of the NAEKey
class. Pass the NAESession object as an argument.
The following code sample returns a list of all global keys, all keys owned by user1, and
all keys that are accessible to groups to which user1 belongs.
NAESession session = NAESession.getSession("user1","password1");
NAEKey[] keys = NAEKey.getKeys(session);
Note: getKeys() returns key handles, not key bytes. To access key bytes, use the export()
method.
Accessing a Non–Global Key

In order to get an instance of a non–global key (a key that is not accessible to all users),
you must pass the session object to the getSecretKey method. The NAE Server then
returns the key, provided that the key is accessible to the authenticated user.
To access a non-global key:
Pass the NAESession object as an argument.
NAESecretKey key = NAEKey.getSecretKey("user1key", session);
Caching Keys on the Client

The key caching feature enables you to export symmetric keys from the Ingrian device and
store them on the client for a limited time, in order to perform cryptographic operations
locally.

This feature can improve performance, specifically if network latency is high, encryption
sizes are small, and local CPU cycles are available. Once keys are cached, the client’s
cryptographic operations can continue without accessing the NAE Server.
Keys cached on the client are stored in process memory only, they are not stored on disk.
Warning! Your client and its connection to the Ingrian device must be secure.
Downloading keys over this connection and storing them on your client exposes them to
possible attack. When using the symmetric key caching feature, be sure that you are using
a secure method of download and that your client’s operating system is secure.
The following sections explain how to configure and use this feature. It contains the
following sections:
• Eligible Keys
• Client Properties
• API Support
• Logging
Eligible Keys
Only symmetric keys (AES, DES, DESede, SEED, RC4) that have been marked
Exportable may be cached. In addition, the NAE User must have export privileges for the
key. Thus, the NAE User must be the key owner or the key must be global. The NAE User
automatically has full encryption and decryption privileges for all keys in the client cache;
while in the cache, key permissions and authorization policies are ignored.
Client Properties
To cache keys, you must set the Symmetric_Key_Cache_Enabled and
Symmetric_Key_Cache_Expiry parameters on the client. Both are located in the
When setting the Symmetric_Key_Cache_Enabled parameter, you can enable the
feature over SSL or TCP. Selecting yes enables key caching over an SSL connection, so
you must also configure SSL. Selecting tcp_ok enables key caching over both TCP and
SSL connections.
Warning! TCP is not a secure communication protocol. We recommend that you use
SSL.

You can predetermine the minimum length of time a key will remain in the client cache
using the Symmetric_Key_Cache_Expiry parameter. Because the key cache is purged
only when it is called, keys may stay in the cache longer than the expiration period if there
are no calls to the Ingrian library.
API Support
Key caching is supported by the following APIs:
• Cipher.init()
• Cipher.update()
• Cipher.doFinal()
All other APIs run remotely (occur on the Ingrian device) regardless of your key caching
configuration.
Logging
The Client log will indicate when key caching has been enabled whenever client logging is
enabled.
When Log_Level is set to HIGH, the client log will record the following key caching-
related actions:
• Key export from the Ingrian device.
• Cryptographic operations that use cached keys.
• Deletion of a key from the client cache.
The server log will likewise record when keys have been downloaded.
Encrypting and Decrypting Data

The examples below illustrate how to encrypt and decrypt a small piece of data.
• Generating a Random IV
• Encrypting a Text String
• Decrypting a Text String
• Encrypting a String and Writing to a File

• Encrypting a File
Generating a Random IV
When encrypting with symmetric algorithms in ECB mode, a random IV provides a high
level of security.
To generate a random IV:
1 Call the getInstance method of the SecureRandom class. Pass the random number
generator and the JCE Provider as arguments. To use the local RNG, pass SHA1PRNG
for the algorithm name and SUN (or IBM) as the provider. To use the RNG on the
Ingrian device, pass IngrianRNG and IngrianProvider as arguments.
2 Create a byte array, sized for your key. An AES key needs a 16 byte array, a DES or
DESede key needs an 8 byte array.
3 Call the nextBytes method of SecureRandom object. Pass the byte array as an
argument.
The following code sample generates a 16 byte random IV.
SecureRandom sr = SecureRandom.getInstance("IngrianRNG",
"IngrianProvider");
byte[] iv = new byte[16];
sr.nextBytes(iv);
Important! You cannot decrypt your data without the random IV. Save and secure this
value.
If the NAE Server requires password authentication, then you must circumvent the JCE
framework when generating a random IV. This is because the JCE framework does not
allow you to pass in the NAESession object that contains the authentication information.
To generate a random IV when the NAE Server requires password authentication:
2 Create an NAESecureRandom object. Pass the NAESession object as an argument.
The following code sample generates a 16 byte random IV in an authenticated session.


NAESecureRandom sr = new NAESecureRandom(session);
sr.nextBytes(iv);
Important! You cannot decrypt your data without the random IV. Save and secure this
value.
Encrypting a Text String

To encrypt a text string:
2 Create an NAESecureRandom object. Pass the NAESession object as an argument.
3 Specify an IV, if necessary, by creating a new byte array.
4 Get an instance of a Cipher object. Pass the algorithm, mode, and padding as
arguments.
5 Obtain an instance of the key you want to use for the encryption operation.
6 Initialize the Cipher object to encrypt mode. If necessary, create a new
IvParameterSpec object and set it to the value contained in the IV byte array.
7 Convert the plaintext to a byte array and invoke the doFinal method of the Cipher
object to perform the encryption.
The sample below encrypts the text string “Hello World!” with the key “user1key.” For
this Encrypt operation the algorithm is AES, the mode is CBC, and the padding is PKCS5.
Because AES is being used in CBC mode, it is necessary to supply a 16 byte initialization
vector (IV).
SecureRandom sr = SecureRandom.getInstance("IngrianRNG",
"IngrianProvider");
sr.nextBytes(iv);
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding", "IngrianPro-
vider");
SecretKey key = NAEKey.getSecretKey("user1key", session);
cipher.init(Cipher.ENCRYPT_MODE, key, new IvParameterSpec(iv));
byte[] ciphertext = cipher.doFinal("Hello World!".getBytes());

Decrypting a Text String

To decrypt a text string:
2 Specify the IV used to encrypt the text string by creating a byte array.
3 Store the existing ciphertext in a byte array.
4 Get an instance of a Cipher object. Pass the algorithm, mode, and passing as
arguments.
5 Obtain an instance of the key you want to use for the decryption operation.
6 Initialize the Cipher object to decrypt mode. If necessary, create a new
7 Invoke the doFinal method of the Cipher object to perform the decryption and store
the plaintext in a byte array.
The example below decrypts a string with the key “user1key”. For this Decrypt operation
the algorithm is AES, the mode is CBC, and the padding is PKCS5Padding - the same
values used to encrypt the string in the previous example. Because AES is used in CBC
mode, it is necessary to supply a 16 byte initialization vector (IV). This must be the same
IV used to encrypt the string.
byte[] iv = ... /* get IV used during Encrypt operation */
byte[] ciphertext = ... /* get ciphertext */
vider");
cipher.init(Cipher.DECRYPT_MODE, key, new IvParameterSpec(iv));
byte[] plaintext = cipher.doFinal(ciphertext);
String hello = new String(plaintext);
Encrypting a String and Writing to a File

To encrypt a string and write the results to a file:
2 Specify an IV, if necessary, by creating a new byte array.
3 Get an instance of a Cipher object. Pass the algorithm, mode, and padding as
arguments.

4 Obtain an instance of the key you want to use for the encryption operation.
5 Initialize the Cipher object to encrypt mode. If necessary, create a new
6 Create and open a file to which the encrypted data can be written.
7 Specify that the Cipher object is used to write to the file.
8 Invoke getBytes to write the plaintext to the CipherOutputStream.
9 Close the cipher stream.
byte[] iv = ... /* set iv byte array to 16 byte value of the IV */
vider");
OutputStream fos = new FileOutputStream("hello.enc");
OutputStream cos = new CipherOutputStream(fos, cipher);
cos.write("Hello World!".getBytes());
cos.close();
fos.close();
Encrypting a File
The Ingrian JCE Provider interfaces with the standard JCE streaming interface, which
allows for easy cryptographic protection of all types of files: sensitive documents,
financial spreadsheets, images, or any other type of file. The steps below demonstrate how
the Ingrian JCE Provider uses the streaming mechanism.
To encrypt a file:
2 Set the IV.
3 Get an instance of the cipher object, passing as an argument the algorithm, mode, and
padding you want for that Cipher object.
4 Obtain an instance of the key you want to use for the encryption operation. The
example below uses “user1key”.
5 Initialize the Cipher object to encrypt mode.
6 Create a new buffer of 2048 bytes and declare the ciphertext byte array, which is used
later.

7 Create an input stream for the file.

8 Create an output stream for the file.
9 Declare a len variable. This variable will record how many bytes have been read at a
time.
10 Create a loop that reads data from the input file and stores it in the buffer.
11 Pass the buffer to the update method of the cipher object. This is where the actual
encryption is done. The file is read 2048 bytes at a time; however, unless the file size
is a multiple of 2048 bytes, on its last pass, the read method reads some number of
bytes less than 2048. To prevent passing garbage characters (left over from the
previous read operation) to the update method, it's necessary to specify how many
bytes were read, which is why the len variable was included.
Because some block algorithms require a certain number of bytes to perform an
Encrypt operation, it might be the case that cipher.update returns null.
12 Check that cipher.update has not returned a null value.
13 Call the doFinal method and write out the encrypted text to the output file.
14 Close the input and output files.

byte[] iv = ... /* set iv byte array to 16 byte value of the IV */
vider");
byte[] readBuffer = new byte[2048];
byte[] ciphertext;
InputStream fis = new FileInputStream("myfile");
OutputStream fos = new FileOutputStream("myfile.enc");
int len;
while ((len = fis.read(readBuffer)) != -1) {
ciphertext = cipher.update(readBuffer, 0, len);
if (ciphertext != null) {
fos.write(ciphertext);
}
}
ciphertext = cipher.doFinal();
if (ciphertext != null) {
fos.write(ciphertext);
}
fis.close();
fos.close();

Generating and Verifying Digital Signatures

• Generating a Digital Signature with an RSA Private Key
• Verifying Signed Text
Generating a Digital Signature with an RSA Private Key

The Sign operation is a bit different from the other operations available in the Ingrian
provider. A digital signature is created by taking a message, applying a hash function
(SHA1) to the fingerprint of the message (which creates a message digest), and then using
the private key in an RSA public-private key pair to encrypt that message digest. The
message and the encrypted message digest are then sent to the recipient, who can verify
the digital signature using the public key of the sender. The procedure below signs the text
string “Hello World!” with the key “rsakey.” The algorithm is SHA1withRSA.
To sign a message with an RSA private key:
1 Get an instance of a Signature object, passing as an argument the SHA1withRSA
algorithm.
2 Obtain an instance of the key you want to use for the Sign operation using the
getPrivateKey method of the NAEKey class.
3 Initialize the Signature object with the key.
4 Convert the text string, “Hello World!” in this example, to a byte array and pass it to
the update method of the Signature object.
5 Invoke the sign method of the Signature object.
Signature sig = Signature.getInstance("SHA1withRSA", "IngrianProvid-
er");
PrivateKey key = NAEKey.getPrivateKey("rsakey");
sig.initSign(key);
sig.update("Hello World!".getBytes());
byte[] signature = sig.sign();
Verifying Signed Text

The Sign Verify operation is a two–part operation used to verify a digital signature. As
mentioned above, the Sign operation produces an encrypted message digest. In order to
verify a signature, the client must send the NAE Server the encrypted hash and the

message (in this example: “Hello World!”). In the first part of the Sign Verify operation,
the NAE Server applies a hash function (using the same algorithm as was used in the
original Sign operation) to the message text that needs to be verified. This produces the
first hash. In the second part of the Sign Verify operation, the NAE Server decrypts the
message digest using the sender’s public key. This produces the second hash. The NAE
Server then compares the two hashes: if they are identical, the signature is valid; if the
hashes are not identical, then the signature is not valid.
To verify signed text:
1 Get an instance of a Signature object, passing as an argument the SHA1withRSA
algorithm.
2 Obtain an instance of the key you want to use for the Sign Verify operation using the
getPublicKey method of the NAEKey class.
3 Initialize the Signature object with the key.
4 Specify the text string that you want to verify and convert it to a byte array.
5 Perform the verify operation, passing as an argument the previously calculated
signature. At this point, the NAE Server generates a hash from the text string and
decrypts the previously calculated signature, which produces a second hash. The NAE
Server compares the two hashes and returns true if the they are identical and false if
they are not.
byte[] signature = ... /* get previously calculated signature*/
Signature sig = Signature.getInstance("SHA1withRSA", "IngrianProvid-
er");
PublicKey key = NAEKey.getPublicKey("rsakey");
sig.initVerify(key);
sig.update("Hello World".getBytes());
boolean verified = sig.verify(signature);
Generating and Verifying a MAC

The NAE Server is quite useful for protecting passwords. If you store passwords in a
database in clear text, and a malicious user compromises that database, then all your user
passwords are jeopardized. However, if you store keyed hashes of the passwords in a
database, a malicious user who compromises your database cannot obtain anything useful.
Password protection in this environment works as follows: When the Ingrian JCE Provider
is presented with a password for a user named Irwin, it sends the password to the Ingrian
device, which computes a keyed hash of the password. That keyed hash is returned to the

Ingrian JCE Provider. The hashed password is then stored in a database or other server.
The next time Irwin logs in, he provides his password as part of the request. The Ingrian
JCE Provider is sent the password from Irwin and the hashed password stored in the
database. The Ingrian device once again applies the keyed hash function to the password
submitted from Irwin and compares that value to the hash value stored in the database. For
this operation, the NAE Server returns only one byte: 1 if the two hash values match; 0 if
they do not.
• Generating a MAC
• Verifying a MAC
Generating a MAC
To generate a MAC:
1 Get an instance of a Mac object. Pass the algorithm as an argument.
2 Obtain an instance of the key.
3 Initialize the Mac object.
4 Convert the plaintext to a byte array and invoke the doFinal method of the Mac object
to create the MAC.
The following code sample uses the HmacSHA1 algorithm to create a MAC of the string
“password”.
Mac mac = Mac.getInstance("HmacSHA1", "IngrianProvider");
SecretKey key = NAEKey.getSecretKey("mackey");
mac.init(key);
byte[] mactext = mac.doFinal("password".getBytes());
Verifying a MAC
To verify a MAC:
1 Obtain a previously calculated MAC value. Put that value in a byte array.
2 Get an instance of a Mac object. Pass the algorithm as an argument.
3 Obtain an instance of the key that was used to create the MAC.

4 Initialize the Mac object and pass the previously calculated MAC value by
encapsulating the byte array in a MACValue object.
5 Convert the original plaintext to a byte array and invoke the doFinal method of the
Mac object to verify the previously calculated MAC.
The following code sample compares the value of prevMac with a newly calculated MAC
of the string “password”.
byte[] prevMac = ... /* get previously calculated MAC */
Mac mac = Mac.getInstance("HmacSHA1Verify", "IngrianProvider");
SecretKey key = NAEKey.getSecretKey("mackey");
mac.init(key, new MACValue(prevMac));
byte[] result = mac.doFinal("password".getBytes());
boolean verified = (result[0] == 1);
Chaining Operations
Using the ChainedOperations object, you can perform multiple operations on data - each
subsequent operation using the output of the previous operation.
The legal combinations of chained operations are listed below:
• encrypt / decrypt
• decrypt / encrypt
• mac / encrypt
• sign / encrypt

• Creating Chained Operations
• Returning an Intermediate Result in a Chain of Operations
Creating Chained Operations

The example below demonstrates how to encrypt “Hello World!” with “mykey1” and then
encrypt the result with “mykey2”.
To create a chained encryption operation:
1 Set the IVs you’ll need for the encryption.
2 Obtain an instance of a chained cipher.

3 Create a ChainedOperations object.

4 Use addEncrypt() to add the encryption operations to the ChainedOperations object.
Specify the key name, padding, and IvParameterSpec object.
5 Use the seal() method to seal the ChainedOperations object.
6 Initialize the Cipher object, passing the ChainedOperations object as a parameter.
Note: For all chained operations, the first argument of cipher.init is ignored.
7 Perform the operations by calling the doFinal() method on the Cipher object. Pass the
bytes of data you want to encrypt.
byte[] iv = ... /* set iv byte array to 16 byte value of the IV for mykey1
*/
byte[] iv2 = ... /* set iv byte array to 16 byte value of the IV for
mykey2 */
Cipher cipher = Cipher.getInstance("ChainedCipher");
ChainedOperations ops = new ChainedOperations();
ops.addEncrypt(NAEKey.getSecretKey("mykey1"), "AES/CBC/ PKCS5Padding",
new IvParameterSpec(iv));
ops.addEncrypt(NAEKey.getSecretKey("mykey2"), "AES/CBC/ PKCS5Padding",
new IvParameterSpec(iv2));
ops.seal();
cipher.init(Cipher.ENCRYPT_MODE, ops);
Returning an Intermediate Result in a Chain of Operations

The example below demonstrates how to encrypt “Hello World!” with the key mykey,
then MAC the encrypted text with the key “mackey”. This chain of operations returns the
encrypted text concatenated with the MAC.
To return an intermediate result in a chain of operations:
1 Obtain an instance of a chained cipher.
2 Create a ChainedOperations object. Add the an operation to that object. An encryption
operation is used in this example. Because the example returns the encrypted text
along with the MAC, you must add the addSend method to the encryption operation.
3 Add the second operation. A MAC operation is used in this example.
4 Seal the operations.
5 Pass the ChainedOperations object to the cipher.init method.

6 Call the cipher.doFinal method, passing the bytes of data you want to encrypt and
MAC.
Cipher cipher = Cipher.getInstance("ChainedCipher", "IngrianProvider");
ChainedOperations ops = new ChainedOperations();
ops.addEncrypt(NAEKey.getSecretKey("mykey"), "AES/CBC/ PKCS5Padding",
iv);
ops.addSend();
ops.addMAC(NAEKey.getSecretKey("mackey"), "HmacSHA1");
ops.seal();
cipher.init(Cipher.ENCRYPT_MODE, ops);

CHAPTER 6
Using the Sample

Applications
About the CryptoTool Application 88
Examples of CryptoTool 91
About the Tomcat Servlet 95

88 USING THE SAMPLE APPLICATIONS
About the CryptoTool Application

We distribute a sample application with the Ingrian JCE Provider. This sample application
can be used as a debug tool to ensure that you have installed and configured the Ingrian
JCE Provider correctly. Once you have verified that the Ingrian JCE Provider is installed
and configured properly, the sample application can be used to perform cryptographic
operations and key management tasks from the command line or from shell scripts.
To use the sample application, copy the CryptoTool.class file from IngrianJCE/
samples/cryptotool to the <java-home>/bin directory. Once the file is in place,
you can invoke the sample application by navigating to your JRE directory and executing
the following command:
java CryptoTool
You can access the help for the sample application by running the same command above,
only this time add the -help option.
java CryptoTool -help
Tip: Before invoking the CryptoTool, make sure that the values specified in the
IngrianNAE.properties file are correct.
Usage
The syntax for the JCE sample application is as follows:
java CryptoTool OPERATION options
• java – invokes the JVM

• CryptoTool – invokes the sample application
• OPERATION – specifies a cryptographic or key management operation
• options – specifies one or many options
Operations
The CryptoTool provides support for all cryptographic operations supported by the Ingrian
JCE Provider and some key management operations.
You can use standard input from the command line (e.g. text that is manually typed on the
command line) as input for any of the cryptographic operations; however, the more
practical application of the CryptoTool is to use a file as input. This is because the output
from an ENCRYPT operation, for example, generates binary output. To decrypt that

string, you would have to copy the binary output from the ENCRYPT operation and pass it
in as input for the DECRYPT operation. It is most likely that the binary data would be
misrepresented, causing the DECRYPT operation to throw a Java exception
Supported cryptographic operations:
• ENCRYPT – encrypt a file or string
• DECRYPT – decrypt a file or string
• MAC – generate a MAC on a string or file
• MACV – verify a MAC
• SIGN – generate a signature on a file or string
• SIGNV – verify a signature
Supported key management operations

• GENERATE – generate a key
• DELETE – delete a key
• EXPORT – export a key
• IMPORT – import a key
• LIST – list all keys on your NAE Server
Important! You must use all capital letters when specifying an operation, and you can
specify only one operation at a time. Chain operations are not supported.
Options
This section describes options that can be used in conjunction with the operations above.
Options can be specified in any order, but they must be specified after the operation. In the
following table, the option is listed in the Flag column, and the expected input is
immediately after the option in italics. For example, the -in option requires that you
specify a file to be used as input for the cryptographic operation. If the input file is not in
your present working directory, you must specify the path to the file.

Table 6.1
Sample Application Usage Options
Flag Expected Input Description
–in filename specifies an input file to use for a cryptographic operation. If you are
not using a file, then you must type the data that you want to use for
the cryptographic operation on the command line.
–out filename specifies a file that receives the output of the cryptographic operation.
If you do not specify a file, the output appears on the screen.
–key filename specifies a key name for either a key management or cryptographic
operation.
–alg algorithm_name specifies a cryptographic algorithm. The parameter for this option
must be a valid algorithm name, as specified in Appendix A,
“Supported Algorithms.” Such algorithms include DES, DESede,
AES, RSA, HMAC, or RC4.
–iv value this option specifies an IV. The IV must be hex ASCII encoded. An
IV is only required when using either DES, DESede, or AES in CBC
mode; in ECB mode, the IV is not allowed.
–sig value allows you to specify on the command line a signature value that you
want to verify. The signature value must be hex ASCII encoded.
Alternatively, you can specify a file that contains the hex ASCII
encoded signature value by using the –sigfile option instead of the
–sig option. That option is described immediately below.
–sigfile filename an alternative to the –sig option above. It allows you to specify a file
that contains the hex ASCII encoded signature value for verification.
–mac value allows you to specify on the command line a MAC value for
verification. The MAC value must be hex ASCII encoded.
Alternatively, you can specify a file that contains the hex ASCII
encoded MAC value by using the –macfile option instead of the –mac
option. That option is described immediately below.
–macfile filename an alternative to the –mac option above. It allows you to specify a file
that contains the hex ASCII encoded MAC value for verification.
–auth username:password allows you to specify an NAE username and password to use for
authentication.
–keysize size specifies the size of the key to be created.
–exportable when used with the GENERATE operation, this option allows you to
create an exportable key.
–deletable when used with the GENERATE operation, this option allows you to
create a deletable key.

Flag Expected Input Description

–ip ip_address this option allows you to specify the IP address of the NAE Server(s)
that the sample application sends requests to. You can specify
multiple IP addresses in a colon–separated list. By default, the sample
application uses the IP address specified in
IngrianNAE.properties; by specifying a value for this
option, you override the IP address stored in
IngrianNAE.properties.
–port port specifies the port to be used to communicate with the NAE Server.
By default, the sample application uses the port specified in
IngrianNAE.properties; by specifying a value for this
option, you override the value stored in
IngrianNAE.properties.
–protocol protocol specifies the protocol to be used to establish connections with the
NAE Server. You can specify either TCP or SSL. By default, the
sample application uses the protocol specified in the
IngrianNAE.properties file; by specifying a value for this
option, you are overriding the protocol stored in the
Examples of CryptoTool
The examples below demonstrate how to use the operations and options available in the
Ingrian JCE sample application. When using the JCE sample application, remember that
you must specify the operation before any options, and that options can be specified in any
order.
Important! All of the examples below include the use of the -auth flag; this is not
required. It might be the case that you have configured the NAE Server to not require
password authentication, in which case it would not be necessary to include an NAE user
name and password in the requests you send to the NAE Server from CryptoTool. By not
including a user name and password, you are essentially creating an unauthenticated
session with the NAE Server; all keys created during an unauthenticated session are global
keys, meaning that they can be used without restriction by any NAE user.
Key Management Operations
Generate an AES Key
The command below generates an AES key named “mykey” and owned by User1.

java CryptoTool GENERATE -auth User1:pwd -key mykey -alg AES
Use the command below to make sure that the key was created on the correct NAE Server.
java CryptoTool LIST -auth User1:pwd
The key name and algorithm should appear.

Because we did not include the -keysize flag in this request, the NAE Server generates a
128–bit AES key.
Generate a 256–bit AES Key
The command below creates a 256–bit AES key named “my256key”, owned by User1.
java CryptoTool GENERATE -auth User1:pwd -key mykey256 -alg AES -keysize 256
Generate an HMAC Key
The command below creates an HMAC key named “hmackey”, owned by NAE_User1.
java CryptoTool GENERATE -auth User1:pwd -key hmackey -alg HmacSHA1
Generate an RSA Key
The command below generates an RSA key named “rsakey”, owned by User1.
java CryptoTool GENERATE -auth User1:pwd -key rsakey -alg RSA
Create a Global Key
The command below creates a global AES key named globalAESkey. Notice that the
username and password are omitted in this example. Remember that you can only create
global keys if the NAE Server is configured to allow unauthenticated sessions.
java CryptoTool GENERATE -key globalAES -alg AES
Create an Exportable and Deletable DESede Key
You can include the -exportable and/or -deletable flags in any request to generate a key.
The command below creates an exportable and deletable DESede key called DESkey27.
java CryptoTool GENERATE -auth User1:pwd -key DESkey27 -alg DESede -exportable -
deletable

Note: The exportable and deletable options specify no arguments. You should also notice
that the -alg option came before the -key option. This is to illustrate the point that you
can list options in any order.
Export a Key
The example below exports AESkey27, created immediately above. Make sure that you
do not discard the key text; it is used again later.
java CryptoTool EXPORT -auth User1:password -key AESkey27
Notice that you only have to specify the key name to export a key; you do not have to
specify the algorithm. The authentication information was included because the mykey2 is
owned by nae_user.
Delete a Key
This example deletes AESkey27 from the NAE Server.

java CryptoTool DELETE -auth User1:password -key AESkey27
Import a Key
This example imports AESkey27 to the NAE Server.

java CryptoTool IMPORT -auth User1:password -key AESkey27 -alg AES
Once you execute the command above, you must provide the key that you want to import.
You can copy the key text that was displayed when you exported mykey2 above. When
you have entered the key text, press Return, then press Ctrl+d (Linux) or Ctrl+z
(Windows). You should see a message confirming that the key was imported.
Cryptographic Operations
Encrypt a String
This example is included for illustrative purposes only. Because you cannot decrypt the
ciphtertext printed to the screen after the encrypt operation, there is little use in encrypting
a string.
In this example we encrypt the string “Hello World!” with the AES key created above.
After you execute the command below, you must type in the text you want to encrypt.

When you are done entering the text, press Return, then press Ctrl+d (Linux/Unix) or
Ctrl+z (Windows). The system prints the ciphertext to the console.
java CryptoTool ENCRYPT -auth User1:pwd -key mykey -alg AES
Encrypt a File
While it is possible to supply text for cryptographic operations from the command line, it
is more convenient and less error–prone to perform cryptographic operations on files. The
example below uses the -in and -out options to encrypt a file called test.txt and write the
ciphertext to a file called test.txt.enc.
java CryptoTool ENCRYPT -auth User1:password -key mykey -alg AES -in /jcetest/
test.txt -out /jcetest/test.txt.enc
Decrypt a File
The example below decrypts the output file that was created in the encrypt example above.
Again, the -in option is used to specify what file the DECRYPT operation is performed
on, and the -out option specifies the file to which the decrypted text is written.
java CryptoTool DECRYPT -auth User1:password -key mykey -alg AES -in /jcetest/
test.txt.enc -out /jcetest/test.txt.dec
Open the output file (test.txt.dec) and verify that the text of the file matches the text of the
input file (text.txt).
Create a MAC
The example below creates a MAC using the same test.txt file as was used in the examples
above. This example uses the HMAC key created above.
java CryptoTool MAC -auth User1:password -key hmackey -alg HmacSHA1 -in /jcetest/
test.txt -out /jcetest/test.mac
Verify a MAC Value
To verify a MAC, you have to provide the NAE Server with the previously–calculated
MAC and the text the MAC was created from. In this example, you use the -macfile option
to specify the MAC, and you use the -in option to provide the original text.
java CryptoTool MACV -auth User1:password -key hmackey -alg HmacSHA1 -in /jcetest/
test.txt -macfile /jcetest/test.mac
After executing the command, you should see a verification message.

Create a Signature
This example creates a signature using the file test.txt and the RSA key created above.
java CryptoTool SIGN -auth User1:password -key rsakey -alg SHA1withRSA -in /jcet-
est/test.txt -out /jcetest/test.sig
Verify a Signature
To verify a signature, you must provide the NAE Server with the previously–calculated
signature value and the text that the signature was created from. In this example, you use
the -sigfile option to specify the signature, and you use the -in option to provide the text.
java CryptoTool SIGNV -auth User1:password -key rsakey -alg SHA1withRSA -in /
jcetest/test.txt -sigfile /jcetest/test.sig
After executing the command, you should see a verification message.
About the Tomcat Servlet

The Tomcat servlet enables you to see how your java web server will interact with the
Ingrian JCE Provider. The servlet itself is simple. You enter an NAE username, password
and an AES key name. The servlet then:
• Connects to the Ingrian device.
• Verifies that the user is authorized to use the key.
• Encrypts a string.
• Decrypts the string.
• Returns a list of registered JCE providers.
This sample servlet requires Apache Ant and Apache Tomcat.
Configuring the Tomcat Servlet

Before you can run the servlet, you will need to update the build.xml and tomcat-
users.xml files and build the war file.
To configure the Tomcat servlet you must:
1 Open /IngrianJCE_HOME/samples/tomcat_servlet/build.xml in text editor.
2 Update the catalina.home property in the build.xml file.
<property name="catalina.home" value="C:\apache-tomcat-6.0.14"/>

3 Update the ingrian.home property with the location of the IngrianNAE.jar, log4j-
1.2.9.jar, and IngrianNAE.properties files.
<property name="ingrian.home" value="C:\Java\jre1.6.0_03\lib\ext"/>
4 Open your tomcat-users.xml file in a text editor.

5 Add the manager rolename and assign it to your Tomcat user. Your tomcat-users.xml
file will look something like the following:
<tomcat-users>
<role rolename="manager"/>
<role rolename="tomcat"/>
<user username="tomcat" password="tomcat" roles="tomcat,manager"/>
</tomcat-users>
6 Run ant dist to build the war file. This will create the dist directory and copy the
sample.war file.
Note: If you are rebuilding the war file after a previous test, you may need to restart
Tomcat prior to running ant dist if your environment was somehow corrupted.
Running the Servlet

To run the servlet:
1 Start Tomcat by running the following command:
$CATALINA_HOME\bin\startup.bat (Windows)
$CATALINA_HOME/bin/startup.sh (UNIX)
2 Test your server by visiting http://localhost:8080. You should see the standard Apache
Tomcat page.
3 Run ant install to deploy the sample servlet. The servlet will be available at
http://localhost:8080/sample/Hello.

Fig. 6.1
Sample Application Servlet: Query section
4 Enter the name and password of a previously defined NAE User on the Ingrian device.
5 Enter the name of a previously defined key on the Ingrian device.
6 Click Submit Query. The servlet will now use the username/password combination to
connect to the Ingrian device. It will then call on the device to encrypt the string
‘Hello servlet’. The string will then be decrypted and the servlet will list the available
JCE providers. All results are shown in the web browser.
Fig. 6.2
Sample Application Servlet: Results section


99 INDEX
Index K
keystore 44, 55
L
load balancing
C configuration 27
CA certificate Load_Balancing_Algorithm
installing on server 56 IngrianNAE.properties file 27
CA certificates logging
clustering 32 configuration 33
ssl configuration 32
client certificate authentication 32 N
clustering NAE device
CA certificates 32 content restrictions 8
connection pooling
configuration 27 P
Connection Read Timeout Configuration 28
parameters
content restrictions, NAE device 8
Size_of_Connection_Pool 27
cryptographic operations
performance
asymmetric encryption 7
connection read timeout 28
digital signatures 7
connection timeout 28
MAC 7
timeout configuration 28
MAC Verify 7
persistent connection configuration 27
random number generation 7
protocol configuration 24
symmetric encryption 7
R
D
requirements
data restrictions, NAE device 8
hardware and software 7
round-robin
H
load balancing algorithm 27
hardware
requirements 7 S
setProperty method 23
I
Size_of_Connection_Pool parameter 27
importing Ingrian Java Package 64 software
Ingrian Data Privacy Solution requirements 7
alternate configurations, extremely high load 8 SSL
alternate configurations, high availability 8 client certificate 32
Ingrian Java Package client certificate authentication 32
importing 64 client private key 33
Ingrian JCE Provider, communication channel with client private key passphrase 33
server 7 protocol configuration 24
IngrianNAE.properties server CA certificate 32
setting system properties 23 System Properties
SSL configuration 31 client certificate authentication 32
IngrianNAE.properties file 9 client certificate private key 33
client private key passphrase 33
J connection pooling 27
java keystore 44, 55 connection read timeout configuration 28
connection retry 29
load balancing 27

100 INDEX
logging 33 setting programmatically 23

network configuration 24, 26
persistent connections 27 T
protocol configuration 24 tcp
setting 22 protocol configuration 24
SSL Configuration 31 Timeout Configuration 28
timeout configuration 28 TLSv1 24
system properties trusted CA list profile 56

JCE-Developer - Guide-4 6 0

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

JCE-Developer - Guide-4 6 0

Загружено:

Авторское право:

Доступные форматы

NAE Developer Guide for the

Software Version: 4.6.0

© 2007 Ingrian Networks, Inc. All rights reserved

CHAPTER 2 INSTALLING THE INGRIAN JCE PROVIDER . . . . . . . . . . . . . . 11

CHAPTER 3 CONFIGURING THE INGRIAN CLIENT . . . . . . . . . . . . . . . . . . 21

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Log Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

CHAPTER 4 SETTING UP SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CHAPTER 5 USING THE JCE PROVIDER . . . . . . . . . . . . . . . . . . . . . . . . 63

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Creating a Key and Assigning Permissions . . . . . . . . . . . . . . . . . . . .69

CHAPTER 6 USING THE SAMPLE APPLICATIONS. . . . . . . . . . . . . . . . . . . 87

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Cryptographic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Contacting Technical Support 3

Using This Guide

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Notes and Cautions

Contacting Technical Support

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Hardware and Software Requirements 7

Supported Cryptographic Operations 7

General System Architecture

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Hardware and Software Requirements

Supported Cryptographic Operations

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Extremely High Load

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Installing the Ingrian JCE

Installing the Ingrian JCE Provider 13

Using Unlimited Strength Ciphers 19

Obtaining Provider Software

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

The IngrianJCE/documentation directory contains the Ingrian Javadoc, which gives

Installing the Ingrian JCE Provider

Installing the jar Files

Files Needed For J2SE/J2EE Version 1.4.x and 1.5.x

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Files Needed for J2SE/J2EE Version 1.3.x

Files Needed to Improve SSL Performance

Updating the Java Security File

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Manually Adding the Ingrian Provider

2 Add the following line to the end of the list of providers:

3 Save and close the file.

Manually Adding the Ingrian Provider When Using Sun J2SE/J2EE

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Adding the Ingrian Provider Programmatically

addProvider() automatically appends the Ingrian Provider to the list of approved

Adding the Cryptix JCE Provider

2 Add the following line to the end of the list of providers:

NAE DEVELOPER GUIDE FOR THE JCE PROVIDER

Installing the IngrianNAE.properties File

This section provides instructions for:

Configuring the IngrianNAE.properties File

We provide a default configuration file in the IngrianJCE/lib/ext directory. You