IAIK PKCS#11 Provider API Documentation
version 1.6

iaik.pkcs.pkcs11.provider.keys
Class IAIKPKCS11Key

java.lang.Object
  extended by iaik.pkcs.pkcs11.provider.keys.IAIKPKCS11Key
All Implemented Interfaces:
java.io.Serializable, java.security.Key
Direct Known Subclasses:
IAIKPKCS11PrivateKey, IAIKPKCS11PublicKey, IAIKPKCS11SecretKey

public abstract class IAIKPKCS11Key
extends java.lang.Object
implements java.security.Key

A Java key object that is associated with a PKCS#11 key object. This class uses the PKCS#11 wrapper from IAIK.

Author:
Karl Scheibelhofer
See Also:
Serialized Form
Invariants
(tokenManager_ <> null) and (keyObject_ <> null) and (keyTypeNames_ <> null) and (keyTypeCodes_ <> null)

Field Summary
static java.lang.String AES
          The key algortihm name for AES.
static java.lang.String BATON
          The key algortihm name for BATON.
static java.lang.String BLOWFISH
          The key algortihm name for AES.
static java.lang.String CAST
          The key algortihm name for CAST.
static java.lang.String CAST128
          The key algortihm name for CAST128 (=CAST5).
static java.lang.String CAST3
          The key algortihm name for CAST3.
static java.lang.String CAST5
          The key algortihm name for CAST5 (=CAST128).
static java.lang.String CDMF
          The key algortihm name for CDMF.
static java.lang.String DES
          The key algortihm name for DES.
static java.lang.String DES2
          The key algortihm name for DES2.
static java.lang.String DESede
          The key algortihm name for DESede (=DES3).
static java.lang.String DH
          The key algortihm name for DH.
static java.lang.String DSA
          The key algortihm name for DSA.
static java.lang.String ECDSA
          The key algortihm name for ECDSA.
static java.lang.String GENERIC_SECRET
          The key algortihm name for GENERIC_SECRET.
static java.lang.String IDEA
          The key algortihm name for IDEA.
static java.lang.String JUNIPER
          The key algortihm name for JUNIPER.
static java.lang.String KEA
          The key algortihm name for KEA.
static java.lang.String RC2
          The key algortihm name for RC2.
static java.lang.String RC4
          The key algortihm name for RC4.
static java.lang.String RC5
          The key algortihm name for RC5.
static java.lang.String RSA
          The key algortihm name for RSA.
static java.lang.String SKIPJACK
          The key algortihm name for SKIPJACK.
static java.lang.String TWOFISH
          The key algortihm name for AES.
static java.lang.String VENDOR_DEFINED
          The key algortihm name for VENDOR_DEFINED.
 
Fields inherited from interface java.security.Key
serialVersionUID
 
Method Summary
static IAIKPKCS11Key create(TokenManager tokenManager, iaik.pkcs.pkcs11.objects.Key keyObject)
          Create a new instance of a IAIKPKCS11Key which's token managed by the given token manager and is based on the given PKCS#11 key object.
 void destroy()
          A call to this method destroys the underlying pkcs#11 key object.
 void finalize()
          Tries to release the close-lock of this key's session if there is one.
 java.lang.String getAlgorithm()
          The name of the algorthim of this key object; e.g.
static java.lang.Long getAlgorithmCode(java.lang.String keyTypeName)
          Get the code of the algorthim with the given name.
static java.lang.String getAlgorithmName(int keyTypeCode)
          Get the name of the algorthim of the give key type code.
 java.lang.String getAlias()
          Get the alias name for this key.
 byte[] getEncoded()
          UNSUPPORTED.
 java.lang.String getFormat()
          UNSUPPORTED.
 byte[] getKeyID()
          Get the ID of this PKCS#11 key object; i.e. the exact value of the PKCS#11 CKA_ID attribute of the asociated key object.
 iaik.pkcs.pkcs11.objects.Key getKeyObject()
          Get the associated PKCS#11 key object.
 iaik.pkcs.pkcs11.Session getSession()
          The chached session in this key.
 TokenManager getTokenManager()
          Get the token manager this object works with.
 boolean isAutoDestroy()
          Returns true if this key object is marked for automatic deletion upon object finalization.
 boolean isDestroyed()
          Returns true, if the destroy() method has already been called successfully.
 void setAutoDestroy(boolean autoDestroy)
          Set if this key object should be deleted automatically upon object finalization.
 void setSession(iaik.pkcs.pkcs11.Session session)
          Cache the given session in this key.
 java.lang.String toString()
          Returns a string presentation for debug output.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

RSA

public static final java.lang.String RSA
The key algortihm name for RSA.

See Also:
Constant Field Values

DSA

public static final java.lang.String DSA
The key algortihm name for DSA.

See Also:
Constant Field Values

DH

public static final java.lang.String DH
The key algortihm name for DH.

See Also:
Constant Field Values

ECDSA

public static final java.lang.String ECDSA
The key algortihm name for ECDSA.

See Also:
Constant Field Values

KEA

public static final java.lang.String KEA
The key algortihm name for KEA.

See Also:
Constant Field Values

GENERIC_SECRET

public static final java.lang.String GENERIC_SECRET
The key algortihm name for GENERIC_SECRET.

See Also:
Constant Field Values

RC2

public static final java.lang.String RC2
The key algortihm name for RC2.

See Also:
Constant Field Values

RC4

public static final java.lang.String RC4
The key algortihm name for RC4.

See Also:
Constant Field Values

DES

public static final java.lang.String DES
The key algortihm name for DES.

See Also:
Constant Field Values

DES2

public static final java.lang.String DES2
The key algortihm name for DES2.

See Also:
Constant Field Values

DESede

public static final java.lang.String DESede
The key algortihm name for DESede (=DES3).

See Also:
Constant Field Values

CAST

public static final java.lang.String CAST
The key algortihm name for CAST.

See Also:
Constant Field Values

CAST3

public static final java.lang.String CAST3
The key algortihm name for CAST3.

See Also:
Constant Field Values

CAST5

public static final java.lang.String CAST5
The key algortihm name for CAST5 (=CAST128).

See Also:
Constant Field Values

CAST128

public static final java.lang.String CAST128
The key algortihm name for CAST128 (=CAST5).

See Also:
Constant Field Values

RC5

public static final java.lang.String RC5
The key algortihm name for RC5.

See Also:
Constant Field Values

IDEA

public static final java.lang.String IDEA
The key algortihm name for IDEA.

See Also:
Constant Field Values

SKIPJACK

public static final java.lang.String SKIPJACK
The key algortihm name for SKIPJACK.

See Also:
Constant Field Values

BATON

public static final java.lang.String BATON
The key algortihm name for BATON.

See Also:
Constant Field Values

JUNIPER

public static final java.lang.String JUNIPER
The key algortihm name for JUNIPER.

See Also:
Constant Field Values

CDMF

public static final java.lang.String CDMF
The key algortihm name for CDMF.

See Also:
Constant Field Values

AES

public static final java.lang.String AES
The key algortihm name for AES.

See Also:
Constant Field Values

BLOWFISH

public static final java.lang.String BLOWFISH
The key algortihm name for AES.

See Also:
Constant Field Values

TWOFISH

public static final java.lang.String TWOFISH
The key algortihm name for AES.

See Also:
Constant Field Values

VENDOR_DEFINED

public static final java.lang.String VENDOR_DEFINED
The key algortihm name for VENDOR_DEFINED.

See Also:
Constant Field Values
Method Detail

create

public static IAIKPKCS11Key create(TokenManager tokenManager,
                                   iaik.pkcs.pkcs11.objects.Key keyObject)
Create a new instance of a IAIKPKCS11Key which's token managed by the given token manager and is based on the given PKCS#11 key object.

Parameters:
tokenManager - The token manager of the token where the key is.
keyObject - The PKCS#11 key object.
Returns:
A new IAIKPKCS11Key that can be used with this provider.
Postconditions
(result <> null)

getAlgorithmName

public static java.lang.String getAlgorithmName(int keyTypeCode)
Get the name of the algorthim of the give key type code.

Parameters:
keyTypeCode - The PKCS#11 key type code; e.g. 0x00000000 for RSA.
Returns:
The name of the algorithm, or null if unknown algorithm; e.g. "RSA".

getAlgorithmCode

public static java.lang.Long getAlgorithmCode(java.lang.String keyTypeName)
Get the code of the algorthim with the given name.

Parameters:
keyTypeName - The key type name. This may be one of the defined constants in this class or one of those declared in the key type properties file; e.g. RSA.
Returns:
The type code of the algorithm, or null if unknown algorithm; e.g. 0x00000000 for RSA.

destroy

public void destroy()
A call to this method destroys the underlying pkcs#11 key object. This applies to permanent keys (token objects) and session keys as well. Any session which has been hold by this key object will be released during this call. Use this method with care. Ensure that the key object is not longer used. It will be unrecoverable.


isDestroyed

public boolean isDestroyed()
Returns true, if the destroy() method has already been called successfully.

Returns:
true, if the object has alread been destroyed.

getAlgorithm

public java.lang.String getAlgorithm()
The name of the algorthim of this key object; e.g. "RSA".

Specified by:
getAlgorithm in interface java.security.Key
Returns:
The name of the algorithm, or null if unknown algorithm.

getAlias

public java.lang.String getAlias()
Get the alias name for this key. This alias may be used as alias in the key store.

Returns:
An alais name for this key.

getTokenManager

public TokenManager getTokenManager()
Get the token manager this object works with.

Returns:
The token manager of this key.

getKeyObject

public iaik.pkcs.pkcs11.objects.Key getKeyObject()
Get the associated PKCS#11 key object.

Returns:
The PKCS#11 key object.

getKeyID

public byte[] getKeyID()
Get the ID of this PKCS#11 key object; i.e. the exact value of the PKCS#11 CKA_ID attribute of the asociated key object. This is used to get the corresponding private key and certificate.

Returns:
The value of the PKCS#11 CKA_ID attribute.

getEncoded

public byte[] getEncoded()
UNSUPPORTED.

Specified by:
getEncoded in interface java.security.Key
Returns:
null.
Postconditions
(result == null)

getFormat

public java.lang.String getFormat()
UNSUPPORTED.

Specified by:
getFormat in interface java.security.Key
Returns:
null.
Postconditions
(result == null)

getSession

public iaik.pkcs.pkcs11.Session getSession()
The chached session in this key. Used for keeping the session of session objects open to avoid session keys being destroyed.

Returns:
The chaed session or null.

setSession

public void setSession(iaik.pkcs.pkcs11.Session session)
Cache the given session in this key. Used for keeping the session of session objects open to avoid session keys being destroyed. If the session argument is null, this key will release the close-lock of its session.

Parameters:
session - The cached session or null.

setAutoDestroy

public void setAutoDestroy(boolean autoDestroy)
Set if this key object should be deleted automatically upon object finalization. If this is true and this object gets finalized by the garbage collector, the finalize() method of this key object will destroy the underlying PKCS#11 key object.

This is useful especially for keys which are a result of automatic translation to PKCS#11 keys. They are usually no longer used after this object got finalized.

The default value is false.

Parameters:
autoDestroy - true, if the underlying PCKCS#11 key object should be deleted upon object finalization.

isAutoDestroy

public boolean isAutoDestroy()
Returns true if this key object is marked for automatic deletion upon object finalization. If this is true and this object gets finalized by the garbage collector, the finalize() method of this key object will destroy the underlying PKCS#11 key object.

The default value is false.

Returns:
true, if this key is marked for automatic deletion.

toString

public java.lang.String toString()
Returns a string presentation for debug output.

Overrides:
toString in class java.lang.Object
Returns:
The string presentation of this object.

finalize

public void finalize()
              throws java.lang.Throwable
Tries to release the close-lock of this key's session if there is one.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable - If finalization fails.

IAIK PKCS#11 Provider API Documentation
version 1.6

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

IAIK at Graz University of Technology, Austria, Europe
Copyright 2001-2004, IAIK, Graz University of Technology, Inffeldgasse 16a, 8010 Graz, Austria. All Rights Reserved.
version 1.6