index.rst (20564B)
1 .. _mozilla_projects_nss_jss_jss_provider_notes: 2 3 JSS Provider Notes 4 ================== 5 6 .. container:: 7 8 .. warning:: 9 10 This page has been moved to http://www.dogtagpki.org/wiki/JSS_Provider. 11 12 .. _the_mozilla-jss_jca_provider: 13 14 `The Mozilla-JSS JCA Provider <#the_mozilla-jss_jca_provider>`__ 15 ---------------------------------------------------------------- 16 17 .. container:: 18 19 Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ 20 21 `Overview <#overview>`__ 22 ~~~~~~~~~~~~~~~~~~~~~~~~ 23 24 .. container:: 25 26 This document describes the JCA Provider shipped with JSS. The provider's name is "Mozilla-JSS". 27 It implements cryptographic operations in native code using the `NSS <../nss>`__ libraries. 28 29 `Contents <#contents>`__ 30 ~~~~~~~~~~~~~~~~~~~~~~~~ 31 32 .. container:: 33 34 - `Signed JAR file <#signed-jar>`__ 35 - `Installing the Provider <#installing-provider>`__ 36 - `Specifying the CryptoToken <#specifying-token>`__ 37 - `Supported Classes <#supported-classes>`__ 38 - `What's Not Supported <#not-supported>`__ 39 40 -------------- 41 42 .. _signed_jar_file: 43 44 `Signed JAR file <#signed_jar_file>`__ 45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47 .. container:: 48 49 - JSS 3.2 implements several JCE (Java Cryptography Extension) algorithms. These algorithms have 50 at various times been export-controlled by the US government. Sun therefore requires that JAR 51 files implementing JCE algorithms be digitally signed by an approved organization. Netscape 52 has this approval and signs the official builds of ``jss32.jar``. At runtime, the JRE 53 automatically verifies this signature whenever a JSS class is loaded that implements a JCE 54 algorithm. The verification is transparent to the application (unless it fails and throws an 55 exception). If you are curious, you can verify the signature on the JAR file using the 56 ``jarsigner`` tool, which is distributed with the JDK. 57 58 If you build JSS yourself from source instead of using binaries downloaded from mozilla.org, 59 your JAR file will not have a valid signature. This means you will not be able to use the JSS 60 provider for JCE algorithms. You have two choices. 61 62 #. Use the binary release of JSS from mozilla.org. 63 #. Apply for your own JCE code-signing certificate following the procedure at `How to 64 Implement a Provider for the Java\ TM Cryptography 65 Extension <http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/HowToImplAProvider.html#Step61>`__. 66 Then you can sign your own JSS JAR file. 67 68 .. _installing_the_provider: 69 70 `Installing the Provider <#installing_the_provider>`__ 71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 72 73 .. container:: 74 75 - In order to use any part of JSS, including the JCA provider, you must first call 76 ``CryptoManager.initialize()``. By default, the JCA provider will be installed in the list of 77 providers maintained by the ``java.security.Security`` class. If you do not wish the provider 78 to be installed, create a 79 :ref:`mozilla_projects_nss_jss_cryptomanager_cryptomanager_initializationvalues` object, set 80 its ``installJSSProvider`` field to ``false``, and pass the ``InitializationValues`` object to 81 ``CryptoManager.initialize()``. 82 83 .. _specifying_the_cryptotoken: 84 85 `Specifying the CryptoToken <#specifying_the_cryptotoken>`__ 86 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 87 88 .. container:: 89 90 - All cryptographic operations in JSS and NSS occur on a particular PKCS #11 token, implemented 91 in software or hardware. There is no clean way to specify this token through the JCA API. By 92 default, the JSS provider carries out all operations except MessageDigest on the Internal Key 93 Storage Token, a software token included in JSS/NSS. MessageDigest operations take place by 94 default on the Internal Crypto Token, another internal software token in JSS/NSS. There is no 95 good design reason for this difference, but it is necessitated by a quirk in the NSS 96 implementation. 97 98 In order to use a different token, use ``CryptoManager.setThreadToken()``. This sets the token 99 to be used by the JSS JCA provider in the current thread. When you call ``getInstance()`` on a 100 JCA class, the JSS provider checks the current per-thread default token (by calling 101 ``CryptoManager.getThreadToken()``) and instructs the new object to use that token for 102 cryptographic operations. The per-thread default token setting is only consulted inside 103 ``getInstance()``. Once a JCA object has been created it will continue to use the same token, 104 even if the application later changes the per-thread default token. 105 106 Whenever a new thread is created, its token is initialized to the default, the Internal Key 107 Storage Token. Thus, the thread token is not inherited from the parent thread. 108 109 The following example shows how you can specify which token is used for various JCA 110 operations: 111 112 .. code:: 113 114 // Lookup PKCS #11 tokens 115 CryptoManager manager = CryptoManager.getInstance(); 116 CryptoToken tokenA = manager.getTokenByName("TokenA"); 117 CryptoToken tokenB = manager.getTokenByName("TokenB"); 118 119 // Create an RSA KeyPairGenerator using TokenA 120 manager.setThreadToken(tokenA); 121 KeyPairGenerator rsaKpg = KeyPairGenerator.getInstance("RSA", "Mozilla-JSS"); 122 123 // Create a DSA KeyPairGenerator using TokenB 124 manager.setThreadToken(tokenB); 125 KeyPairGenerator dsaKpg = KeyPairGenerator.getInstance("DSA", "Mozilla-JSS"); 126 127 // Generate an RSA KeyPair. This will happen on TokenA because TokenA 128 // was the per-thread default token when rsaKpg was created. 129 rsaKpg.initialize(1024); 130 KeyPair rsaPair = rsaKpg.generateKeyPair(); 131 132 // Generate a DSA KeyPair. This will happen on TokenB because TokenB 133 // was the per-thread default token when dsaKpg was created. 134 dsaKpg.initialize(1024); 135 KeyPair dsaPair = dsaKpg.generateKeyPair(); 136 137 .. _supported_classes: 138 139 `Supported Classes <#supported_classes>`__ 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 141 142 .. container:: 143 144 - `Cipher <#cipher>`__ 145 146 - `DSAPrivateKey <#dsaprivatekey>`__ 147 148 - DSAPublicKey 149 150 - `KeyFactory <#keyfactory>`__ 151 152 - `KeyGenerator <#keygenerator>`__ 153 154 - `KeyPairGenerator <#keypairgenerator>`__ 155 156 - `Mac <#mac>`__ 157 158 - `MessageDigest <#messagedigest>`__ 159 160 - `RSAPrivateKey <#rsaprivatekey>`__ 161 162 - RSAPublicKey 163 164 - `SecretKeyFactory <#secretkeyfactory>`__ 165 166 - `SecretKey <#secretkey>`__ 167 168 - `SecureRandom <#securerandom>`__ 169 170 - `Signature <#signature>`__ 171 172 .. rubric:: What's Not Supported 173 :name: What's_Not_Supported 174 175 - The following classes don't work very well: 176 177 - **KeyStore:** There are many serious problems mapping the JCA keystore interface onto 178 NSS's model of PKCS #11 modules. The current implementation is almost useless. Since 179 these problems lie deep in the NSS design and implementation, there is no clear 180 timeframe for fixing them. Meanwhile, the ``org.mozilla.jss.crypto.CryptoStore`` class 181 can be used for some of this functionality. 182 183 .. rubric:: Cipher 184 :name: Cipher_2 185 186 .. rubric:: Supported Algorithms 187 :name: supported_algorithms 188 189 .. rubric:: Notes 190 :name: notes 191 192 - 193 194 - AES 195 - DES 196 - DESede (*DES3* ) 197 - RC2 198 - RC4 199 - RSA 200 201 - The following modes and padding schemes are supported: 202 203 204 +------------------------------+------------------------------+------------------------------+ 205 | Algorithm | Mode | Padding | 206 +------------------------------+------------------------------+------------------------------+ 207 | DES | ECB | NoPadding | 208 +------------------------------+------------------------------+------------------------------+ 209 | | CBC | NoPadding | 210 +------------------------------+------------------------------+------------------------------+ 211 | | | PKCS5 Padding | 212 +------------------------------+------------------------------+------------------------------+ 213 | DESede | ECB | NoPadding | 214 | *DES3* | | | 215 +------------------------------+------------------------------+------------------------------+ 216 | | CBC | NoPadding | 217 +------------------------------+------------------------------+------------------------------+ 218 | | | PKCS5 Padding | 219 +------------------------------+------------------------------+------------------------------+ 220 | AES | ECB | NoPadding | 221 +------------------------------+------------------------------+------------------------------+ 222 | | CBC | NoPadding | 223 +------------------------------+------------------------------+------------------------------+ 224 | | | PKCS5 Padding | 225 +------------------------------+------------------------------+------------------------------+ 226 | RC4 | *None* | *None* | 227 +------------------------------+------------------------------+------------------------------+ 228 | RC2 | CBC | NoPadding | 229 +------------------------------+------------------------------+------------------------------+ 230 | | | PKCS5Padding | 231 +------------------------------+------------------------------+------------------------------+ 232 233 - The SecureRandom argument passed to ``initSign()`` and ``initVerify()`` is ignored, because 234 NSS does not support specifying an external source of randomness. 235 236 .. rubric:: DSAPrivateKey 237 :name: DSAPrivateKey_2 238 239 - ``getX()`` is not supported because NSS does not support extracting data from private keys. 240 241 .. rubric:: KeyFactory 242 :name: KeyFactory_2 243 244 .. rubric:: Supported Algorithms 245 :name: supported_algorithms_2 246 247 .. rubric:: Notes 248 :name: notes_2 249 250 - 251 252 - DSA 253 - RSA 254 255 - The following transformations are supported for ``generatePublic()`` and 256 ``generatePrivate()``: 257 258 259 +----------------------------------------------+----------------------------------------------+ 260 | From | To | 261 +----------------------------------------------+----------------------------------------------+ 262 | ``RSAPublicKeySpec`` | ``RSAPublicKey`` | 263 +----------------------------------------------+----------------------------------------------+ 264 | ``DSAPublicKeySpec`` | ``DSAPublicKey`` | 265 +----------------------------------------------+----------------------------------------------+ 266 | ``X509EncodedKeySpec`` | ``RSAPublicKey`` | 267 | | ``DSAPublicKey`` | 268 +----------------------------------------------+----------------------------------------------+ 269 | ``RSAPrivateCrtKeySpec`` | ``RSAPrivateKey`` | 270 +----------------------------------------------+----------------------------------------------+ 271 | ``DSAPrivateKeySpec`` | ``DSAPrivateKey`` | 272 +----------------------------------------------+----------------------------------------------+ 273 | ``PKCS8EncodedKeySpec`` | ``RSAPrivateKey`` | 274 | | ``DSAPrivateKey`` | 275 +----------------------------------------------+----------------------------------------------+ 276 277 - ``getKeySpec()`` is not supported. This method exports key material in plaintext and is 278 therefore insecure. Note that a public key's data can be accessed directly from the key. 279 - ``translateKey()`` simply gets the encoded form of the given key and then tries to import 280 it by calling ``generatePublic()`` or ``generatePrivate()``. Only ``X509EncodedKeySpec`` is 281 supported for public keys, and only ``PKCS8EncodedKeySpec`` is supported for private keys. 282 283 .. rubric:: KeyGenerator 284 :name: KeyGenerator_2 285 286 .. rubric:: Supported Algorithms 287 :name: supported_algorithms_3 288 289 .. rubric:: Notes 290 :name: notes_3 291 292 - 293 294 - AES 295 - DES 296 - DESede (*DES3* ) 297 - RC4 298 299 - The SecureRandom argument passed to ``init()`` is ignored, because NSS does not support 300 specifying an external source of randomness. 301 - None of the key generation algorithms accepts an ``AlgorithmParameterSpec``. 302 303 .. rubric:: KeyPairGenerator 304 :name: KeyPairGenerator_2 305 306 .. rubric:: Supported Algorithms 307 :name: supported_algorithms_4 308 309 .. rubric:: Notes 310 :name: notes_4 311 312 - 313 314 - DSA 315 - RSA 316 317 - The SecureRandom argument passed to initialize() is ignored, because NSS does not support 318 specifying an external source of randomness. 319 320 .. rubric:: Mac 321 :name: Mac_2 322 323 .. rubric:: Supported Algorithms 324 :name: supported_algorithms_5 325 326 .. rubric:: Notes 327 :name: notes_5 328 329 - 330 331 - HmacSHA1 (*Hmac-SHA1* ) 332 333 - Any secret key type (AES, DES, etc.) can be used as the MAC key, but it must be a JSS key. 334 That is, it must be an ``instanceof org.mozilla.jss.crypto.SecretKeyFacade``. 335 - The params passed to ``init()`` are ignored. 336 337 .. rubric:: MessageDigest 338 :name: MessageDigest_2 339 340 .. rubric:: Supported Algorithms 341 :name: supported_algorithms_6 342 343 - 344 345 - MD5 346 - MD2 347 - SHA-1 (*SHA1, SHA* ) 348 349 .. rubric:: RSAPrivateKey 350 :name: RSAPrivateKey_2 351 352 .. rubric:: Notes 353 :name: notes_6 354 355 - 356 357 - ``getModulus()`` is not supported because NSS does not support extracting data from private 358 keys. 359 - ``getPrivateExponent()`` is not supported because NSS does not support extracting data from 360 private keys. 361 362 .. rubric:: SecretKeyFactory 363 :name: SecretKeyFactory_2 364 365 .. rubric:: Supported Algorithms 366 :name: supported_algorithms_7 367 368 .. rubric:: Notes 369 :name: notes_7 370 371 - 372 373 - AES 374 - DES 375 - DESede (*DES3* ) 376 - PBAHmacSHA1 377 - PBEWithMD5AndDES 378 - PBEWithSHA1AndDES 379 - PBEWithSHA1AndDESede (*PBEWithSHA1AndDES3* ) 380 - PBEWithSHA1And128RC4 381 - RC4 382 383 - ``generateSecret`` supports the following transformations: 384 385 386 +----------------------------------------------+----------------------------------------------+ 387 | KeySpec Class | Key Algorithm | 388 +----------------------------------------------+----------------------------------------------+ 389 | PBEKeySpec | *Using the appropriate PBE algorithm:* | 390 | org.mozilla.jss.crypto.PBEKeyGenParams | DES | 391 | | DESede | 392 | | RC4 | 393 +----------------------------------------------+----------------------------------------------+ 394 | DESedeKeySpec | DESede | 395 +----------------------------------------------+----------------------------------------------+ 396 | DESKeySpec | DES | 397 +----------------------------------------------+----------------------------------------------+ 398 | SecretKeySpec | AES | 399 | | DES | 400 | | DESede | 401 | | RC4 | 402 +----------------------------------------------+----------------------------------------------+ 403 404 - ``getKeySpec`` supports the following transformations: 405 406 407 +----------------------------------------------+----------------------------------------------+ 408 | Key Algorithm | KeySpec Class | 409 +----------------------------------------------+----------------------------------------------+ 410 | DESede | DESedeKeySpec | 411 +----------------------------------------------+----------------------------------------------+ 412 | DES | DESKeySpec | 413 +----------------------------------------------+----------------------------------------------+ 414 | DESede | SecretKeySpec | 415 | DES | | 416 | AES | | 417 | RC4 | | 418 +----------------------------------------------+----------------------------------------------+ 419 420 - For increased security, some SecretKeys may not be extractable from their PKCS #11 token. 421 In this case, the key should be wrapped (encrypted with another key), and then the 422 encrypted key might be extractable from the token. This policy varies across PKCS #11 423 tokens. 424 - ``translateKey`` tries two approaches to copying keys. First, it tries to copy the key 425 material directly using NSS calls to PKCS #11. If that fails, it calls ``getEncoded()`` on 426 the source key, and then tries to create a new key on the target token from the encoded 427 bits. Both of these operations will fail if the source key is not extractable. 428 - The class ``java.security.spec.PBEKeySpec`` in JDK versions earlier than 1.4 does not 429 contain the salt and iteration fields, which are necessary for PBE key generation. These 430 fields were added in JDK 1.4. If you are using a JDK (or JRE) version earlier than 1.4, you 431 cannot use class ``java.security.spec.PBEKeySpec``. Instead, you can use 432 ``org.mozilla.jss.crypto.PBEKeyGenParams``. If you are using JDK (or JRE) 1.4 or later, you 433 can use ``java.security.spec.PBEKeySpec`` or ``org.mozilla.jss.crypto.PBEKeyGenParams``. 434 435 .. rubric:: SecretKey 436 :name: SecretKey_2 437 438 .. rubric:: Supported Algorithms 439 :name: supported_algorithms_8 440 441 .. rubric:: Notes 442 :name: notes_8 443 444 - 445 446 - AES 447 - DES 448 - DESede (*DES3* ) 449 - HmacSHA1 450 - RC2 451 - RC4 452 453 - ``SecretKey`` is implemented by the class ``org.mozilla.jss.crypto.SecretKeyFacade``, which 454 acts as a wrapper around the JSS class ``SymmetricKey``. Any ``SecretKeys`` handled by JSS 455 will actually be ``SecretKeyFacades``. This should usually be transparent. 456 457 .. rubric:: SecureRandom 458 :name: SecureRandom_2 459 460 .. rubric:: Supported Algorithms 461 :name: supported_algorithms_9 462 463 .. rubric:: Notes 464 :name: notes_9 465 466 - 467 468 - pkcs11prng 469 470 - This invokes the NSS internal pseudorandom number generator. 471 472 .. rubric:: Signature 473 :name: Signature_2 474 475 .. rubric:: Supported Algorithms 476 :name: supported_algorithms_10 477 478 .. rubric:: Notes 479 :name: notes_10 480 481 - 482 483 - SHA1withDSA (*DSA, DSS, SHA/DSA, SHA-1/DSA, SHA1/DSA, DSAWithSHA1, SHAwithDSA* ) 484 - SHA-1/RSA (*SHA1/RSA, SHA1withRSA* ) 485 - MD5/RSA (*MD5withRSA* ) 486 - MD2/RSA 487 488 - The ``SecureRandom`` argument passed to ``initSign()`` and ``initVerify()`` is ignored, 489 because NSS does not support specifying an external source of randomness.