Blackberry JAVA DEVELOPMENT ENVIRONMENT User Manual

Download

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.

©2008 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType® and related trademarks, names, 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, includin g one or more of the fo llowing 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 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.

www.rim.com/patents for a list

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.

Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada

Published in Canada

Research In Motion UK Limited Centrum House, 36 Station Road Egham, Surrey TW20 9LF United Kingdom

1 Using 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

2 Testing 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

3 Code 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 Creating a cryptographic smart card driver

Smart cards

Add support for smart cards

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

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.

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

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.

Design a cryptographic smart card driver

You must implement all of the following methods:

Task Steps

Enable a smart card driver to open a cryptographic session with a smart card.

Enable a smart card driver to verify if a smart card is compatible with a specific Answer To Reset (ATR) sequence.

Enable a smart card driver to display settings or properties.

Enable a smart card driver to indicate support for display settings.

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

Retrieve the smart card type. >Implement SmartCard.getLabelImpl().

>Implement SmartCard.openSessionImpl(SmartCardReaderSession).

>Implement SmartCard.checkAnswerToResetImpl(AnswerToReset).

>Implement SmartCard.displaySettingsImpl(Object).

>Implement SmartCard.isDisplaySettingsAvailableImpl(Object).

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

Task Steps

Retrieve the names of the algorithms that

>Implement CryptoSmartCard.getAlgorithms(). the smart card supports, for example (“RSA”, “DSA”).

Retrieve a CryptoToken object that

>Implement CryptoSmartCard.getCryptoToken(String). supports the given algorithm.

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

Create a cryptographic session for a cryptographic smart card

Task Steps

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

Close a cryptographic smart card session.

Retrieve the maximum number of login attempts.

Retrieve the ID for the smart card.

Retrieve the remaining number of login attempts.

Attempt to log in to the cryptographic session using a given password string.

Retrieve the certificates from the smart card.

Validate the input parameters in the cryptographic session.

> Extend the abstract CryptoSmartCardSession class.

> Implement SmartCardSession.closeImpl().

> Implement SmartCardSession.getMaxLoginAttemptsImpl().

> Implement SmartCardSession.getSmartCardIDImpl().

> Implement SmartCardSession.getRemainingLoginAttemptsImpl().

> Implement SmartCardSession.loginImpl(String).

> 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

RSACryptoToken token = new MyRSACryptoToken();

RSACryptoSystem cryptoSystem = new RSACryptoSystem(token, 1024);

RSAPrivateKey privateKey;

PrivateKey privateKey = new RSAPrivateKey(cryptoSystem, new MyCryptoTokenData());

CryptoSmartCardSession.getKeyStoreDataArrayImpl()as follows:

PrivateKey privateKey = CryptoSmartCardUtilities2.createPrivateKey(token, 1024, new MyCryptoTokenData());

getKeyStoreDataArrayImp method as follows:

> 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

int modulusLength = cryptoSystem.getModulusLength();

signDecrypt method, validate the parameters as follows:

• 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

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

signDecrypt method, validate the parameters as follows:

1: Using smart cards

Cryptographic Smart Card Driver Development Guide

Task Steps

Retrieve random data from

> Implement CryptoSmartCardSession.getRandomBytesImpl(int maxNumBytes). the internal random number generator of the smart card.

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

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

SmartCardRSACryptoToken class.

final class MyRSACryptoToken extends SmartCardRSACryptoToken

Determine if the token object can perform authentication for a BlackBerry device user.

Determine if the token object supports the current

CryptoSystem.

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

authentication information.

public boolean providesUserAuthentication()

{

return true;

}

> 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

Determine if the token object and the

CryptoSystem support the type of

encryption scheme.

> 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 method that returns a Boolean value that indicates if the token object supports the specified encryption scheme.

public boolean isSupportedDecryptRSA(RSACryptoSystem cryptoSystem,

CryptoTokenPrivateKeyData privateKeyData)throws

CryptoTokenException

{

return privateKeyData instanceof MyCryptoTokenData;

}

public boolean isSupportedDecryptRSASmartCardImpl( CryptoSystem cryptoSystem,CryptoTokenPrivateKeyData privateKeyData);

Enable decryption of unprocessed data. > 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 method that performs decryption of unprocessed data, for example:

public void decryptRSA(RSACryptoSystem cryptoSystem,

CryptoTokenPrivateKeyData privateKeyData,byte[] input, int

inputOffset,

byte[] output, int outputOffset)throws CryptoTokenException

{

try {//signDecryptHelper is a private helper method.

signDecryptHelper(cryptoSystem, privateKeyData, input, inputOffset,

output, outputOffset, DECRYPT_DESC,

SmartCardSession.DECRYPT_OPERATION);

}

catch (CryptoUnsupportedOperationException e) {

throw new CryptoTokenException(e.toString());

}

public void decryptRSASmartCardImplCryptoSystem cryptoSystem,

CryptoTokenPrivateKeyData privateKeyData, byte[] input, int

inputOffset, byte[] output,int outputOffset)

1: Using smart cards

+ 25 hidden pages

Blackberry JAVA DEVELOPMENT ENVIRONMENT User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Using smart cards

Smart cards

Add support for smart cards

Creating a cryptographic smart card driver

Set up the project for the cryptographic smart card driver

Design a cryptographic smart card driver

Create a cryptographic session for a cryptographic smart card

Create a cryptographic token for private key operations