Page 3
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.
Store the location of the private key file....................8 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.....................
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.
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: Set up the project for the cryptographic smart card driver.
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, getKeyStoreDataArrayImp...
MyRSACryptoToken extends SmartCardRSACryptoToken Determine if the token object can perform > Create a method that returns true if your token object prompts the BlackBerry device user for authentication for a BlackBerry device authentication information. user. public boolean providesUserAuthentication() return true;...
Page 11
CryptoSystem support the type of • To create a cryptographic smart card driver that is compatible with BlackBerry Device encryption scheme. 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.
Store the location of the private key file Even though the private key file is stored on the smart card, the BlackBerry device needs to know that a private key CryptoTokenPrivateKeyData file exists for a certificate. A class that implements the interface can act as a pointer to a private key file on the smart card.
Page 13
1: Using smart cards Task Steps Retrieve the location of the private key file > Create a method that returns the location of the private key file on the smart card. on the smart card. public byte getFile() return _file; See “Code sample: Storing the location of a private key file on the smart card”...
Page 14
Cryptographic Smart Card Driver Development Guide...
Set up the BlackBerry Device Simulator to test a cryptographic smart card driver To test a cryptographic smart card driver with the BlackBerry® Device Simulator, you require the Casira® End Point. Visit Cambridge Silicon Radio Lt. at www.btdesigner.com/devcasira.htm for more information.
Support package for BlackBerry smartphones on your computer or a BlackBerry device. 2. Connect the BlackBerry device to the computer. 3. At a command prompt, switch to the BlackBerry Java Development Environment bin folder. 4. Type the following command: JavaLoader [-usb] [-wpassword] load <file>...
Page 17
2: Testing a cryptographic smart card driver...
Page 18
Cryptographic Smart Card Driver Development Guide...
String DISPLAY_SETTINGS = “Show driver properties/settings now”; private static final String RSA = “RSA”; * This method is invoked when the BlackBerry device starts and registers this * cryptographic smart card driver with the smart card factory.
Page 20
* to communicate with a physical smart card that has the given AnswerToReset. * The system invokes this method to ascertain which smart card implementation it should * use to communicate with a physical smart card found in a BlackBerry Smart Card Reader. protected boolean checkAnswerToResetImpl( AnswerToReset atr ) // If this method returns false, the cryptographic smart card driver will not be used to // perform additional operations on a particular smart card.
Page 21
3: Code samples * Retrieves this smart card’s capabilities protected SmartCardCapabilities getCapabilitiesImpl() return new SmartCardCapabilities( SmartCardCapabilities.PROTOCOL_T0 ); * Determine if this smart card can display its settings. protected boolean isDisplaySettingsAvailableImpl( Object context ) return true; * Display this smart card’s settings. * This method will be invoked from the smart card options screen when * the user selects the driver and chooses to view the settings of that driver.
Cryptographic Smart Card Driver Development Guide return new MyRSACryptoToken(); throw new NoSuchAlgorithmException(); Code sample: Creating a cryptographic session for a cryptographic smart card driver Example: MyCryptoSmartCardSession.java * MyCryptoSmartCardSession.java * Copyright (C) 2001-2007 Research In Motion Limited. All rights reserved. package com.rim.samples.device.smartcard; import net.rim.device.api.crypto.*;...
Page 23
3: Code samples * Construct a new MyCryptoSmartCardSession object. * @param smartCard Smart card associated with this session * @param readerSession Reader session commands sent to this smart card. protected MyCryptoSmartCardSession( SmartCard smartCard, SmartCardReaderSession readerSession ) super( smartCard, readerSession ); * Close this cryptographic smart card session.
Page 24
* Note: * If your cryptographic smart card driver is only designed to work with * BlackBerry Version 4.2 or later, you can replace this method with a call to * CryptoByteArrayArithmetic.valueOf( byte [] ). private long byteArrayToLong( byte[] array ) if ( array == null ) { throw new IllegalArgumentException();...
Page 25
3: Code samples if ( zeros != 0 ) { array = Arrays.copy( array, zeros, array.length - zeros ); int length = array.length; if( length > 8 ) { throw new IllegalArgumentException(); long n = 0; for( int i=0; i<length; i++ ) { n <<= 8;...
Page 26
Cryptographic Smart Card Driver Development Guide RSACryptoToken token = new MyRSACryptoToken(); RSACryptoSystem cryptoSystem = new RSACryptoSystem( token, 1024 ); RSAPrivateKey privateKey; CryptoSmartCardKeyStoreData[] keyStoreDataArray = new CryptoSmartCardKeyStoreData[ 3 ]; // This encoding would be extracted from the card using a series of APDU commands.
Page 27
3: Code samples * Send some data to the smart card for signing or decryption. /*package*/ void signDecrypt( RSACryptoSystem cryptoSystem, MyCryptoTokenData privateKeyData,byte[] input, int inputOffset, byte[] output, int outputOffset ) throws SmartCardException // Check for nulls if ( cryptoSystem == null || privateKeyData == null || input == null || output == null) { throw new IllegalArgumentException();...
Cryptographic Smart Card Driver Development Guide Code sample: Enabling a CryptoToken object for RSA operations using a private key Example: MyRSACryptoToken.java * MyRSACryptoToken.java * Copyright (C) 2001-2007 Research In Motion Limited. All rights reserved. package com.rim.samples.device.smartcard; import net.rim.device.api.smartcard.*; import net.rim.device.api.crypto.*; import net.rim.device.api.crypto.keystore.*;...
Page 29
* If the RSACryptoToken removes the padding in the input data, this method must re-add * the same type of padding before the method completes its operations. * Data encrypted using the BlackBerry S/MIME implementation currently uses Public-Key Cryptography Standards (PKCS) #1 * padding but may use other padding methods in the future.
Page 30
* to the data. If the RSA Crypto token is unable to re-apply the same type of padding, * this method should throw an UnsupportedOperationException. * Signature requests which come from BlackBerry's S/MIME implementation currently use * Public-Key Cryptography Standards (PKCS) #1 padding but may use other padding methods in the future.
Page 31
3: Code samples signDecryptHelper( cryptoSystem, privateKeyData, input, inputOffset, output, outputOffset, SIGN_DESC, SmartCardSession.SIGN_OPERATION ); * Help signing and decryption operations. * This helper method assists data signing and decryption because * the operations are very similar. private void signDecryptHelper( RSACryptoSystem cryptoSystem, CryptoTokenPrivateKeyData privateKeyData, byte[] input, int inputOffset, byte[] output, int outputOffset,String accessReason,int operation ) throws CryptoTokenException, CryptoUnsupportedOperationException...
Cryptographic Smart Card Driver Development Guide Code sample: Storing the location of a private key file on the smart card Example: MyCryptoTokenData.java * MyCryptoTokenData.java * Copyright (C) 2001-2007 Research In Motion Limited. All rights reserved. package com.rim.samples.device.smartcard; import net.rim.device.api.crypto.*; import net.rim.device.api.smartcard.*; import net.rim.device.api.util.*;...
Page 33
3: Code samples * Retrieve the ID of the key file containing the private key file. * @return ID of the smart card. public SmartCardID getSmartCardID() return _id; * Retrieve the location of the private key file on the smart card. * @return Location of the private key file.
Page 34
Cryptographic Smart Card Driver Development Guide...