Many large corporations require two-factor authentications for their internal applications. This usually starts with the login to the office computer, e.g. using smartcards (or other tokens). In order to reasonably protect applications as well, they need to integrate the smartcard authentication. The following sample shows how to access the certificates located on the inserted smartcard using PKCS#11.
The PKCS#11 Configuration
In order to use the PKCS#11 API, a shared library compatible with the smartcard is necessary. With the given library, a configuration needs to be created first.
|
1 2 3 |
name = OpenSCAccelerator library = C:\Windows\System32\opensc-pkcs11.dll slot = 0 |
The name key can be anything. The library key provides the path to the PKCS#11 library to load. The slot key represents the ID of the smartcard reader. This can be anything, but starts with 0. If only one smartcard reader is connected, the value is most-likely 0. An alternative to the slod ID would be slotListIndex.
PKCS#11 Provider Registration
Now with the prepared configuration, there are multiple ways to load it. The used implementation supports both, a file-path or an InputStream. So either locate it somewhere on the file-system, load it from the jar itself or dynamically create it at runtime, e.g. using a ByteArrayInputStream. The following example loads it from the jar.
|
1 2 3 4 |
public static void registerProvider() { Provider provider = new sun.security.pkcs11.SunPKCS11(Pkcs11Sample.class.getResourceAsStream("/pkcs11.cfg")); Security.addProvider(provider); } |
Rather unusual in this sample is, it uses the restricted Sun-API as seen on line 2. This yields the requirement of the Oracle Java runtime (so no OpenJDK). Line 3 registers the instantiated PKCS#11 provider to the security context so it can be accessed whenever necessary.
The Callback Handler
In order to create a KeyStore with the smartcard, the password is necessary. One way would be providing the password right upon instantiation. But in this sample, a single sign-on approach is desired. This means, if the smartcard has already been unlocked (e.g. when unlocking the computer), no more password prompts are necessary. When working with callback handlers, the callback will only be fired if the information is required.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public class ConsoleCallbackHandler implements CallbackHandler { @Override public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException { for(Callback callback : callbacks) { if(!(callback instanceof PasswordCallback)) { throw new UnsupportedCallbackException(callback, "Unrecognized Callback"); } PasswordCallback pc = (PasswordCallback)callback; System.out.println("Please enter your password:"); String password = new BufferedReader(new InputStreamReader(System.in)).readLine(); pc.setPassword(password.toCharArray()); } } } |
The example above will prompt for user’s password using the console. The line 12 will provide the password to the callback. If no password is given (e.g. the user cancels the login), null should be provided to the callback.
PKCS#11 KeyStore
With everything prepared, the KeyStore can finally be created. This is accomplished using the KeyStore.Builder.
|
1 2 3 4 5 |
public static KeyStore createKeyStore() throws KeyStoreException { KeyStore.CallbackHandlerProtection callbackHandler = new KeyStore.CallbackHandlerProtection(new ConsoleCallbackHandler()); KeyStore.Builder builder = KeyStore.Builder.newInstance("PKCS11", null, callbackHandler); return builder.getKeyStore(); } |
Line 3 provides the previously created CallbackHandler to the KeyStore. There are multiple reasons KeyStore creation may fail. Two reasons for exceptions are an invalid password entry or no smartcard has been inserted into the reader at all.
Certificate Access
The now created KeyStore can be used just like any other KeyStore. The main difference is, that the keys are unextractable. But they still can be used for encryption tasks. The following sample shows how to iterate over all aliases and print the associated certificate.
|
1 2 3 4 5 |
public static void printCertificate(KeyStore keyStore) throws KeyStoreException { for(String alias : Collections.list(keyStore.aliases())) { System.out.println(keyStore.getCertificate(alias)); } } |
Moreover, this KeyStore can also be used to prove identity to a remote host using SSL. But this may require selecting the correct alias prior the connection. This may be necessary because there is a high chance that there are multiple certificates located on the smartcard.
Thanks for post.
Now, I can understand how to use callbackhandler with smartcard.
Hello,
I want to get certificate from smart card without pin. How can i do? Thanks.