Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - CRYPTOGRAPHIC SMART CARD DRIVER

BlackBerry Java Development

Environment

Version 4.6.0

Cryptographic Smart Card Driver Development Guide

BlackBerry Java Development Environment Version 4.6.0 Cryptographic Smart Card Driver Development Guide

Last modified: 6 October 2008

Part number: 12802084

At the time of publication, this documentation is based on the BlackBerry Java Development Environment Version 4.6.0.

Send us your comments on product documentation: https://www.blackberry.com/DocsFeedback.

and logos are the property of Research In Motion Limited and are registered and/or used as trademarks in the U.S., Canada, and countries

around the world.

Bluetooth is a trademark of Bluetooth SIG. Java is a trademark of Sun Microsystems, Inc. SafeNet is a trademark of SafeNet, Inc. Casira is a

trademark of Cambridge Silicon Radio Ltd. RSA is a trademark of RSA Security. All other brands, product names, company names, trademarks

and service marks are the properties of their respective owners.

The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, and various

patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460;

D416,256. Other patents are registered or pending in the U.S. and in various countries around the world. Visit www.rim.com/patents for a list

of RIM (as hereinafter defined) patents.

This documentation including all documentation incorporated by reference herein such as documentation provided or made available at

www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee,

representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility

for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and

confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM

reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide

any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or services including

components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and

Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content,

accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party

Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by

RIM of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS,

GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY

CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR

PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR

ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR

ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND

SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE.

SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT

PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT

BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST

ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE

OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE,

HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY

OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED

DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION,

LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT

OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR

SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME

SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR

PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF

THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY,

OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT

LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF

ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY

OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL

PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR

SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO

INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT,

DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR

RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service

provider has agreed to support all of their features. Installation or use of Third Party Products and Services with RIM's products and services

may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are

solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If

required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses

have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience

to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by

RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and

subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent

expressly covered by a license or other agreement with RIM.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN

THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR

PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Certain features outlined in this document require a minimum version of BlackBerry Enterprise Server Software, BlackBerry Desktop Software,

and/or BlackBerry Handheld Software and may require additional development or third-party products and/or services for access to corporate

applications.

Published in Canada

Research In Motion Limited

295 Phillip Street

Waterloo, ON N2L 3W8

Canada

Research In Motion UK Limited

Centrum House, 36 Station Road

Egham, Surrey TW20 9LF

United Kingdom

Contents

1Using smart cards................................................................................................................................................. 3

Smart cards........................................................................................................................................................ 3

Add support for smart cards .................................................................................................................... 3

Creating a cryptographic smart card driver ................................................................................................. 4

Set up the project for the cryptographic smart card driver ................................................................ 4

Design a cryptographic smart card driver............................................................................................. 4

Create a cryptographic session for a cryptographic smart card........................................................ 5

Create a cryptographic token for private key operations ................................................................... 6

Store the location of the private key file................................................................................................ 8

2Testing a cryptographic smart card driver...................................................................................................... 11

Set up the BlackBerry Device Simulator to test a cryptographic smart card driver...............................11

Set up a BlackBerry device to test a cryptographic smart card driver .....................................................11

Test the cryptographic smart card driver.....................................................................................................12

3Code samples .......................................................................................................................................................15

Code sample: Creating a cryptographic smart card object.......................................................................15

Code sample: Creating a cryptographic session for a cryptographic smart card driver ......................18

Code sample: Enabling a CryptoToken object for RSA operations using a private key.......................24

Code sample: Storing the location of a private key file on the smart card............................................28

Using smart cards

Smart cards

Add support for smart cards

You can use the net.rim.device.api.smartcard package and the net.rim.device.api.crypto package to

create smart card drivers that interact with smart cards and BlackBerry Smart Card Readers. The smart card API

was included in BlackBerry® Java® Development Environment Version 4.1. The

SmartCardProtocolErrorException API was added in BlackBerry JDE Version 4.2.

A cryptographic smart card driver that implements the smart card API can work with the S/MIME Support

Package for BlackBerry® smartphones on a BlackBerry smartphone with S/MIME support. A cryptographic smart

card driver can perform private key operations on the smart card such as signing and decrypting messages. A

cryptographic smart card driver does not require the S/MIME Support Package for BlackBerry smartphones to be

able to import certificates from the smart card, or to provide two-factor authentication for a BlackBerry device. See

BlackBerry with the S/MIME Support Package for more information on S/MIME.

The smart card API information included with BlackBerry JDE Version 4.2 or later contains some deprecated

elements. The deprecated elements provide backward compatibility for a cryptographic smart card driver

application created for a BlackBerry device that uses BlackBerry® Device Software Version 4.1.x. If you want to

create a cryptographic smart card driver for a BlackBerry device that is compatible with either BlackBerry Device

Software Version 4.1.x or Version 4.2 or later, you can use the deprecated elements to avoid having to create two

versions of the cryptographic smart card driver.

If you want to create a cryptographic smart card driver for a BlackBerry device that is compatible with BlackBerry

Device Software Version 4.2 or later, use the non-deprecated API items in the smart card API.

Smart cards

Creating a cryptographic smart card driver

Smart card scenarios Description

supported smart cards The BlackBerry® device supports the following smart cards:

•Common Access Card (CAC)

•SafeNet® Model 330 smart card

unsupported smart cards If your smart card is not a CAC or SafeNet smart card, use the smart card API to create a cryptographic smart

card driver to support your smart card.

Cryptographic Smart Card Driver Development Guide

Creating a cryptographic smart card driver

To create a cryptographic smart card driver for BlackBerry Device Software Version 4.1 or later, complete the

following tasks:

1. Set up the project for the cryptographic smart card driver.

2. Design a cryptographic smart card driver.

3. Create a cryptographic session for a cryptographic smart card driver.

4. Create a cryptographic token for private key operations.

5. Store the location of the private key file.

Set up the project for the cryptographic smart card driver

Design a cryptographic smart card driver

You must implement all of the following methods:

Task Steps

Set up the project. 1. Open the BlackBerry® Integrated Development Environment.

2. Create a new project for the cryptographic smart card driver.

Configure the project. 1. In the Workspace window, right-click the new project.

2. Select Properties.

3. On the Application tab, in the Project type field, type Library.

4. Select the Auto-run on startup check box.

5. In the Startup Tier field, select the 7(Last; 3rd party apps only) option.

6. Click OK.

Create a libMain() method. > In your extension of the CryptoSmartCard class, implement the libMain() method.

Task Steps

Enable a smart card driver to open a

cryptographic session with a smart card.

>ImplementSmartCard.openSessionImpl(SmartCardReaderSession).

Enable a smart card driver to verify if a smart

card is compatible with a specific Answer To

Reset (ATR) sequence.

>ImplementSmartCard.checkAnswerToResetImpl(AnswerToReset).

Enable a smart card driver to display

settings or properties.

>ImplementSmartCard.displaySettingsImpl(Object).

Enable a smart card driver to indicate

support for display settings.

>ImplementSmartCard.isDisplaySettingsAvailableImpl(Object).

Retrieve the capabilities of a smart card. >ImplementSmartCard.getCapabilitiesImpl(). The capabilites of a smart card

include the protocols the card supports, the baud rate, and the clock adjustment factors.

Retrieve the smart card type. >ImplementSmartCard.getLabelImpl().

1: Using smart cards

See “Code sample: Creating a cryptographic smart card object” on page 15 for more information.

Create a cryptographic session for a cryptographic smart card

Retrieve the names of the algorithms that

the smart card supports, for example (“RSA”,

“DSA”).

>ImplementCryptoSmartCard.getAlgorithms().

Retrieve a CryptoToken object that

supports the given algorithm.

>ImplementCryptoSmartCard.getCryptoToken(String).

Task Steps

Create a cryptographic smart

card session for a

cryptographic smart card.

> Extend the abstract CryptoSmartCardSession class.

Close a cryptographic smart

card session.

> Implement SmartCardSession.closeImpl().

Retrieve the maximum

number of login attempts.

> Implement SmartCardSession.getMaxLoginAttemptsImpl().

Retrieve the ID for the smart

card.

> Implement SmartCardSession.getSmartCardIDImpl().

Retrieve the remaining

number of login attempts.

> Implement SmartCardSession.getRemainingLoginAttemptsImpl().

Attempt to log in to the

cryptographic session using a

given password string.

> Implement SmartCardSession.loginImpl(String).

Retrieve the certificates from

the smart card.

> Perform one of the following steps:

•To create a cryptographic smart card driver that is compatible with BlackBerry Device Software Version

4.2 or later, implement CryptoSmartCardSession.getKeyStoreDataArrayImpl()as follows:

RSACryptoToken token = new MyRSACryptoToken();

RSACryptoSystem cryptoSystem = new RSACryptoSystem(token, 1024);

RSAPrivateKey privateKey;

PrivateKey privateKey = new RSAPrivateKey(cryptoSystem, new

MyCryptoTokenData());

•To create a cryptographic smart card driver that is compatible with BlackBerry Device Software Version 4.1

and Version 4.2 or later, and to include the cryptographic smart card driver in two-factor authentication,

implement the getKeyStoreDataArrayImp method as follows:

PrivateKey privateKey = CryptoSmartCardUtilities2.createPrivateKey(token,

1024, new MyCryptoTokenData());

Validate the input

parameters in the

cryptographic session.

> Perform one of the following steps:

•To create a cryptographic smart card driver that is compatible with BlackBerry Device Software Version

4.2 or later, in your implementation of the signDecrypt method, validate the parameters as follows:

int modulusLength = cryptoSystem.getModulusLength();

•To create a cryptographic smart card driver that is compatible with BlackBerry Device Software Version 4.1

and Version 4.2 or later, and to include the cryptographic smart card driver in two-factor authentication,

in your implementation of the signDecrypt method, validate the parameters as follows:

int modulusLength = (cryptoSystem.getBitLength()/8);

Task Steps

Cryptographic Smart Card Driver Development Guide

See “Code sample: Creating a cryptographic session for a cryptographic smart card driver” on page 18 for more

information.

Create a cryptographic token for private key operations

Retrieve random data from

the internal random number

generator of the smart card.

> Implement CryptoSmartCardSession.getRandomBytesImpl(int maxNumBytes).

Task Steps

Create a token class. > Perform one of the following steps:

•To create a cryptographic smart card driver that is compatible with BlackBerry Device

Software Version 4.2 or later, create a class that extends an RSA®, DSA, or ECC token class.

For example:

final class MyRSACryptoToken extends RSACryptoToken implements

Persistable

•To create a cryptographic smart card driver that is compatible with BlackBerry Device

Software Version 4.1 and Version 4.2 or later, and to include the cryptographic smart card

driver in two-factor authentication, create a class that extends the

SmartCardRSACryptoToken class.

final class MyRSACryptoToken extends SmartCardRSACryptoToken

Determine if the token object can perform

authentication for a BlackBerry device

user.

> Create a method that returns true if your token object prompts the BlackBerry device user for

authentication information.

public boolean providesUserAuthentication()

{

return true;

}

Determine if the token object supports the

current CryptoSystem.

> Create a method that returns a Boolean value that indicates if the token object supports the

current CryptoSystem.

public boolean isSupported(CryptoSystem cryptoSystem, int operation)

{

return (operation == PRIVATE_KEY_OPERATION);

}

Task Steps

Ce manuel convient aux modèles suivants

Table des matières

Autres manuels Blackbe;rry Logiciel

Blackbe;rry

Blackbe;rry PROFESSIONAL SOFTWARE FOR IBM LOTUS DOMINO - - MIGRATION... Manuel utilisateur

Blackbe;rry

Blackbe;rry ENTERPRISE SERVER FOR MICROSOFT EXCHANGE - CALENDAR SYNCHRONIZATION TOOL - TECHNICAL... Manuel utilisateur

Blackbe;rry

Blackbe;rry MAIL - - HELP Manuel utilisateur

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - GPS AND MAPS - DEVELOPMENT... Manuel utilisateur

Blackbe;rry

Blackbe;rry CLIENT FOR IBM LOTUS CONNECTIONS - WILLKOMMEN BEI... Manuel utilisateur

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - DEVICE APPLICATIONS INTEGRATION - DEVELOPMENT... Guide de configuration rapide

Blackbe;rry

Blackbe;rry WALLET - LEARN MORE Manuel utilisateur

Blackbe;rry

Blackbe;rry TWITTER FOR SMARTPHONES - BETA V1.0 Manuel utilisateur

Blackbe;rry

Blackbe;rry PROFESSIONAL SOFTWARE FOR MICROSOFT EXCHANGE - - MIGRATION... Manuel utilisateur

Blackbe;rry

Blackbe;rry MEDIA SYNC - - RELEASE NOTES Mode d’emploi

Blackbe;rry

Blackbe;rry ICQ - MISE EN ROUTE Manuel utilisateur

Blackbe;rry

Blackbe;rry ICQ - RELEASE NOTES V2.5 Mode d’emploi

Blackbe;rry

Blackbe;rry S-MIME SUPPORT PACKAGE VERSION 4.1 - Manuel utilisateur

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT Mode d’emploi

Blackbe;rry

Blackbe;rry WINDOWS LIVE MESSENGER FOR SMARTPHONES Manuel utilisateur

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - COMPONENT PACKAGE - RELEASE... Mode d’emploi

Blackbe;rry

Blackbe;rry CLIENT FOR NOVELL GROUPWISE MESSENGER Manuel utilisateur

Blackbe;rry

Blackbe;rry CLIENT FOR IBM LOTUS QUICKR - AUTRE KNOWN ISSUES... Manuel utilisateur

Blackbe;rry

Blackbe;rry GOOGLE TALK - LEARN MORE Manuel utilisateur

Blackbe;rry

Blackbe;rry ENTERPRISE SOLUTION SECURITY - ERASING FILE SYSTEMS ON DEVICES -... Guide d'installation

Blackbe;rry

Blackbe;rry AMAZON MP3 - V1.0 Manuel utilisateur

Blackbe;rry

Blackbe;rry Amazon MP3 Mode d’emploi

Blackbe;rry

Blackbe;rry PROFESSIONAL SOFTWARE FOR MICROSOFT EXCHANGE - - RELEASE... Mode d’emploi

Blackbe;rry

Blackbe;rry FACEBOOK FOR BLACKBERRY SMARTPHONES 1.9 - RELEASE... Mode d’emploi

Manuels Logiciel populaires d'autres marques

COMPRO

COMPRO COMPROFM Manuel utilisateur

Muratec

Muratec OFFICEBRIDGE ONLINE Manuel utilisateur

Oracle

Oracle Contact Center Anywhere 8.1 Manuel utilisateur

Adobe

Adobe 65007312 - Photoshop Lightroom Manuel

Avaya

Avaya NULL One-X for RIM Blackberry Manuel utilisateur

HP ProLiant BL420c Manuel utilisateur

PS Audio

PS Audio PowerPlay Manuel du propriétaire

Brady

Brady LOCKOUT PRO 3.0 Manuel de service

Avaya

Avaya Interaction Center Manuel utilisateur

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Manuel

Novell

Novell GROUPWISE 8 - INTERNET AGENT Manuel utilisateur

Oracle

Oracle Application 9i Manuel utilisateur

Acer

Acer RDM Manuel utilisateur

Canon

Canon Vixia HF21 Manuel utilisateur

Canon

Canon ZR950 Manuel utilisateur

Samsung

Samsung Auto Backup Manuel utilisateur

Polycom

Polycom Vortex EF2201 Instructions d'installation et d'utilisation

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c Manuel utilisateur

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - CRYPTOGRAPHIC SMART CARD DRIVER - DEVELOPMENT... Manuel utilisateur

Manuels Logiciel populaires d'autres marques