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