iaik.pkcs.pkcs11.me.Cipher
|
IAIK PKCS#11 Provider Micro Edition version 1.0 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
This class encrypts and decrypts data using the associated token. The used cipher can be an asymmetric cipher as well as a symmetric cipher. In addition, it supports wrapping and unwrapping of symmetric keys; i.e. encrypting and decrypting symmetric keys with another key on the token. In this case, the key encryption key is usually an asymmetric key (e.g. RSA).
The application must initiate a cipher operation using the
init(int, Key, byte[]) method. Thereafter, it feeds in the
input data (i.e. the data to be encrypted, or the encrypted data)
using update(byte[]).
To finish the operation, the application calls doFinal().
The application should always finish each operation, otherwise
resources may be bound until the operation gets finished.
For key-wrapping and key-unwrapping, the application calls
init(int, Key, byte[]) and then wrap(Key) or
unwrap(byte[], String, int, String, boolean) respectively,
optionally followed by some more wrap(Key) or
unwrap(byte[], String, int, String, boolean) calls.
Remember that wrap(Key) and
unwrap(byte[], String, int, String, boolean) rest the
Cipher object into its last initialized state.
Note, that there is no doFinal() call for
key-wrapping and key-unwrapping.
A typical piece of code using this class may look like this.
Token token = ... // get token from module
long algorithm = ALGORITHM_RSA_PKCS1PADDING;
if (!token.supportsAlgorithm(algorithm)) {
... // token does not support this cipher algorithm
}
// login user first to be able to see private key objects on the token
char[] pin = ... // e.g. prompt the PIN from the user
token.loginUser(pin);
// get a key store view of the keys and certificates on the token
KeyStore keyStore = token.getKeyStore();
String alias = ... // select a key from the key store
Key key = keyStore.getKey(alias);
if (!key.canBeUsedFor(Key.USAGE_DECRYPTION)) {
... // this key cannot be used for decryption
}
// also get the DER encoded certificate for the key;
// e.g. for matching with the encryption certificate
byte[] certificate = keyStore.getCertificate(alias);
Cipher cipher = token.getCipher(algorithm);
cipher.init(Cipher.DECRYPT_MODE, key);
byte[] dataToBeDecrypted = ... // assign encrypted data
cipher.update(dataToBeDecrypted);
byte[] decryptedData = cipher.doFinal();
The variable decryptedData will hold the decrypted data; e.g.
a symmetric key value which was encrypted.
This class is not thread safe.
Token,
Token.getCipher(long),
Token.supportsAlgorithm(long, int),
Key.canBeUsedFor(long)| Field Summary | |
static long |
ALGORITHM_AES_CBC_PKCS5PADDING
The algorithm code constant for the AES block cipher according to FIPS PUB 197 with PKCS#5 padding as specified in PKCS#5 version 1.5. |
static long |
ALGORITHM_AES_ECB
The algorithm code constant for the AES block cipher according to FIPS PUB 197 without any padding. |
static long |
ALGORITHM_DES_CBC_PKCS5PADDING
The algorithm code constant for the DES block cipher according to FIPS PUB 46-3 with PKCS#5 padding as specified in PKCS#5 version 1.5. |
static long |
ALGORITHM_DES_ECB
The algorithm code constant for the DES block cipher according to FIPS PUB 46-3 without any padding. |
static long |
ALGORITHM_DESEDE_CBC_PKCS5PADDING
The algorithm code constant for the Triple DES block cipher according to FIPS PUB 46-3 with PKCS#5 padding as specified in PKCS#5 version 1.5. |
static long |
ALGORITHM_DESEDE_ECB
The algorithm code constant for the Triple DES block cipher according to FIPS PUB 46-3 without any padding. |
static long |
ALGORITHM_IDEA_CBC_PKCS5PADDING
The algorithm code constant for the IDEA block cipher (see e.g. |
static long |
ALGORITHM_IDEA_ECB
The algorithm code constant for the IDEA block cipher (see e.g. |
static long |
ALGORITHM_RC2_CBC_PKCS5PADDING
The algorithm code constant for the RC2 block cipher according to RFC 2268 with PKCS#5 padding as specified in PKCS#5 version 1.5. |
static long |
ALGORITHM_RC2_ECB
The algorithm code constant for the RC2 block cipher according to RFC 2268 without any padding. |
static long |
ALGORITHM_RC4
The algorithm code constant for the RC4 stream cipher (see e.g. |
static long |
ALGORITHM_RSA_OAEPPADDING
The algorithm code constant for RSA OAEP asymmetric encryption according to PKCS#1 version 2.1. |
static long |
ALGORITHM_RSA_PKCS1PADDING
The algorithm code constant for RSA asymmetric encryption according to PKCS#1 version 1.5. |
static int |
DECRYPT_MODE
This constant is used to signal decryption. |
static int |
ENCRYPT_MODE
This constant is used to signal encryption. |
static int |
UNWRAP_MODE
This constant is used to signal key-unwrapping. |
static int |
WRAP_MODE
This constant is used to signal key-wrapping. |
| Method Summary | |
byte[] |
doFinal()
Finish the current encryption or decryption operation and return the final result; i.e. the enciphered data. |
void |
init(int mode,
Key key,
byte[] iv)
Initialize a new encryption or decryption operation. |
Key |
unwrap(byte[] wrappedKey,
java.lang.String wrappedKeyAlgorithm,
int keyUsage,
java.lang.String label,
boolean tokenObject)
Unwrap (decrypt) a wrapped secret key. |
byte[] |
update(byte[] data)
Feed a piece of data into the current cipher operation. |
byte[] |
wrap(Key key)
Wrap (encrypt) the specified symmetric key with the wrapping key which has been provided to the init(int, Key, byte[]) call.
|
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final long ALGORITHM_RSA_PKCS1PADDING
RSA/NONE/PKCS1Padding in the JCE.
public static final long ALGORITHM_RSA_OAEPPADDING
RSA/NONE/PKCS1Padding in the JCE.
public static final long ALGORITHM_AES_ECB
AES/ECB/NoPadding in the JCE.
public static final long ALGORITHM_AES_CBC_PKCS5PADDING
AES/CBC/PKCS5Padding in the JCE.
public static final long ALGORITHM_DES_ECB
DES/ECB/NoPadding in the JCE.
public static final long ALGORITHM_DES_CBC_PKCS5PADDING
DES/CBC/PKCS5Padding in the JCE.
public static final long ALGORITHM_DESEDE_ECB
DESede/ECB/NoPadding in the JCE.
public static final long ALGORITHM_DESEDE_CBC_PKCS5PADDING
DESede/CBC/PKCS5Padding in the JCE.
public static final long ALGORITHM_IDEA_ECB
IDEA/ECB/NoPadding in the JCE.
public static final long ALGORITHM_IDEA_CBC_PKCS5PADDING
IDEA/CBC/PKCS5Padding in the JCE.
public static final long ALGORITHM_RC2_ECB
RC2/ECB/NoPadding in the JCE.
public static final long ALGORITHM_RC2_CBC_PKCS5PADDING
RC2/CBC/PKCS5Padding in the JCE.
public static final long ALGORITHM_RC4
RC4/NONE/NoPadding in the JCE.
public static final int ENCRYPT_MODE
public static final int DECRYPT_MODE
public static final int WRAP_MODE
public static final int UNWRAP_MODE
| Method Detail |
public void init(int mode,
Key key,
byte[] iv)
throws PKCS11RuntimeException
mode is ENCRYPT_MODE;
i.e. key.canBeUsedFor(Key.USAGE_ENCRYPTION)true.
If mode is DECRYPT_MODE, the specified key must be valid for decryption;
i.e. key.canBeUsedFor(Key.USAGE_DECRYPTION)true.
If mode is WRAP_MODE, the specified key must be valid for key-wrapping;
i.e. key.canBeUsedFor(Key.USAGE_WRAP)true.
If mode is UNWRAP_MODE, the specified key must be valid for key-unwrapping;
i.e. key.canBeUsedFor(Key.USAGE_UNWRAP)true.
After this call, the application calls update(byte[])
one or more times to process encryption or decryption.
To finish the encryption or decryption operation, the application
calls doFinal().
For key-wrapping or key-unwrapping, the application calls
wrap(iaik.pkcs.pkcs11.me.Key) or unwrap(byte[], java.lang.String, int, java.lang.String, boolean) after this initialization call.
mode - The mode; i.e. ENCRYPT_MODE for encryption,
DECRYPT_MODE for decryption,
WRAP_MODE for key-wrapping and
UNWRAP_MODE for key-unwrapping.key - The encryption key, decryption key, wrapping key or unwrapping key,
depending on the mode.iv - Initialization vector if the cipher is a block cipher
and operates in a feedback mode (e.g. CBC).
PKCS11RuntimeException - If initializing the cipher fails.update(byte[]),
doFinal(),
Key.canBeUsedFor(long)
public byte[] update(byte[] data)
throws PKCS11RuntimeException
The underlying cipher will process as many of data as possible
and will return any finished result data. However, the cipher
may not have enough data to finish the processing of a block
of data. Then, it may return null and return the
result as return value of one of the next update(byte[])
calls or of the final doFinal() call. Anyway, the
application must not ignore a result of any call to
update(byte[]). Otherwise, it will end up with
an incomplete result.
The application may call this method one or more
times after calling init(int, Key, byte[]).
After providing the last input data, the application
calls doFinal() to finish the current operation.
data - The piece of data;
i.e. data to be encrypted or enciphered data to be decrypted.
null if the cipher had to
delay the processing until the next call to update(byte[])
or doFinal().
PKCS11RuntimeException - If the cipher operation fails.init(int, Key, byte[]),
doFinal()
public byte[] doFinal()
throws PKCS11RuntimeException
After this call, this cipher object is reset to the state
in which it was right after the call to init(int, Key, byte[]).
The application can reuse it for another encryption or decryption
operation; i.e. it can start with calling update(byte[])
without calling init(int, Key, byte[]) first.
The application may also initialize the object again for a new encryption or decryption operation.
PKCS11RuntimeException - If the cipher operation fails.init(int, Key, byte[]),
update(byte[])
public byte[] wrap(Key key)
throws PKCS11RuntimeException
init(int, Key, byte[]) call.
Note that the mode provided to the last init(int, Key, byte[]) call
must have been WRAP_MODE.
After this call, the object is reset to the state in which it was just
after the last call to init(int, Key, byte[]);
i.e. the application can start a new key-wrapping operation with the
same key using wrap(Key) without calling
init(int, Key, byte[]) again.
Do not call doFinal() after wrap(Key)!
key - The key to wrap.
PKCS11RuntimeException - If wrapping the given key fails; e.g. if the
specified key is too large.
public Key unwrap(byte[] wrappedKey,
java.lang.String wrappedKeyAlgorithm,
int keyUsage,
java.lang.String label,
boolean tokenObject)
throws PKCS11RuntimeException
Note that the mode provided to the last init(int, Key, byte[]) call
must have been unwrap(byte[], String, int, String, boolean).
After this call, the object is reset to the state in which it was just
after the last call to init(int, Key, byte[]);
i.e. the application can start a new key-unwrapping operation with the
same key using unwrap(byte[], String, int, String, boolean)
without calling init(int, Key, byte[]) again.
Do not call doFinal() after
unwrap(byte[], String, int, String, boolean)!
wrappedKey - The wrapped secret key.wrappedKeyAlgorithm - The algorithm of the wrapped key;
e.g. Key.ALGORITHM_AES or Key.ALGORITHM_DESEDE.keyUsage - The usage of the new key object. It can be any sum of
KeyGenerator.USAGE_CIPHER, KeyGenerator.USAGE_SIGNATURE
and KeyGenerator.USAGE_WRAP. The use is the same as in
KeyGenerator.init(int, int, String, boolean).label - The label of the new key object. This can be used later as alias to
access the key via the key store.tokenObject - true to make the new secret key a permanent key
on the token (i.e. a token object), or false to
make is just a session key which will be deleted after the
associated session is closed.
PKCS11RuntimeException - If unwrapping the key fails for some reason.
|
IAIK PKCS#11 Provider Micro Edition version 1.0 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||