Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - CRYPTOGRAPHIC SMART CARD DRIVER - DEVELOPMENT... User manual

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, 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

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

4
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().

5
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

6
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