Package Slot Missing From Signature For Generic
The signature argument specifies classes, corresponding to formal arguments of the generic function; to be precise, to the signature slot of the generic function object. The argument may be a vector of strings identifying classes, and may be named or not. Names, if supplied, match the names of those formal arguments included in the signature of the generic. How to properly document S4 methods using roxygen2. Ask Question Asked 8 years, 2 months ago. Somehow, this is not completely being understood by R CMD check. The not-so-missing documentation of S4 methods - is because of quotation marks being added erroneously around the alias tags when the S4 naming.
1.0 Introduction
2.0 Sun PKCS#11 Provider
- 2.1 Requirements
- 2.2 Configuration
- 2.3 Accessing Network Security Services(NSS)
- 2.4 Troubleshooting PKCS#11
- 2.5 Disabling PKCS#11
- 2.5.1 Disabling PKCS#11Providers
- 2.5.2 Disabling SpecificMechanisms
3.0 Application Developers
- 3.1 Token Login
- 3.2 Token Keys
- 3.3 Delayed ProviderSelection
- 3.4 JAAS KeyStoreLoginModule
- 3.5 Tokens as JSSE Keystores and TrustStores
4.0 Tools
- 4.1 KeyTool and JarSigner
- 4.2 PolicyTool
5.0 Provider Developers
- 5.1 Provider Services
- 5.1.1 Instantiating EngineClasses
- 5.1.2 Parameter Support
Appendix A Sun PKCS#11 Provider's SupportedAlgorithms
Appendix B Sun PKCS#11Provider's KeyStore Restrictions
Appendix C Example Provider
1.0 Introduction
The Java platform defines a set of programming interfaces forperforming cryptographic operations. These interfaces arecollectively known as the Java Cryptography Architecture (JCA) andthe Java Cryptography Extension (JCE). Specifications are availableat the Java SE Security Documentationpage.
The cryptographic interfaces are provider-based. Specifically,applications talk to Application Programming Interfaces (APIs), andthe actual cryptographic operations are performed in configuredproviders which adhere to a set of Service Provider Interfaces(SPIs). This architecture supports different providerimplementations. Some providers may perform cryptographicoperations in software; others may perform the operations on ahardware token (for example, on a smartcard device or on a hardwarecryptographic accelerator).
The Cryptographic Token Interface Standard, PKCS#11, is producedby RSA Security and defines native programming interfaces tocryptographic tokens, such as hardware cryptographic acceleratorsand Smartcards. To facilitate the integration of native PKCS#11tokens into the Java platform, a new cryptographic provider, theSun PKCS#11 provider, has been introduced into the J2SE 5.0release. This new provider enables existing applications written tothe JCA and JCE APIs to access native PKCS#11 tokens. Nomodifications to the application are required. The only requirementis the proper configuration of the provider into the JavaRuntime.
Although an application canmake use of most PKCS#11 features using existing APIs, someapplications might need more flexibility and capabilities. Forexample, an application might want to deal with Smartcards beingremoved and inserted dynamically more easily. Or, a PKCS#11 tokenmight require authentication for some non-key-related operationsand therefore, the application must be able to log into the tokenwithout using keystore. In J2SE 5.0, the JCA was enhanced to allowapplications greater flexibility in dealing with differentproviders.
This document describes how native PKCS#11 tokens can beconfigured into the Java platform for use by Java applications. Italso describes the enhancements that were made to the JCA to makeit easier for applications to deal with different types ofproviders, 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, itacts as a bridge between the Java JCA and JCE APIs and the nativePKCS#11 cryptographic API, translating the calls and conventionsbetween the two. This means that Java applications calling standardJCA and JCE APIs can, without modification, take advantage ofalgorithms offered by the underlying PKCS#11 implementations, suchas, 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 andx86), Linux (x86), and Windows platforms in both 32-bit and 64-bitJava processes.
The Sun PKCS#11 provider requires an implementation of PKCS#11v2.0 or later to be installed on the system. This implementationmust take the form of a shared-object library (.so on Solaris andLinux) or dynamic-link library (.dll on Windows). Please consultyour vendor documentation to find out if your cryptographic deviceincludes such a PKCS#11 implementation, how to configure it, andwhat 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 arelisted 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 fullpathname of a configuration file as an argument. To use theprovider, you must first install it by using the Java CryptographyArchitecture (JCA). As with all JCA providers, installation ofthe provider can be done either statically or programmatically. Toinstall the provider statically, add the provider to the JavaSecurity properties file($JAVA_HOME/lib/security/java.security). For example,here's a fragment of the java.security file that installsthe Sun PKCS#11 provider with the configuration file/opt/bar/cfg/pkcs11.cfg.To install the provider dynamically, create an instance of theprovider with the appropriate configuration filename and theninstall it. Here is an example.To use more than one slot per PKCS#11 implementation, or to usemore than one PKCS#11 implementation, simply repeat theinstallation for each with the appropriate configuration file. Thiswill result in a Sun PKCS#11 provider instance for each slot ofeach PKCS#11 implementation.
The configuration file is a text file that contains entries inthe following format.
attribute = value The valid values forattribute and value are described in the table inthis section. The two mandatory attributes are name andlibrary. 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#11implementation; the format of the pathname is platform dependent.For example, /opt/foo/lib/libpkcs11.so might be thepathname of a PKCS#11 implementation on Solaris and Linux whileC:foomypkcs11.dll might be the pathname onWindows. |
| 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 stringreturned by its Provider.getName() method). Forexample, if the name attribute is'FooAccelerator', then the provider instance's name willbe 'SunPKCS11-FooAccelerator'. |
| description | description of this provider instance | This string will be returned by the provider instance'sProvider.getInfo() method. If none is specified, adefault description will be returned. |
| slot | slot id | This is the id of the slot that this provider instance is to beassociated with. For example, you would use 1 for theslot with the id 1 under PKCS#11. At most one ofslot or slotListIndex may be specified. Ifneither is specified, the default is a slotListIndex of0. |
| slotListIndex | slot index | This is the slot index that this provider instance is to beassociated with. It is the index into the list of all slotsreturned by the PKCS#11 function C_GetSlotList. Forexample, 0 indicates the first slot in the list. Atmost one of slot or slotListIndex may bespecified. If neither is specified, the default is aslotListIndex of 0. |
| enabledMechanisms | brace enclosed, whitespace-separated list of PKCS#11 mechanismsto enable | This is the list PKCS#11 mechanisms that this provider instanceshould use, provided that they are supported by both the SunPKCS#11 provider and PKCS#11 token. All other mechanisms will beignored. 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 ordisabledMechanisms may be specified. If neither isspecified, the mechanisms enabled are those that are supported byboth the Sun PKCS#11 provider and the PKCS#11token. |
| disabledMechanisms | brace enclosed, whitespace-separated list of PKCS#11 mechanismsto disable | This is the list of PKCS#11 mechanism that this providerinstance should ignore. Any mechanism listed will be ignored by theprovider, even if they are supported by the token and the SunPKCS#11 provider. The strings SecureRandom andKeyStore may be specified to disable those services.At most one of enabledMechanisms ordisabledMechanisms may be specified. If neither isspecified, the mechanisms enabled are those that are supported byboth the Sun PKCS#11 provider and the PKCS#11token. |
| attributes | see below | The attributes option can be used to specifyadditional PKCS#11 that should be set when creating PKCS#11 keyobjects. This makes it possible to accommodate tokens that requireparticular attributes. For details, see the section below. |
Attributes Configuration
The attributes option allows you to specify additional PKCS#11attributes that should be set when creating PKCS#11 key objects. Bydefault, the SunPKCS11 provider only specifies mandatory PKCS#11attributes when creating objects. For example, for RSA public keysit specifies the key type and algorithm (CKA_CLASS andCKA_KEY_TYPE) and the key values for RSA public keys (CKA_MODULUSand CKA_PUBLIC_EXPONENT). The PKCS#11 library you are using willassign implementation specific default values to the otherattributes of an RSA public key, for example that the key can beused to encrypt and verify messages (CKA_ENCRYPT and CKA_VERIFY =true).The attributes option can be used if you do not likethe default values your PKCS#11 implementation assigns or if yourPKCS#11 implementation does not support defaults and requires avalue to be specified explicitly. Note that specifying attributesthat your PKCS#11 implementation does not support or that areinvalid for the type of key in question may cause the operation tofail at runtime.
The option can be specified zero or more times, the options areprocessed in the order specified in the configuration file asdescribed below. The attributes option has the format:
Valid values for operation are:- generate, for keys generated via a KeyPairGenerator orKeyGenerator
- import, for keys created via a KeyFactory orSecretKeyFactory. This also applies to Java software keysautomatically converted to PKCS#11 key objects when they are passedto the initialization method of a cryptographic operation, forexample Signature.initSign().
- *, for keys created using either a generate or acreate operation.
Valid values for keyalgorithm are one of theCKK_xxx constants from the PKCS#11 specification, or* to match keys of any algorithm. The algorithms currentlysupported by the SunPKCS11 provider are CKK_RSA, CKK_DSA, CKK_DH,CKK_AES, CKK_DES, CKK_DES3, CKK_RC4, CKK_BLOWFISH, andCKK_GENERIC.
The attribute names and values are specified as a list of one ormore name-value pairs. name must be a CKA_xxxconstant from the PKCS#11 specification, for exampleCKA_SENSITIVE. value can be one of thefollowing:
- a boolean value, true or false
- an integer, in decimal form (default) or in hexadecimal form ifit begins with 0x.
- null, indicating that this attribute shouldnot be specified when creating objects.
There is also a special form of the attributes option.You can write attributes = compatibility in theconfiguration file. That is a shortcut for a whole set of attributestatements. They are designed to provider maximum compatibilitywith existing Java applications, which may expect, for example, allkey components to be accessible and secret keys to be usable forboth encryption and decryption. The compatibilityattributes line can be used together with other attributeslines, in which case the same aggregation and overriding rulesapply as described earlier.
2.3 Accessing Network Security Services (NSS)
NetworkSecurity Services (NSS) is a set of open source securitylibraries used by the Mozilla/Firefox browsers, Sun's JavaEnterprise System server software, and a number of other products.Its crypto APIs are based on PKCS#11 but it includes specialfeatures that are outside of the PKCS#11 standard. The Sun PKCS#11provider includes code to interact with these NSS specificfeatures, including several NSS specific configuration directives,which are described below.
For best results, we recommend that you use the latest versionof NSS available. It should be at least version 3.12.
The Sun PKCS#11 provider uses NSS specific code when any of thenss configuration directives described below are used.In that case, the regular configuration commandslibrary, slot, andslotListIndex cannot be used.
| Attribute | Value | Description |
|---|---|---|
| nssLibraryDirectory | directory containing the NSS and NSPR libraries | This is the full pathname of the directory containing the NSSand NSPRlibraries. It must be specified unless NSS has already been loadedand initialized by another component running in the same process asthe 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 NSSconfiguration and key information (secmod.db,key3.db, and cert8.db). This directivemust be specified unless NSS has already been initialized byanother component (see above) or NSS is used without database filesas described below. |
| nssDbMode | one of readWrite, readOnly, andnoDb | This directives determines how the NSS database is accessed. Inread-write mode, full access is possible but only one process at atime should be accessing the databases. Read-only mode disallowsmodifications to the files. The noDb mode allows NSS to be used without database filespurely as a cryptographic provider. It is not possible to createpersistent keys using the PKCS11 KeyStore. |
| nssModule | one of keystore, crypto,fips, and trustanchors | NSS makes its functionality available using several differentlibraries and slots. This directive determines which of thesemodules 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:
2.4 Troubleshooting PKCS#11
Sometimes, there could be issues with PKCS#11 which requiresdebugging. To show debug info about Library, Slots, Token andMechanism, add showInfo=true in$JAVA-HOME/jre/lib/security/sunpkcs11-solaris.cfgfile.
For additional debugging info, users can start or restart theJava processes with one of the following options:
- For general SunPKCS11 provider debugging info:
- For PKCS11 keystore specific debugging info:
2.5 Disabling PKCS#11 Providers and/or Individual PKCS#11Mechanisms
As part of the troubleshooting process, it could be helpful totemporarily disable a PKCS#11 provider or the specific mechanismsof a given provider. Please note that this is only a temporarymeasure. By disabling the PKCS#11 provider, the provider is nolonger available which can cause applications to break or have aperformance impact. Once the issue has been identified, only thatspecific mechanism should remaindisabled.
2.5.1 Disabling PKCS#11 Providers
A PKCS#11 provider can be disabled using one of the followingmethods:
- Disable PKCS#11 for a single Java process: Start or restart theJava process with the following Java command line flag:
Note:This step is only applicable to the SunPKCS11provider when backed by the default Solaris PKCS11 providerfiles(sun.security.pkcs11.SunPKCS11,/lib/security/sunpkcs11-solaris.cfg, /usr/lib/libpkcs11.so). - Disable PKCS#11 for all Java processes run with a particularJava installation: This can be done dynamically by using thejava.security.Security.removeProvider() API (not shown in thisdocument) or statically by editing the
$JAVA_HOME/jre/lib/security/java.securityfile andcommenting out the PKCS#11 security provider (do not forget tore-number the order of providers) as shown below.Start or restart the Java processes being run on thisinstallation of Java.
2.5.2 Disabling Specific Mechanisms
When an issue occurs in one of the mechanisms of PKCS11, it canbe resolved by disabling only that particular mechanism, ratherthan the entire PKCS11 provider (do not forget to re-enable thePKCS11 provider if it was disabled earlier). For example, todisable the SecureRandom mechanism only, you can addSecureRandom to the list of disabled mechanisms in the$JAVA_HOME/jre/lib/security/sunpkcs11-solaris.cfgfile. Here is an excerpt from such a file:
Note: The portion of thesunpkcs11-solaris.cfg file shown above is an exampleto show where to add the mechanisms that are to be disabled but isnot the complete file.
3.0 Application Developers
Java applications can use the existing JCA and JCE APIs toaccess PKCS#11 tokens via the Sun PKCS#11 provider. This issufficient for many applications but it might be difficult for anapplication to deal with certain PKCS#11 features, such asunextractable keys and dynamically changing Smartcards.Consequently, a number of enhancements were made to the APIs tobetter support applications using certain PKCS#11 features. Theseenhancements 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 ofoperations that require login are those that deal with keys on thetoken. In a Java application, such operations often involve firstloading the keystore. When accessing the PKCS#11 token as akeystore via the java.security.KeyStore class, you cansupply the PIN in the password input parameter to the load method, similar to how applications initialize a keystoreprior to J2SE 5.0. The PIN will then be used by the Sun PKCS#11provider for logging into the token. Here is an example.
This is fine for an application that treats PKCS#11 tokens asstatic keystores. For an application that wants to accommodatePKCS#11 tokens more dynamically, such as Smartcards being insertedand removed, you can use the new KeyStore.Builder class.Here is an example of how to initialize the builder for a PKCS#11keystore with a callback handler.
For the Sun PKCS#11 provider, the callback handler must be ableto satisfy a PasswordCallback, which is used to prompt theuser for the PIN. Whenever the application needs access to thekeystore, it uses the builder as follows.
The builder will prompt for a password as needed using thepreviously configured callback handler. The builder will prompt fora password only for the initial access. If the user of theapplication continues using the same Smartcard, the user will notbe prompted again. If the user removes and inserts a differentSmartCard, the builder will prompt for a password for the newcard.
Depending on the PKCS#11 token, there may be non-key-relatedoperations that also require token login. Applications that usesuch operations can use the newly introduced java.security.AuthProviderclass. The AuthProvider class extends fromjava.security.Provider and defines methods to performlogin and logout operations on a provider, as well as to set acallback handler for the provider to use.
For the Sun PKCS#11 provider, the callback handler must be ableto satisfy a PasswordCallback, which is used to prompt theuser for the PIN.
Here is an example of how an application might use anAuthProvider to log into the token.
3.2 Token Keys
Java Key objects may or may not contain actual keymaterial.
- A software Key object does contain the actual key material andallows access to that material.
- An unextractable key on a secure token (such as a Smartcard) isrepresented by a Java Key object that does not contain the actualkey material. The Key object only contains a reference to theactual key.
Applications and providers must use the correct interfaces torepresent these different types of Key objects. Software Keyobjects (or any Key object that has access to the actual keymaterial) should implement the interfaces in the java.security.interfacesand javax.crypto.interfacespackages (such as DSAPrivateKey). Key objects representingunextractable token keys should only implement the relevant genericinterfaces in the java.securityand javax.cryptopackages (PrivateKey, PublicKey, orSecretKey). Identification of the algorithm of a keyshould be performed using the Key.getAlgorithm()method.
Applications should note that a Key object for an unextractabletoken key can only be used by the provider associated with thattoken.
3.3 Delayed Provider Selection
Prior to J2SE 5.0, the Java cryptography getInstance()methods, such as Cipher.getInstance('AES'), returned theimplementation from the first provider that implemented therequested algorithm. This is problematic if an application attemptsto use a Key object for an unextractable token key with aprovider that only accepts software key objects. In such a case,the provider would throw an InvalidKeyException. This isan issue for the Cipher, KeyAgreement,Mac, and Signature classes.
J2SE 5.0, addresses this issue bydelaying the selection of the provider until the relevantinitialization method is called. The initialization method acceptsa Key object and can determine at that point whichprovider can accept the specified Key object. This ensuresthat the selected provider can use the specified Keyobject. The following represents the affected initializationmethods.
- Cipher.init(..., Keykey, ...)
- KeyAgreement.init(Keykey, ...)
- Mac.init(Key key,...)
- Signature.initSign(PrivateKeyprivateKey)
Although this delayed provider selection is hidden from theapplication, it does affect the behavior of thegetProvider() method for Cipher,KeyAgreement, Mac, and Signature. IfgetProvider() is called before theinitialization operation has occurred (and therefore beforeprovider selection has occurred), then the first provider thatsupports the requested algorithm is returned. This may not be thesame provider as the one selected after the initializationmethod is called. If getProvider() is calledafter the initialization operation has occurred, then theactual selected provider is returned. It is recommended thatapplications only call getProvider() after they havecalled the relevant initialization method.
In addition to getProvider(), the followingadditional 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 toauthenticate using its identity in a specified keystore. Afterauthentication, the application would have acquire its principaland credentials information (certificate and private key) from thekeystore. By using this login module and configuring it to use aPKCS#11 token as a keystore, the application can acquire thisinformation from a PKCS#11 token.Use the following options to configure theKeyStoreLoginModule to use a PKCS#11 token as thekeystore.
- keyStoreURL='NONE'
- keyStoreType='PKCS11'
- keyStorePasswordURL=some_pin_url
If more than one Sun PKCS#11 provider has been configureddynamically or in the java.security security propertiesfile, you can use the keyStoreProvider option to target aspecific provider instance. The argument to this option is the nameof the provider. For the Sun PKCS#11 provider, the provider name isof the form SunPKCS11-TokenName, whereTokenName is the name suffix that the providerinstance has been configured with, as detailed in the configuration attributes table. For example, thefollowing configuration file names the PKCS#11 provider instancewith name suffix SmartCard.
Some PKCS#11 tokens support login via a protectedauthentication path. For example, a Smartcard may have adedicated PIN-pad to enter the pin. Biometric devices will alsohave their own means to obtain authentication information. If thePKCS#11 token has a protected authentication path, then use theprotected=true option and omit thekeyStorePasswordURL option. Here is an example of aconfiguration 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 JSSEapplication can use the APIs describedpreviously to instantiate a KeyStore that is backed bya PKCS#11 token and pass it to its key manager and trust manager.The JSSE application will then have access to the keys on thetoken.JSSE also supports configuring the use of keystores and truststores via system properties, as described in the JSSE Reference Guide. Touse a PKCS#11 token as a keystore or trust store, set thejavax.net.ssl.keyStoreType andjavax.net.ssl.trustStoreType system properties,respectively, to 'PKCS11', and set thejavax.net.ssl.keyStore andjavax.net.ssl.trustStore system properties, respectively,to NONE. To specify the use of a specific providerinstance, use the javax.net.ssl.keyStoreProvider andjavax.net.ssl.trustStoreProvider system properties (e.g.,'SunPKCS11-SmartCard').
4.0 Tools
In J2SE 5.0, the security tools were updatedto support operations using the new Sun PKCS#11 provider. Thechanges are discussed below.
4.1 KeyTool and JarSigner
If the Sun PKCS#11 provider has been configured in thejava.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#11token by specifying the following options.
- -keystore NONE
- -storetype PKCS11
If more than one Sun PKCS#11 provider has been configured in thejava.security security properties file, you can use the-providerName option to target a specific providerinstance. The argument to this option is the name of theprovider.
- -providerName providerName
If the Sun PKCS#11 provider has not been configured in thejava.security security properties file, you can use thefollowing options to instruct keytool and jarsigner to install theprovider 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 thefollowing syntax.
This syntax was inadequate for accessing a PKCS#11 keystore becausesuch access usually required a PIN, and there might be multiplePKCS#11 provider instances. To accommodate these requirements, thekeystore entry syntax has been updated in J2SE 5.0, to thefollowing.Where keystore_provider is the keystore provider name (forexample, 'SunPKCS11-SmartCard'), andsome_password_url is a URL pointing to the location of thetoken PIN. Both keystore_provider and thekeystorePasswordURL line are optional. Ifkeystore_provider has not been specified, then the firstconfigured provider that supports the specified keystore type isused. If the keystorePasswordURL line has not beenspecified, then no password is used.The following is an example keystore policy entry for a PKCS#11token.
5.0 Provider Developers
J2SE 5.0 introduces new facilities in the java.security.Providerclass for provider implementations to more easily support PKCS#11tokens and cryptographic services in general. These new facilitiesare discussed below.
See Appendix C for an example ofa simple provider designed to demonstrate the new facilities.
5.1 Provider Services
As described in the above provider documentation, prior to J2SE5.0, providers were required to create java.util.Propertyentries describing the services they supported. For each serviceimplemented by the provider, there must be a property whose name isthe type of service (Cipher, Signature, etc),followed by a period and the name of the algorithm to which theservice applies. The property value must specify the fullyqualified name of the class implementing the service. Here is anexample of a provider setting KeyAgreement.DiffieHellmanproperty to have the valuecom.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 algorithmaliases). Providers can instantiate Provider.Serviceobjects and register them by calling theProvider.putService() method. This is equivalent tocreating a Property entry and calling theProvider.put() method (as was done prior to J2SE 5.0).Note that legacy Property entries registered viaProvider.put are still supported.
Here is an example of a provider creating a Serviceobject with the KeyAgreement type, for theDiffieHellman algorithm, implemented by the classcom.sun.crypto.provider.DHKeyAgreement.
Using Provider.Service objects instead of legacyProperty entries has a couple of major benefits. Onebenefit is that it allows the provider to have greater flexibilitywhen instantiating engine classes.Another benefit is that it allows the provider to test parameter validity. These features arediscussed in detail next.
5.1.1 Instantiating Engine Classes
Prior to J2SE 5.0, the Java Cryptography framework looked up theprovider property for a particular service and directlyinstantiated the engine class registered for that property. J2SE5.0, has the same behavior by default, but allows the provider tooverride this behavior and instantiate the engine class for therequested service itself.
To override the default behavior, the provider overrides theProvider.Service.newInstance() method to add its customerbehavior. For example, the provider might call a customconstructor, or might perform initialization using information notaccessible outside the provider (or that are only known by theprovider).
5.1.2 Parameter Support
The Java Cryptography framework may attempt a fast check todetermine whether a provider's service implementation can use anapplication-specified parameter. To perform this fast check, theframework calls Provider.Service.supportsParameter().
In J2SE 5.0, the framework relies on this fast test duringdelayed provider selection. When anapplication invokes an initialization methodand passes it a Key object, the framework asks anunderlying provider whether it supports the object by calling itsService.supportsParameter() method. IfsupportsParameter() returns false, theframework can immediately remove that provider from consideration.If supportsParameter() returns true, theframework passes the Key object to that provider'sinitialization engine class implementation. A provider thatrequires software Key objects should override this methodto return false when it is passed non-software keys.Likewise, a provider for a PKCS#11 token that containsunextractable keys should only return true forKey objects that it created, and which thereforecorrespond to the Keys on its respective token.
Note that the default implementation ofsupportsParameter() returns true. Thisallows existing providers to work without modification. However,because of this lenient default implementation, the framework mustbe prepared to catch exceptions thrown by providers that reject theKey object inside their initialization engine classimplementations. The framework treats these cases the same as whensupportsParameter() returns false.
Appendix A: Sun PKCS#11 Provider's Supported Algorithms
The following table lists the Java algorithms supported by the SunPKCS#11 provider and corresponding PKCS#11 mechanisms needed tosupport them. When multiple mechanisms are listed, they are givenin the order of preference and any one of them is sufficient. Notethat SunPKCS11 can be instructed to ignore mechanisms by using thedisabledMechanisms and Package Slot Missing From Signature For Generic ‘coerce’
enabledMechanismsconfiguration directives.For Elliptic Curve mechanisms, SunPKCS11 will only use keys thatuse the namedCurve choice as encoding for theparameters and only allow the uncompressed point format. The SunPKCS#11 provider assumes that a token supports all standard nameddomain 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.SHA224withRSA | CKM_SHA224_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.SHA224withECDSA | 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.HmacSHA224 | CKM_SHA224_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-224 | CKM_SHA224 |
| 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 SunPKCS#11 Provider's KeyStore implementation on the underlying nativePKCS#11 library. Note that changes may be made in futurereleases to maximize interoperability with as many existing PKCS#11libraries as possible.
Read-Only Access
To map existing objects stored on a PKCS#11 token to KeyStoreentries, the Sun PKCS#11 Provider's KeyStore implementationperforms the following operations.
- A search for all private key objects on the token is performedby calling C_FindObjects[Init|Final]. The search template includesthe following attributes:
- CKA_TOKEN = true
- CKA_CLASS = CKO_PRIVATE_KEY
- A search for all certificate objects on the token is performedby calling C_FindObjects[Init|Final]. The search template includesthe following attributes:
- CKA_TOKEN = true
- CKA_CLASS = CKO_CERTIFICATE
- Each private key object is matched with its correspondingcertificate by retrieving their respective CKA_ID attributes. Amatching pair must share the same unique CKA_ID.
For each matching pair, the certificate chain is built byfollowing the issuer->subject path. From the end entitycertificate, a call to C_FindObjects[Init|Final] is made with asearch 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 theissuer is found, or until a self-signed certificate is found. Ifmore than one certificate is found the first one is used.
Once a private key and certificate have been matched (and itscertificate chain built), the information is stored in a privatekey entry with the CKA_LABEL value from end entity certificate asthe KeyStore alias.
If the end entity certificate has no CKA_LABEL, then the aliasis derived from the CKA_ID. If the CKA_ID can be determined toconsist exclusively of printable characters, then a String alias iscreated 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 thealias is derived from the CKA_LABEL plus the end entity certificateissuer and serial number ('MyCert/CN=foobar/1234', forexample).
- Each certificate not part of a private key entry (as the endentity certificate) is checked whether it is trusted. If theCKA_TRUSTED attribute is true, then a KeyStore trusted certificateentry is created with the CKA_LABEL value as the KeyStore alias. Ifthe certificate has no CKA_LABEL, or if multiple certificates sharethe same CKA_LABEL, then the alias is derived as described above.
If the CKA_TRUSTED attribute is not supported then no trustedcertificate entries are created.
- Any private key or certificate object not part of a private keyentry or trusted certificate entry is ignored.
- A search for all secret key objects on the token is performedby calling C_FindObjects[Init|Final]. The search template includesthe following attributes:
- CKA_TOKEN = true
- CKA_CLASS = CKO_SECRET_KEY
A KeyStore secret key entry is created for each secret keyobject, with the CKA_LABEL value as the KeyStore alias. Each secretkey object must have a unique CKA_LABEL.
Write Access
To create new KeyStore entries on a PKCS#11 token to KeyStoreentries, the Sun PKCS#11 Provider's KeyStore implementationperforms the following operations.
- When creating a KeyStore entry (during KeyStore.setEntry, forexample), C_CreateObject is called with CKA_TOKEN=true to createtoken objects for the respective entry contents.
Private key objects are stored with CKA_PRIVATE=true. TheKeyStore alias (UTF8-encoded) is set as the CKA_ID for both theprivate key and the corresponding end entity certificate. TheKeyStore alias is also set as the CKA_LABEL for the end entitycertificate 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 certificateis already in the token, a duplicate is not stored.
Secret key objects are stored with CKA_PRIVATE=true. TheKeyStore alias is set as the CKA_LABEL.
- If an attempt is made to convert a session object to a tokenobject (for example, if KeyStore.setEntry is called and the privatekey object in the specified entry is a session object), thenC_CopyObject is called with CKA_TOKEN=true.
- If multiple certificates in the token are found to share thesame CKA_LABEL, then the write capabilities to the token aredisabled.
- Since the PKCS#11 specification does not allow regularapplications to set CKA_TRUSTED=true (only token initializationapplications may do so), trusted certificate entries can not becreated.
Miscellaneous
In addition to the searches listed above, the following searchesmay be used by the Sun PKCS#11 provider's KeyStore implementationto perform internal functions. Specifically,C_FindObjects[Init|Final] may be called with any of the followingattribute templates: