Java Pkcs 5 Key Generation
- Java Pkcs 5 Key Generation Download
- Java Pkcs 5 Key Generation 2
- Java Pkcs 5 Key Generation 1
- Java Pkcs 5 Key Generation 10
Jun 05, 2008 There are currently 10 standards, numbered 1 through 15 (PKCS#2 and PKCS#4 were merged into PKCS#1; PKCS#13 and PKCS#14 are listed as under development) 5. Of the standards, PKCS#1: RSA Cryptography Standard and PKCS#8: Private-Key Information Syntax Standard are of interest. Example how to create PKCS#10 Certificate Signing Request (CSR) using Sun JDK, This example creates signature externally - suitable for Cryptographic devices such as Hardware Security Module (HSM). The 'jsrsasign' (RSA-Sign JavaScript Library) is an opensource free cryptography library supporting RSA/RSAPSS/ECDSA/DSA signing/validation, ASN.1, PKCS#1/5/8 private/public key, X.509 certificate, CRL, OCSP, CMS SignedData, TimeStamp, CAdES JSON Web Signature/Token in pure JavaScript. kjur/jsrsasign. Creating a KeyStore in PKCS12 Format. This section explains how to create a PKCS12 KeyStore to work with JSSE. In a real working environment, a customer could already have an existing private key and certificate (signed by a known CA). A key may be specified in an algorithm-specific way, or in an algorithm-independent encoding format (such as ASN.1). This package contains key specifications for DSA public and private keys, RSA public and private keys, PKCS #8 private keys in DER-encoded.
In cryptography, PBKDF1 and PBKDF2 (Password-Based Key Derivation Function 2) are key derivation functions with a sliding computational cost, used to reduce vulnerabilities to brute force attacks.
PBKDF2 is part of RSA Laboratories' Public-Key Cryptography Standards (PKCS) series, specifically PKCS #5 v2.0, also published as Internet Engineering Task Force's RFC 2898. It supersedes PBKDF1, which could only produce derived keys up to 160 bits long.[1]RFC 8018 (PKCS #5 v2.1), published in 2017, recommends PBKDF2 for password hashing.[2]
Purpose and operation[edit]
PBKDF2 applies a pseudorandom function, such as hash-based message authentication code (HMAC), to the input password or passphrase along with a salt value and repeats the process many times to produce a derived key, which can then be used as a cryptographic key in subsequent operations. The added computational work makes password cracking much more difficult, and is known as key stretching.
When the standard was written in the year 2000 the recommended minimum number of iterations was 1000, but the parameter is intended to be increased over time as CPU speeds increase. A Kerberos standard in 2005 recommended 4096 iterations;[3] Apple reportedly used 2000 for iOS 3, and 10000 for iOS 4;[4] while LastPass in 2011 used 5000 iterations for JavaScript clients and 100000 iterations for server-side hashing.[5]
Having a salt added to the password reduces the ability to use precomputed hashes (rainbow tables) for attacks, and means that multiple passwords have to be tested individually, not all at once. The standard recommends a salt length of at least 64 bits.[6] The US National Institute of Standards and Technology recommends a salt length of 128 bits.[7]
Key derivation process[edit]
The PBKDF2 key derivation function has five input parameters:[8]
where:
- PRF is a pseudorandom function of two parameters with output length hLen (e.g., a keyed HMAC)
- Password is the master password from which a derived key is generated
- Salt is a sequence of bits, known as a cryptographic salt
- c is the number of iterations desired
- dkLen is the desired bit-length of the derived key
- DK is the generated derived key
Each hLen-bit block Ti of derived key DK, is computed as follows (with + marking string concatenation):
The function F is the xor (^) of c iterations of chained PRFs. The first iteration of PRF uses Password as the PRF key and Salt concatenated with i encoded as a big-endian 32-bit integer as the input. (Note that i is a 1-based index.) Subsequent iterations of PRF use Password as the PRF key and the output of the previous PRF computation as the input:
where:
For example, WPA2 uses:
PBKDF1 had a simpler process: the initial U (called T in this version) is created by PRF(Password + Salt), and the following ones are simply PRF(Uprevious). The key is extracted as the first dkLen bits of the final hash, which is why there is a size limit.[8]
HMAC collisions[edit]
PBKDF2 has an interesting property when using HMAC as its pseudo-random function. It is possible to trivially construct any number of different password pairs with collisions within each pair.[9] If a supplied password is longer than the block size of the underlying HMAC hash function, the password is first pre-hashed into a digest, and that digest is instead used as the password. For example, the following password is too long:
- Password:
plnlrtfpijpuhqylxbgqiiyipieyxvfsavzgxbbcfusqkozwpngsyejqlmjsytrmd
therefore (when for example using HMAC-SHA1) it is pre-hashed using SHA-1 into:
- SHA1 (hex):
65426b585154667542717027635463617226672a
Which can be represented in ASCII as:
- SHA1 (ASCII):
eBkXQTfuBqp'cTcar&g*
This means regardless of the salt or iterations, PBKDF2-HMAC-SHA1 will generate the same key bytes for the passwords:
- 'plnlrtfpijpuhqylxbgqiiyipieyxvfsavzgxbbcfusqkozwpngsyejqlmjsytrmd'
- 'eBkXQTfuBqp'cTcar&g*'
For example, using:
- PRF: HMAC-SHA1
- Salt: A009C1A485912C6AE630D3E744240B04
- Iterations: 1,000
- Derived key length: 16 bytes
the following two function calls:
will generate the same derived key bytes (17EB4014C8C461C300E9B61518B9A18B). These derived key collisions do not represent a security vulnerability – as one still must know the original password in order to generate the hash of the password.[10]
Alternatives to PBKDF2[edit]
One weakness of PBKDF2 is that while its number of iterations can be adjusted to make it take an arbitrarily large amount of computing time, it can be implemented with a small circuit and very little RAM, which makes brute-force attacks using application-specific integrated circuits or graphics processing units relatively cheap.[11] The bcrypt password hashing function requires a larger amount of RAM (but still not tunable separately, i. e. fixed for a given amount of CPU time) and is slightly stronger against such attacks,[12] while the more modern scrypt key derivation function can use arbitrarily large amounts of memory and is therefore more resistant to ASIC and GPU attacks.[11]
In 2013, a Password Hashing Competition (PHC) was held to develop a more resistant approach. On 20 July 2015 Argon2 was selected as the final PHC winner, with special recognition given to four other password hashing schemes: Catena, Lyra2, yescrypt and Makwa.[13]
See also[edit]
References[edit]
- ^<bkaliski@rsasecurity.com>, Burt Kaliski. 'PKCS #5: Password-Based Cryptography Specification Version 2.0'. tools.ietf.org. Retrieved 2015-10-23.
- ^'PKCS #5: Password-Based Cryptography Specification Version 2.1'. tools.ietf.org.
- ^Kenneth Raeburn. 'Advanced Encryption Standard (AES) Encryption for Kerberos 5'. tools.ietf.org. Retrieved 2015-10-23.
- ^'Smartphone Forensics: Cracking BlackBerry Backup Passwords'. Advanced Password Cracking – Insight (ElcomSoft). Retrieved 2015-10-23.
- ^'LastPass Security Notification'. The LastPass Blog. Retrieved 2015-10-23.
- ^K. Moriarty; et al. 'RFC 8018 - PKCS #5: Password-Based Cryptography Specification, Version 2.1'. tools.ietf.org. Retrieved 2018-01-24.
- ^Meltem Sönmez Turan, Elaine Barker, William Burr, and Lily Chen. 'NIST SP 800-132, Recommendation for Password-Based Key Derivation Part 1: Storage Applications'(PDF). www.nist.gov. Retrieved 2018-12-20.CS1 maint: multiple names: authors list (link)
- ^ abRFC2898
- ^https://mathiasbynens.be/notes/pbkdf2-hmac
- ^https://crypto.stackexchange.com/questions/26510/why-is-hmac-sha1-still-considered-secure
- ^ abColin Percival.scrypt.As presented in'Stronger Key Derivation via Sequential Memory-Hard Functions'.presented at BSDCan'09, May 2009.
- ^'New 25 GPU Monster Devours Passwords In Seconds'. The Security Ledger. 2012-12-04. Retrieved 2013-09-07.
- ^'Password Hashing Competition'
External links[edit]
- RSA PKCS #5 – RSA Laboratories PKCS #5 v2.1.
- RFC 2898 – Specification of PKCS #5 v2.0.
- RFC 6070 – Test vectors for PBKDF2 with HMAC-SHA1.
1.0 Introduction
2.0 Sun PKCS#11 Provider
- 2.1 Requirements
- 2.2 Configuration
- 2.3 Accessing Network Security Services (NSS)
3.0 Application Developers
- 3.1 Token Login
- 3.2 Token Keys
- 3.3 Delayed Provider Selection
- 3.4 JAAS KeyStoreLoginModule
- 3.5 Tokens as JSSE Keystores and Trust Stores
4.0 Tools
- 4.1 KeyTool and JarSigner
- 4.2 PolicyTool
5.0 Provider Developers
- 5.1 Provider Services
- 5.1.1 Instantiating Engine Classes
- 5.1.2 Parameter Support
Appendix A Sun PKCS#11 Provider's Supported Algorithms
Appendix B Sun PKCS#11 Provider's KeyStore Restrictions
Appendix C Example Provider
1.0 Introduction
The Java platform defines a set of programming interfaces for performing cryptographic operations. These interfaces are collectively known as the Java Cryptography Architecture (JCA) and the Java Cryptography Extension (JCE). Specifications are available at the Java SE Security Documentation page.
The cryptographic interfaces are provider-based. Specifically, applications talk to Application Programming Interfaces (APIs), and the actual cryptographic operations are performed in configured providers which adhere to a set of Service Provider Interfaces (SPIs). This architecture supports different provider implementations. Some providers may perform cryptographic operations in software; others may perform the operations on a hardware token (for example, on a smartcard device or on a hardware cryptographic accelerator).
The Cryptographic Token Interface Standard, PKCS#11, is produced by RSA Security and defines native programming interfaces to cryptographic tokens, such as hardware cryptographic accelerators and Smartcards. To facilitate the integration of native PKCS#11 tokens into the Java platform, a new cryptographic provider, the Sun PKCS#11 provider, has been introduced into the J2SE 5.0 release. This new provider enables existing applications written to the JCA and JCE APIs to access native PKCS#11 tokens. No modifications to the application are required. The only requirement is the proper configuration of the provider into the Java Runtime.
Although an application can make use of most PKCS#11 features using existing APIs, some applications might need more flexibility and capabilities. For example, an application might want to deal with Smartcards being removed and inserted dynamically more easily. Or, a PKCS#11 token might require authentication for some non-key-related operations and therefore, the application must be able to log into the token without using keystore. In J2SE 5.0, the JCA was enhanced to allow applications greater flexibility in dealing with different providers.
This document describes how native PKCS#11 tokens can be configured into the Java platform for use by Java applications. It also describes the enhancements that were made to the JCA to make it easier for applications to deal with different types of providers, including PKCS#11 providers.
2.0 Sun PKCS#11 Provider
The Sun PKCS#11 provider, in contrast to most other providers, does not implement cryptographic algorithms itself. Instead, it acts as a bridge between the Java JCA and JCE APIs and the native PKCS#11 cryptographic API, translating the calls and conventions between the two. This means that Java applications calling standard JCA and JCE APIs can, without modification, take advantage of algorithms offered by the underlying PKCS#11 implementations, such as, for example,
- Cryptographic Smartcards,
- Hardware cryptographic accelerators, and
- High performance software implementations.
2.1 Requirements
The Sun PKCS#11 provider is supported on Solaris (SPARC and x86) and Linux (x86) in both 32-bit and 64-bit Java processes. It is also supported on 32-bit Windows (x86) but not currently on 64-bit Windows platforms due to the lack of suitable PKCS#11 libraries.The Sun PKCS#11 provider requires an implementation of PKCS#11 v2.0 or later to be installed on the system. This implementation must take the form of a shared-object library (.so on Solaris and Linux) or dynamic-link library (.dll on Windows). Please consult your vendor documentation to find out if your cryptographic device includes such a PKCS#11 implementation, how to configure it, and what the name of the library file is.
The Sun PKCS#11 provider supports a number of algorithms, provided that the underlying PKCS#11 implementation offers them. The algorithms and their corresponding PKCS#11 mechanisms are listed in the table in Appendix A.
2.2 Configuration
The Sun PKCS#11 provider is implemented by the main classsun.security.pkcs11.SunPKCS11 and accepts the full pathname of a configuration file as an argument. To use the provider, you must first install it by using the Java Cryptography Architecture (JCA). As with all JCA providers, installation of the provider can be done either statically or programmatically. To install the provider statically, add the provider to the Java Security properties file ($JAVA_HOME/lib/security/java.security). For example, here's a fragment of the java.security file that installs the Sun PKCS#11 provider with the configuration file /opt/bar/cfg/pkcs11.cfg. To install the provider dynamically, create an instance of the provider with the appropriate configuration filename and then install it. Here is an example. To use more than one slot per PKCS#11 implementation, or to use more than one PKCS#11 implementation, simply repeat the installation for each with the appropriate configuration file. This will result in a Sun PKCS#11 provider instance for each slot of each PKCS#11 implementation.
The configuration file is a text file that contains entries in the following format.
attribute = value The valid values for attribute and value are described in the table in this section. The two mandatory attributes are name and library. Here is a sample configuration file. Comments are denoted by lines starting with the # (number) symbol.| Attribute | Value | Description |
|---|---|---|
| library | pathname of PKCS#11 implementation | This is the full pathname (including extension) of the PKCS#11 implementation; the format of the pathname is platform dependent. For example, /opt/foo/lib/libpkcs11.so might be the pathname of a PKCS#11 implementation on Solaris and Linux while C:foomypkcs11.dll might be one on Windows. |
| name | name suffix of this provider instance | This string is concatenated with the prefix SunPKCS11- to produce this provider instance's name (that is, the string returned by its Provider.getName() method). For example, if the name attribute is 'FooAccelerator', then the provider instance's name will be 'SunPKCS11-FooAccelerator'. |
| description | description of this provider instance | This string will be returned by the provider instance's Provider.getInfo() method. If none is specified, a default description will be returned. |
| slot | slot id | This is the id of the slot that this provider instance is to be associated with. For example, you would use 1 for the slot with the id 1 under PKCS#11. At most one of slot or slotListIndex may be specified. If neither is specified, the default is a slotListIndex of 0. |
| slotListIndex | slot index | This is the slot index that this provider instance is to be associated with. It is the index into the list of all slots returned by the PKCS#11 function C_GetSlotList. For example, 0 indicates the first slot in the list. At most one of slot or slotListIndex may be specified. If neither is specified, the default is a slotListIndex of 0. |
| enabledMechanisms | brace enclosed, whitespace-separated list of PKCS#11 mechanisms to enable | This is the list PKCS#11 mechanisms that this provider instance should use, provided that they are supported by both the Sun PKCS#11 provider and PKCS#11 token. All other mechanisms will be ignored. Each entry in the list is the name of a PKCS#11 mechanism. Here is an example that lists two PKCS#11 mechanisms. At most one of enabledMechanisms or disabledMechanisms may be specified. If neither is specified, the mechanisms enabled are those that are supported by both the Sun PKCS#11 provider and the PKCS#11 token. |
| disabledMechanisms | brace enclosed, whitespace-separated list of PKCS#11 mechanisms to disable | This is the list of PKCS#11 mechanism that this provider instance should ignore. Any mechanism listed will be ignored by the provider, even if they are supported by the token and the Sun PKCS#11 provider. The strings SecureRandom and KeyStore may be specified to disable those services. At most one of enabledMechanisms or disabledMechanisms may be specified. If neither is specified, the mechanisms enabled are those that are supported by both the Sun PKCS#11 provider and the PKCS#11 token. |
| attributes | see below | The attributes option can be used to specify additional PKCS#11 that should be set when creating PKCS#11 key objects. This makes it possible to accommodate tokens that require particular attributes. For details, see the section below. |
Attributes Configuration
The attributes option allows you to specify additional PKCS#11 attributes that should be set when creating PKCS#11 key objects. By default, the SunPKCS11 provider only specifies mandatory PKCS#11 attributes when creating objects. For example, for RSA public keys it specifies the key type and algorithm (CKA_CLASS and CKA_KEY_TYPE) and the key values for RSA public keys (CKA_MODULUS and CKA_PUBLIC_EXPONENT). The PKCS#11 library you are using will assign implementation specific default values to the other attributes of an RSA public key, for example that the key can be used to encrypt and verify messages (CKA_ENCRYPT and CKA_VERIFY = true).The attributes option can be used if you do not like the default values your PKCS#11 implementation assigns or if your PKCS#11 implementation does not support defaults and requires a value to be specified explicitly. Note that specifying attributes that your PKCS#11 implementation does not support or that are invalid for the type of key in question may cause the operation to fail at runtime.
The option can be specified zero or more times, the options are processed in the order specified in the configuration file as described below. The attributes option has the format:
Valid values for operation are:- generate, for keys generated via a KeyPairGenerator or KeyGenerator
- import, for keys created via a KeyFactory or SecretKeyFactory. This also applies to Java software keys automatically converted to PKCS#11 key objects when they are passed to the initialization method of a cryptographic operation, for example Signature.initSign().
- *, for keys created using either a generate or a create operation.
Valid values for keyalgorithm are one of the CKK_xxx constants from the PKCS#11 specification, or * to match keys of any algorithm. The algorithms currently supported by the SunPKCS11 provider are CKK_RSA, CKK_DSA, CKK_DH, CKK_AES, CKK_DES, CKK_DES3, CKK_RC4, CKK_BLOWFISH, and CKK_GENERIC.
The attribute names and values are specified as a list of one or more name-value pairs. name must be a CKA_xxx constant from the PKCS#11 specification, for example CKA_SENSITIVE. value can be one of the following:
- a boolean value, true or false
- an integer, in decimal form (default) or in hexadecimal form if it begins with 0x.
- null, indicating that this attribute should not be specified when creating objects.
There is also a special form of the attributes option. You can write attributes = compatibility in the configuration file. That is a shortcut for a whole set of attribute statements. They are designed to provider maximum compatibility with existing Java applications, which may expect, for example, all key components to be accessible and secret keys to be usable for both encryption and decryption. The compatibility attributes line can be used together with other attributes lines, in which case the same aggregation and overriding rules apply as described earlier.
2.3 Accessing Network Security Services (NSS)
Network Security Services (NSS) is a set of open source security libraries used by the Mozilla/Firefox browsers, Sun's Java Enterprise System server software, and a number of other products. Its crypto APIs are based on PKCS#11 but it includes special features that are outside of the PKCS#11 standard. The Sun PKCS#11 provider includes code to interact with these NSS specific features, including several NSS specific configuration directives, which are described below.
For best results, we recommend that you use the latest version of NSS available. It should be at least version 3.12.
The Sun PKCS#11 provider uses NSS specific code when any of the nss configuration directives described below are used. In that case, the regular configuration commands library, slot, and slotListIndex cannot be used.
| Attribute | Value | Description |
|---|---|---|
| nssLibraryDirectory | directory containing the NSS and NSPR libraries | This is the full pathname of the directory containing the NSS and NSPR libraries. It must be specified unless NSS has already been loaded and initialized by another component running in the same process as the Java VM. Depending on your platform, you may have to set |
| nssSecmodDirectory | directory containing the NSS DB files | The full pathname of the directory containing the NSS configuration and key information (secmod.db, key3.db, and cert8.db). This directive must be specified unless NSS has already been initialized by another component (see above) or NSS is used without database files as described below. |
| nssDbMode | one of readWrite, readOnly, and noDb | This directives determines how the NSS database is accessed. In read-write mode, full access is possible but only one process at a time should be accessing the databases. Read-only mode disallows modifications to the files. The noDb mode allows NSS to be used without database files purely as a cryptographic provider. It is not possible to create persistent keys using the PKCS11 KeyStore. |
| nssModule | one of keystore, crypto, fips, and trustanchors | NSS makes its functionality available using several different libraries and slots. This directive determines which of these modules is accessed by this instance of SunPKCS11. The The The The |
Example SunPKCS11 configuration files for NSS
- NSS as a pure cryptography provider
- NSS as a FIPS 140 compliant crypto token:
3.0 Application Developers
Java applications can use the existing JCA and JCE APIs to access PKCS#11 tokens via the Sun PKCS#11 provider. This is sufficient for many applications but it might be difficult for an application to deal with certain PKCS#11 features, such as unextractable keys and dynamically changing Smartcards. Consequently, a number of enhancements were made to the APIs to better support applications using certain PKCS#11 features. These enhancements are discussed in this section.
3.1 Token Login
Certain PKCS#11 operations, such as accessing private keys, require a login using a Personal Identification Number, or PIN, before the operations can proceed. The most common type of operations that require login are those that deal with keys on the token. In a Java application, such operations often involve first loading the keystore. When accessing the PKCS#11 token as a keystore via the java.security.KeyStore class, you can supply the PIN in the password input parameter to the load method, similar to how applications initialize a keystore prior to J2SE 5.0. The PIN will then be used by the Sun PKCS#11 provider for logging into the token. Here is an example.
This is fine for an application that treats PKCS#11 tokens as static keystores. For an application that wants to accommodate PKCS#11 tokens more dynamically, such as Smartcards being inserted and removed, you can use the new KeyStore.Builder class. Here is an example of how to initialize the builder for a PKCS#11 keystore with a callback handler.
For the Sun PKCS#11 provider, the callback handler must be able to satisfy a PasswordCallback, which is used to prompt the user for the PIN. Whenever the application needs access to the keystore, it uses the builder as follows.
The builder will prompt for a password as needed using the previously configured callback handler. The builder will prompt for a password only for the initial access. If the user of the application continues using the same Smartcard, the user will not be prompted again. If the user removes and inserts a different SmartCard, the builder will prompt for a password for the new card.
Depending on the PKCS#11 token, there may be non-key-related operations that also require token login. Applications that use such operations can use the newly introduced java.security.AuthProvider class. The AuthProvider class extends from java.security.Provider and defines methods to perform login and logout operations on a provider, as well as to set a callback handler for the provider to use.
For the Sun PKCS#11 provider, the callback handler must be able to satisfy a PasswordCallback, which is used to prompt the user for the PIN.
Here is an example of how an application might use an AuthProvider to log into the token.
3.2 Token Keys
Java Key objects may or may not contain actual key material.
- A software Key object does contain the actual key material and allows access to that material.
- An unextractable key on a secure token (such as a Smartcard) is represented by a Java Key object that does not contain the actual key material. The Key object only contains a reference to the actual key.
Applications and providers must use the correct interfaces to represent these different types of Key objects. Software Key objects (or any Key object that has access to the actual key material) should implement the interfaces in the java.security.interfaces and javax.crypto.interfaces packages (such as DSAPrivateKey). Key objects representing unextractable token keys should only implement the relevant generic interfaces in the java.security and javax.crypto packages (PrivateKey, PublicKey, or SecretKey). Identification of the algorithm of a key should be performed using the Key.getAlgorithm() method.
Applications should note that a Key object for an unextractable token key can only be used by the provider associated with that token.
3.3 Delayed Provider Selection
Prior to J2SE 5.0, the Java cryptography getInstance() methods, such as Cipher.getInstance('AES'), returned the implementation from the first provider that implemented the requested algorithm. This is problematic if an application attempts to use a Key object for an unextractable token key with a provider that only accepts software key objects. In such a case, the provider would throw an InvalidKeyException. This is an issue for the Cipher, KeyAgreement, Mac, and Signature classes.
J2SE 5.0, addresses this issue by delaying the selection of the provider until the relevant initialization method is called. The initialization method accepts a Key object and can determine at that point which provider can accept the specified Key object. This ensures that the selected provider can use the specified Key object. The following represents the affected initialization methods.
- Cipher.init(.., Key key, ..)
- KeyAgreement.init(Key key, ..)
- Mac.init(Key key, ..)
- Signature.initSign(PrivateKey privateKey)
Although this delayed provider selection is hidden from the application, it does affect the behavior of the getProvider() method for Cipher, KeyAgreement, Mac, and Signature. If getProvider() is called before the initialization operation has occurred (and therefore before provider selection has occurred), then the first provider that supports the requested algorithm is returned. This may not be the same provider as the one selected after the initialization method is called. If getProvider() is called after the initialization operation has occurred, then the actual selected provider is returned. It is recommended that applications only call getProvider() after they have called the relevant initialization method.
In addition to getProvider(), the following additional methods are similarly affected.
- Cipher.getBlockSize
- Cipher.getExcemptionMechanism
- Cipher.getIV
- Cipher.getOutputSize
- Cipher.getParameters
- Mac.getMacLength
- Signature.getParameters
- Signature.setParameter
3.4 JAAS KeyStoreLoginModule
Java SE comes with a JAAS keystore login module, KeyStoreLoginModule that allows an application to authenticate using its identity in a specified keystore. After authentication, the application would have acquire its principal and credentials information (certificate and private key) from the keystore. By using this login module and configuring it to use a PKCS#11 token as a keystore, the application can acquire this information from a PKCS#11 token.Use the following options to configure the KeyStoreLoginModule to use a PKCS#11 token as the keystore.
- keyStoreURL='NONE'
- keyStoreType='PKCS11'
- keyStorePasswordURL=some_pin_url
Java Pkcs 5 Key Generation Download
where some_pin_url is the location of the PIN. If the keyStorePasswordURL option is omitted, then the login module will get the PIN via the application's callback handler, supplying it with a PasswordCallback. Here is an example of a configuration file that uses a PKCS#11 token as a keystore.If more than one Sun PKCS#11 provider has been configured dynamically or in the java.security security properties file, you can use the keyStoreProvider option to target a specific provider instance. The argument to this option is the name of the provider. For the Sun PKCS#11 provider, the provider name is of the form SunPKCS11-TokenName, where TokenName is the name suffix that the provider instance has been configured with, as detailed in the configuration attributes table. For example, the following configuration file names the PKCS#11 provider instance with name suffix SmartCard.
Some PKCS#11 tokens support login via a protected authentication path. For example, a Smartcard may have a dedicated PIN-pad to enter the pin. Biometric devices will also have their own means to obtain authentication information. If the PKCS#11 token has a protected authentication path, then use the protected=true option and omit the keyStorePasswordURL option. Here is an example of a configuration file for such a token.
3.5 Tokens as JSSE Keystore and Trust Stores
To use PKCS#11 tokens as JSSE keystores or trust stores, the JSSE application can use the APIs described previously to instantiate a KeyStore that is backed by a PKCS#11 token and pass it to its key manager and trust manager. The JSSE application will then have access to the keys on the token.JSSE also supports configuring the use of keystores and trust stores via system properties, as described in the JSSE Reference Guide. To use a PKCS#11 token as a keystore or trust store, set the javax.net.ssl.keyStoreType and javax.net.ssl.trustStoreType system properties, respectively, to 'PKCS11', and set the javax.net.ssl.keyStore and javax.net.ssl.trustStore system properties, respectively, to NONE. To specify the use of a specific provider instance, use the javax.net.ssl.keyStoreProvider and javax.net.ssl.trustStoreProvider system properties (e.g., 'SunPKCS11-SmartCard').
4.0 Tools
In J2SE 5.0, the security tools were updated to support operations using the new Sun PKCS#11 provider. The changes are discussed below.
4.1 KeyTool and JarSigner
If the Sun PKCS#11 provider has been configured in the java.security security properties file (located in the $JAVA_HOME/lib/security directory of the Java runtime), then keytool and jarsigner can be used to operate on the PKCS#11 token by specifying the following options.
- -keystore NONE
- -storetype PKCS11
If more than one Sun PKCS#11 provider has been configured in the java.security security properties file, you can use the -providerName option to target a specific provider instance. The argument to this option is the name of the provider.
- -providerName providerName
Java Pkcs 5 Key Generation 2
is the name suffix that the provider instance has been configured with, as detailed in the configuration attributes table. For example, the following command lists the contents of the PKCS#11 keystore provider instance with name suffix SmartCard.If the Sun PKCS#11 provider has not been configured in the java.security security properties file, you can use the following options to instruct keytool and jarsigner to install the provider dynamically.
- -providerClass sun.security.pkcs11.SunPKCS11
- -providerArg ConfigFilePath
4.2 PolicyTool
Prior to J2SE 5.0, the keystore entry in the default policy implementation had the following syntax.
This syntax was inadequate for accessing a PKCS#11 keystore because such access usually required a PIN, and there might be multiple PKCS#11 provider instances. To accommodate these requirements, the keystore entry syntax has been updated in J2SE 5.0, to the following. Where keystore_provider is the keystore provider name (for example, 'SunPKCS11-SmartCard'), and some_password_url is a URL pointing to the location of the token PIN. Both keystore_provider and the keystorePasswordURL line are optional. If keystore_provider has not been specified, then the first configured provider that supports the specified keystore type is used. If the keystorePasswordURL line has not been specified, then no password is used.The following is an example keystore policy entry for a PKCS#11 token.
5.0 Provider Developers
J2SE 5.0 introduces new facilities in the java.security.Provider class for provider implementations to more easily support PKCS#11 tokens and cryptographic services in general. These new facilities are discussed below.
See Appendix C for an example of a simple provider designed to demonstrate the new facilities.
5.1 Provider Services
As described in the above provider documentation, prior to J2SE 5.0, providers were required to create java.util.Property entries describing the services they supported. For each service implemented by the provider, there must be a property whose name is the type of service (Cipher, Signature, etc), followed by a period and the name of the algorithm to which the service applies. The property value must specify the fully qualified name of the class implementing the service. Here is an example of a provider setting KeyAgreement.DiffieHellman property to have the value com.sun.crypto.provider.DHKeyAgreement.
J2SE 5.0 introduces a new public static nested class, Provider.Service, to help better encapsulate the properties of a provider service (including its type, attributes, algorithm name, and algorithm aliases). Providers can instantiate Provider.Service objects and register them by calling the Provider.putService() method. This is equivalent to creating a Property entry and calling the Provider.put() method (as was done prior to J2SE 5.0). Note that legacy Property entries registered via Provider.put are still supported.
Here is an example of a provider creating a Service object with the KeyAgreement type, for the DiffieHellman algorithm, implemented by the class com.sun.crypto.provider.DHKeyAgreement.
Using Provider.Service objects instead of legacy Property entries has a couple of major benefits. One benefit is that it allows the provider to have greater flexibility when instantiating engine classes. Another benefit is that it allows the provider to test parameter validity. These features are discussed in detail next.
5.1.1 Instantiating Engine Classes
Prior to J2SE 5.0, the Java Cryptography framework looked up the provider property for a particular service and directly instantiated the engine class registered for that property. J2SE 5.0, has the same behavior by default, but allows the provider to override this behavior and instantiate the engine class for the requested service itself.
To override the default behavior, the provider overrides the Provider.Service.newInstance() method to add its customer behavior. For example, the provider might call a custom constructor, or might perform initialization using information not accessible outside the provider (or that are only known by the provider).
5.1.2 Parameter Support
The Java Cryptography framework may attempt a fast check to determine whether a provider's service implementation can use an application-specified parameter. To perform this fast check, the framework calls Provider.Service.supportsParameter().
In J2SE 5.0, the framework relies on this fast test during delayed provider selection. When an application invokes an initialization method and passes it a Key object, the framework asks an underlying provider whether it supports the object by calling its Service.supportsParameter() method. If supportsParameter() returns false, the framework can immediately remove that provider from consideration. If supportsParameter() returns true, the framework passes the Key object to that provider's initialization engine class implementation. A provider that requires software Key objects should override this method to return false when it is passed non-software keys. Likewise, a provider for a PKCS#11 token that contains unextractable keys should only return true for Key objects that it created, and which therefore correspond to the Keys on its respective token.
Note that the default implementation of supportsParameter() returns true. This allows existing providers to work without modification. However, because of this lenient default implementation, the framework must be prepared to catch exceptions thrown by providers that reject the Key object inside their initialization engine class implementations. The framework treats these cases the same as when supportsParameter() returns false.
Appendix A: Sun PKCS#11 Provider's Supported Algorithms
The following table lists the Java algorithms supported by the Sun PKCS#11 provider and corresponding PKCS#11 mechanisms needed to support them. When multiple mechanisms are listed, they are given in the order of preference and any one of them is sufficient. Note that SunPKCS11 can be instructed to ignore mechanisms by using thedisabledMechanisms and enabledMechanismsconfiguration directives. For Elliptic Curve mechanisms, SunPKCS11 will only use keys that use the namedCurve choice as encoding for the parameters and only allow the uncompressed point format. The Sun PKCS#11 provider assumes that a token supports all standard named domain parameters.
| Java Algorithm | PKCS#11 Mechanisms |
|---|---|
| Signature.MD2withRSA | CKM_MD2_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509 |
| Signature.MD5withRSA | CKM_MD5_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509 |
| Signature.SHA1withRSA | CKM_SHA1_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509 |
| Signature.SHA256withRSA | CKM_SHA256_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509 |
| Signature.SHA384withRSA | CKM_SHA384_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509 |
| Signature.SHA512withRSA | CKM_SHA512_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509 |
| Signature.SHA1withDSA | CKM_DSA_SHA1, CKM_DSA |
| Signature.NONEwithDSA | CKM_DSA |
| Signature.SHA1withECDSA | CKM_ECDSA_SHA1, CKM_ECDSA |
| Signature.SHA256withECDSA | CKM_ECDSA |
| Signature.SHA384withECDSA | CKM_ECDSA |
| Signature.SHA512withECDSA | CKM_ECDSA |
| Signature.NONEwithECDSA | CKM_ECDSA |
| Cipher.RSA/ECB/PKCS1Padding | CKM_RSA_PKCS |
| Cipher.ARCFOUR | CKM_RC4 |
| Cipher.DES/CBC/NoPadding | CKM_DES_CBC |
| Cipher.DESede/CBC/NoPadding | CKM_DES3_CBC |
| Cipher.AES/CBC/NoPadding | CKM_AES_CBC |
| Cipher.Blowfish/CBC/NoPadding | CKM_BLOWFISH_CBC |
| Cipher.RSA/ECB/NoPadding | CKM_RSA_X_509 |
| Cipher.AES/CTR/NoPadding | CKM_AES_CTR |
| KeyAgreement.ECDH | CKM_ECDH1_DERIVE |
| KeyAgreement.DiffieHellman | CKM_DH_PKCS_DERIVE |
| KeyPairGenerator.RSA | CKM_RSA_PKCS_KEY_PAIR_GEN |
| KeyPairGenerator.DSA | CKM_DSA_KEY_PAIR_GEN |
| KeyPairGenerator.EC | CKM_EC_KEY_PAIR_GEN |
| KeyPairGenerator.DiffieHellman | CKM_DH_PKCS_KEY_PAIR_GEN |
| KeyGenerator.ARCFOUR | CKM_RC4_KEY_GEN |
| KeyGenerator.DES | CKM_DES_KEY_GEN |
| KeyGenerator.DESede | CKM_DES3_KEY_GEN |
| KeyGenerator.AES | CKM_AES_KEY_GEN |
| KeyGenerator.Blowfish | CKM_BLOWFISH_KEY_GEN |
| Mac.HmacMD5 | CKM_MD5_HMAC |
| Mac.HmacSHA1 | CKM_SHA_1_HMAC |
| Mac.HmacSHA256 | CKM_SHA256_HMAC |
| Mac.HmacSHA384 | CKM_SHA384_HMAC |
| Mac.HmacSHA512 | CKM_SHA512_HMAC |
| MessageDigest.MD2 | CKM_MD2 |
| MessageDigest.MD5 | CKM_MD5 |
| MessageDigest.SHA1 | CKM_SHA_1 |
| MessageDigest.SHA-256 | CKM_SHA256 |
| MessageDigest.SHA-384 | CKM_SHA384 |
| MessageDigest.SHA-512 | CKM_SHA512 |
| KeyFactory.RSA | Any supported RSA mechanism |
| KeyFactory.DSA | Any supported DSA mechanism |
| KeyFactory.EC | Any supported EC mechanism |
| KeyFactory.DiffieHellman | Any supported Diffie-Hellman mechanism |
| SecretKeyFactory.ARCFOUR | CKM_RC4 |
| SecretKeyFactory.DES | CKM_DES_CBC |
| SecretKeyFactory.DESede | CKM_DES3_CBC |
| SecretKeyFactory.AES | CKM_AES_CBC |
| SecretKeyFactory.Blowfish | CKM_BLOWFISH_CBC |
| SecureRandom.PKCS11 | CK_TOKEN_INFO has the CKF_RNG bit set |
| KeyStore.PKCS11 | Always available |
Appendix B: Sun PKCS#11 provider's KeyStore Requirements
The following describes the requirements placed by the Sun PKCS#11 Provider's KeyStore implementation on the underlying native PKCS#11 library. Note that changes may be made in future releases to maximize interoperability with as many existing PKCS#11 libraries as possible.
Read-Only Access
To map existing objects stored on a PKCS#11 token to KeyStore entries, the Sun PKCS#11 Provider's KeyStore implementation performs the following operations.
- A search for all private key objects on the token is performed by calling C_FindObjects[Init Final]. The search template includes the following attributes:
- CKA_TOKEN = true
- CKA_CLASS = CKO_PRIVATE_KEY
- A search for all certificate objects on the token is performed by calling C_FindObjects[Init Final]. The search template includes the following attributes:
- CKA_TOKEN = true
- CKA_CLASS = CKO_CERTIFICATE
- Each private key object is matched with its corresponding certificate by retrieving their respective CKA_ID attributes. A matching pair must share the same unique CKA_ID.
/generate-ms-office-key-online.html. For each matching pair, the certificate chain is built by following the issuer->subject path. From the end entity certificate, a call to C_FindObjects[Init Final] is made with a search template that includes the following attributes:
- CKA_TOKEN = true
- CKA_CLASS = CKO_CERTIFICATE
- CKA_SUBJECT = [DN of certificate issuer]
This search is continued until either no certificate for the issuer is found, or until a self-signed certificate is found. If more than one certificate is found the first one is used.
Once a private key and certificate have been matched (and its certificate chain built), the information is stored in a private key entry with the CKA_LABEL value from end entity certificate as the KeyStore alias.
If the end entity certificate has no CKA_LABEL, then the alias is derived from the CKA_ID. If the CKA_ID can be determined to consist exclusively of printable characters, then a String alias is created by decoding the CKA_ID bytes using the UTF-8 charset. Otherwise, a hex String alias is created from the CKA_ID bytes ('0xFFFF..', for example).
If multiple certificates share the same CKA_LABEL, then the alias is derived from the CKA_LABEL plus the end entity certificate issuer and serial number ('MyCert/CN=foobar/1234', for example).
- Each certificate not part of a private key entry (as the end entity certificate) is checked whether it is trusted. If the CKA_TRUSTED attribute is true, then a KeyStore trusted certificate entry is created with the CKA_LABEL value as the KeyStore alias. If the certificate has no CKA_LABEL, or if multiple certificates share the same CKA_LABEL, then the alias is derived as described above.
If the CKA_TRUSTED attribute is not supported then no trusted certificate entries are created.
- Any private key or certificate object not part of a private key entry or trusted certificate entry is ignored.
- A search for all secret key objects on the token is performed by calling C_FindObjects[Init Final]. The search template includes the following attributes:
- CKA_TOKEN = true
- CKA_CLASS = CKO_SECRET_KEY
A KeyStore secret key entry is created for each secret key object, with the CKA_LABEL value as the KeyStore alias. Each secret key object must have a unique CKA_LABEL.
Write Access
To create new KeyStore entries on a PKCS#11 token to KeyStore entries, the Sun PKCS#11 Provider's KeyStore implementation performs the following operations.
- When creating a KeyStore entry (during KeyStore.setEntry, for example), C_CreateObject is called with CKA_TOKEN=true to create token objects for the respective entry contents.
Private key objects are stored with CKA_PRIVATE=true. The KeyStore alias (UTF8-encoded) is set as the CKA_ID for both the private key and the corresponding end entity certificate. The KeyStore alias is also set as the CKA_LABEL for the end entity certificate object.
Each certificate in a private key entry's chain is also stored. The CKA_LABEL is not set for CA certificates. If a CA certificate is already in the token, a duplicate is not stored.
Secret key objects are stored with CKA_PRIVATE=true. The KeyStore alias is set as the CKA_LABEL.
- If an attempt is made to convert a session object to a token object (for example, if KeyStore.setEntry is called and the private key object in the specified entry is a session object), then C_CopyObject is called with CKA_TOKEN=true.
- If multiple certificates in the token are found to share the same CKA_LABEL, then the write capabilities to the token are disabled.
- Since the PKCS#11 specification does not allow regular applications to set CKA_TRUSTED=true (only token initialization applications may do so), trusted certificate entries can not be created.
Miscellaneous
In addition to the searches listed above, the following searches may be used by the Sun PKCS#11 provider's KeyStore implementation to perform internal functions. Specifically, C_FindObjects[Init Final] may be called with any of the following attribute templates: