PKCS11RandomSpi (IAIK PKCS#11 Provider API Documentation)

java.lang.Object
- java.security.SecureRandomSpi
- - iaik.pkcs.pkcs11.provider.random.PKCS11RandomSpi

All Implemented Interfaces:

PKCS11EngineClass, java.io.Serializable

Direct Known Subclasses:

PKCS11RandomNoSetSeedSpi, PKCS11SeededRandomSpi
```
public class PKCS11RandomSpi
extends java.security.SecureRandomSpi
implements PKCS11EngineClass
```
An implementation of the SecureRandomSpi that uses a PKCS#11 token to gereate random data and seeds. If this object is created using the default constructor, and this is always the case when instantiated through the JCA mechanism, this implementation always links to the first instance of IAIKPkcs11. The only way to link to a different instance is to instantiate the PKCS11Random class directly and to specify the provider. This implementation gets all random data directly from the token - seed bytes and random bytes. If there is no token present at creation time of this object, or if the present token does not support random number generation, this implementation uses a software delegate to process all requests. Per default, the SHA1PRNG algorithm is used for the software delegate.

Author:

Karl Scheibelhofer

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`pkcs11OperationInitialized_` Indicates, if the PKCS#11 signature/verify is already initialized for the next operation round.
`protected iaik.pkcs.pkcs11.Session`	`session_` The session this object works with.
`protected static java.lang.String`	`SOFTWARE_SECURE_RANDOM_ALGORITHM` The name of the algorithm to use for a software delegate.
`protected java.security.SecureRandom`	`softwareDelegate_` This is the software delegate object to use, if the token does not have a random generator.
`protected TokenManager`	`tokenManager_` Token manager used to access the token.
`protected boolean`	`useSoftwareDelegation_` If true, this object must use the software secure random, because the token does not have a random number generator or there was no token present, when this object was created.

Constructor Summary

Constructors
Constructor and Description
`PKCS11RandomSpi()` This default constructor always links this random class to the first provider instance, because there are no means in the JCE to find out our provider instance.
`PKCS11RandomSpi(TokenManager tokenManager)` This constructor links this random class to the given token manager.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected byte[]`	`engineGenerateSeed(int numBytes)` Returns the given number of seed bytes.
`protected void`	`engineNextBytes(byte[] arrayToFill)` Generates a user-specified number of random bytes.
`protected void`	`engineSetSeed(byte[] seedBytes)` Reseeds this random object.
`protected void`	`finalize()` Tries to close the used session.
`protected void`	`finalizePkcs11Operation()` The internal session finalization method, if the current operation has been finished.
`protected java.lang.String`	`getSoftwareDelegateAlgorithm()` Return the name of the software algorithm to use, if this object must use a softwre delegation object.
`protected void`	`initialize()` Initialize this secure random object.
`protected void`	`initializePkcs11Operation()` The internal session initialization method, if all necessary member variables are set.
`protected void`	`initializeSession()` Sets up an appropriate session.
`protected void`	`initializeSoftwareDelegate()` Initialize the software delegate secure random and store a reference in `softwareDelegate_`.
`boolean`	`isSupportedBy(TokenManager tokenManager)` Check, if the current token of the given token manager supports the required features for this engine class.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SOFTWARE_SECURE_RANDOM_ALGORITHM
```
protected static final java.lang.String SOFTWARE_SECURE_RANDOM_ALGORITHM
```
    The name of the algorithm to use for a software delegate.
    
    See Also:
    
    Constant Field Values
  - tokenManager_
```
protected TokenManager tokenManager_
```
    Token manager used to access the token.
  - session_
```
protected iaik.pkcs.pkcs11.Session session_
```
    The session this object works with.
  - pkcs11OperationInitialized_
```
protected boolean pkcs11OperationInitialized_
```
    Indicates, if the PKCS#11 signature/verify is already initialized for the next operation round.
  - useSoftwareDelegation_
```
protected boolean useSoftwareDelegation_
```
    If true, this object must use the software secure random, because the token does not have a random number generator or there was no token present, when this object was created. This variable is set during object creation.
  - softwareDelegate_
```
protected java.security.SecureRandom softwareDelegate_
```
    This is the software delegate object to use, if the token does not have a random generator. This is only set, if useSoftwareDelegation_ is set.
- Constructor Detail
  - PKCS11RandomSpi
```
public PKCS11RandomSpi()
                throws IAIKPkcs11Exception
```
    This default constructor always links this random class to the first provider instance, because there are no means in the JCE to find out our provider instance.
    
    Throws:
    
    IAIKPkcs11Exception - If there is no IAIKPkcs11 instance available.
  - PKCS11RandomSpi
```
public PKCS11RandomSpi(TokenManager tokenManager)
                throws IAIKPkcs11Exception
```
    This constructor links this random class to the given token manager. It uses this token manager to access the token.
    
    Parameters:
    
    tokenManager - The manager of the token we use for random generation.
    
    Throws:
    
    IAIKPkcs11Exception - If there is no IAIKPkcs11 instance available.
- Method Detail
  - isSupportedBy
```
public boolean isSupportedBy(TokenManager tokenManager)
```
    Check, if the current token of the given token manager supports the required features for this engine class.
    
    Specified by:
    
    isSupportedBy in interface PKCS11EngineClass
    
    Parameters:
    
    tokenManager - The token manager. Used to get information about the current token.
    
    Returns:
    
    True, if this engine class can be used with the currently present token of the given token manager.
    
    Preconditions:
    
    (tokenManager <> null)
  - initialize
```
protected void initialize()
```
    Initialize this secure random object. This method looks, if there is a token present and if there is one present it gets its token info to see if it has a random number generator. If the token does not have a random number generator or if there is currently no token present, it initializes a software delegate secure random that will be used to process requests.
  - initializeSoftwareDelegate
```
protected void initializeSoftwareDelegate()
                                   throws java.security.GeneralSecurityException
```
    Initialize the software delegate secure random and store a reference in softwareDelegate_.
    
    Throws:
    
    java.security.GeneralSecurityException - If initializing the software secure random fails.
  - getSoftwareDelegateAlgorithm
```
protected java.lang.String getSoftwareDelegateAlgorithm()
```
    Return the name of the software algorithm to use, if this object must use a softwre delegation object.
    
    Returns:
    
    The name of the software secure random; e.g. SHA1PRNG.
    
    Postconditions:
    
    (result <> null)
  - engineNextBytes
```
protected void engineNextBytes(byte[] arrayToFill)
                        throws IAIKPkcs11Exception
```
    Generates a user-specified number of random bytes.
    
    Specified by:
    
    engineNextBytes in class java.security.SecureRandomSpi
    
    Parameters:
    
    arrayToFill - the array to be filled in with random bytes.
    
    Throws:
    
    IAIKPkcs11Exception - If generating random bytes fails.
    
    Preconditions:
    
    (arrayToFill <> null)
  - engineSetSeed
```
protected void engineSetSeed(byte[] seedBytes)
                      throws IAIKPkcs11Exception
```
    Reseeds this random object. The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness. Sets the seed in the token if possible or in the software delegate otherwise.
    
    Specified by:
    
    engineSetSeed in class java.security.SecureRandomSpi
    
    Parameters:
    
    seedBytes - The seed bytes.
    
    Throws:
    
    IAIKPkcs11Exception - If seeding the random fails.
    
    Preconditions:
    
    (seedBytes <> null)
  - engineGenerateSeed
```
protected byte[] engineGenerateSeed(int numBytes)
```
    Returns the given number of seed bytes. This call may be used to seed other random number generators. Gets the seed from the token if possible or from the software delegate otherwise. This implementation simply calls generateRandom of the token; i.e. it is the same as a call to engineNextBytes(byte[]).
    
    Specified by:
    
    engineGenerateSeed in class java.security.SecureRandomSpi
    
    Parameters:
    
    numBytes - the number of seed bytes to generate.
    
    Returns:
    
    the seed bytes.
    
    Postconditions:
    
    (result <> null) and (result.length == numBytes)
    
    Preconditions:
    
    (numBytes >= 0)
  - initializeSession
```
protected void initializeSession()
```
    Sets up an appropriate session. The key must be set before.
  - initializePkcs11Operation
```
protected void initializePkcs11Operation()
```
    The internal session initialization method, if all necessary member variables are set.
  - finalizePkcs11Operation
```
protected void finalizePkcs11Operation()
```
    The internal session finalization method, if the current operation has been finished.
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Tries to close the used session.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable - If disposing the session fails.

IAIK JavaSecurity Website https://jce.iaik.tugraz.at/

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2023 IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved. Version 1.9.4

Class PKCS11RandomSpi

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SOFTWARE_SECURE_RANDOM_ALGORITHM

tokenManager_

session_

pkcs11OperationInitialized_

useSoftwareDelegation_

softwareDelegate_

Constructor Detail

PKCS11RandomSpi

PKCS11RandomSpi

Method Detail

isSupportedBy

initialize

initializeSoftwareDelegate

getSoftwareDelegateAlgorithm

engineNextBytes

engineSetSeed

engineGenerateSeed

initializeSession

initializePkcs11Operation

finalizePkcs11Operation

finalize