Class semper.crypto.CryptoMan

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class semper.crypto.CryptoMan

java.lang.Object
   |
   +----semper.crypto.CryptoMan

public class CryptoMan
extends Object
implements CryptoConstants

CryptoMan provides an interface to all cryptologic services needed by SEMPER. These comprise encryption (symmetric and public-key), signaing and message authentication (MAC). Furthermore, CryptoMan provides hashing functions. Algorithms are encoded by integers as described in CryptoConstants. The actual functions are implemented in a module. A module based on Cryptomathic's tools is implemented in CRMModule. As soon as the interface to this module is more stable, an interface will be defined, which modules must implement.

Version:: $Revision: 1.36 $ $Date: 1997/04/23 14:55:33 $
Author:: Jesper Drud Nielsen ([email protected]), Torben Pedersen ([email protected])
See Also:: CryptoConstants, CRMModule

CryptoMan(): Instantiation of this class is prevented by throwing an exception.

decipher(byte[], boolean, int, CryptoKeyInfo): Decipher an array of bytes using the algorithm described by keyInfo.
encipher(byte[], boolean, int, CryptoKeyInfo): Encipher a message using the conventional algorithm described by keyInfo.
generateHash(int, byte[], boolean): Hash a string.
generateMAC(byte[], boolean, int, CryptoKeyInfo): Generate a MAC.
generateMasterKey(CryptoKeyInfo): Method for generating and installing a masterkey.
generatePubKeyPair(boolean, byte[], CryptoKeyInfo, CryptoKeyInfo, CryptoKeyInfo): Generate a random public key pair as above, but algorithm as well as key length define in a dialog with the user (through TINGUIN).
generatePubKeyPair(int, byte[], CryptoKeyInfo, CryptoKeyInfo, CryptoKeyInfo): Generate a random public key pair as above, but with 512 bits key length.
generatePubKeyPair(int, int, byte[], CryptoKeyInfo, CryptoKeyInfo, CryptoKeyInfo): Generate a random public key pair.
generateSignature(byte[], boolean, CryptoKeyInfo, int): Sign a string.
generateSymKey(int, byte[]): Generate a random symmetric key.
getLength(int): Returns the maximal lenght of a key of the algorithm.
getSerialNo(): Outputs the lastly used key serial number.
init(): This function initialises the Crypto manager.
initConstInt(): Initialises the vector of integers encoding the cryptographic parameters.
initConstString(): This function initialises a vectore of descriptions of the constants used to designatre cryptographic constants.
int2Str(int): Converts a constant to a string describing the constant.
isInitialised(): Tells whether CryptoMan is initialised.
masterKeyDecrypt(byte[]): Decrypts the input under masterKey.
masterKeyEncrypt(byte[]): Encrypts the input under the master key (used to encrypt keys before being stored).
pkDecipher(byte[], CryptoKeyInfo, int, int): Decipher an encrypted key using the algorithm described by keyInfo.
pkEncipher(CryptoKeyInfo, boolean, CryptoKeyInfo, int): Encipher a conventional key using the asymmetric algorithm described by keyInfo.
randomBytes(int): Returns an array of random bytes.
signatureLength(int): Returns the maximal lenght of a signature using the given algorithm.
str2Int(String): Converts a String to a constant.
updateMasterKey(CryptoKeyInfo): Decrypt the masterKey under a key derived from the password.
updateSerialNo(): Updates the serial number uniquely identifying keys.
verifyMAC(byte[], boolean, int, byte[], CryptoKeyInfo): Verify a MAC.
verifySignature(byte[], boolean, byte[], CryptoKeyInfo, int): Verify a signature.
whichAlgs(int): Gives information of supported algorithms.

CryptoMan

  public CryptoMan() throws CryptoManException

Instantiation of this class is prevented by throwing an exception. All services should be called using static calls.

Throws: CryptoManException: if this method is called

isInitialised

  public static boolean isInitialised()

Tells whether CryptoMan is initialised. The CryptoMan is initialised when CryptoMan.init() has been successfully executed.

Returns:: true if CryptoMan has been executed, false otherwise.

init

  public static void init() throws CryptoManException

This function initialises the Crypto manager. The initialisation mainly does the following:

Loads the correct module (for the moment this is a default module, CRMModule ).
Initialises the pseudo random generator (PRG) of the module (the first time this is based on a user supplied seed - entered through TINGUIN - later initialisations use a seed stored in the archive). The class CryptoSeed contains this seed.
Loads the master key from archive (the very first time a master key is generated, and the user is asked to provide a password by entering it twice; in all subsequent initialisations the user must provide this password).

The very first time the manager is initialised the user is asked to enter a seed of at least 16 characters (this may not be sufficient). Furthermore, the user is requested to define a password which protects his master key (the masterkey protects all other keys). In later initialisations the user has to enter this password. Here no seed is needed, as the crypto manager during initialisation computes a new seed (using the pseudo random generator of the module) and stores it so that it can used in the next initialisation.

Throws: CryptoManException: if initialisation could not be done

updateSerialNo

  public static synchronized void updateSerialNo()

Updates the serial number uniquely identifying keys. The crypto manager assigns a unique (for the user) serial number to all keys generated. This method is sunchronized in order to ensure that different keys will get different numbers. The serial number can be obtained by reading a private variable of the manager.

getSerialNo

  public static long getSerialNo()

Outputs the lastly used key serial number. This function is only necessary if the serial number is needed outside the manager, as every service in the manager can access the value of the serial number immediately.

Returns:: A new serial number

randomBytes

  public static synchronized byte[] randomBytes(int length) throws CryptoManException

Returns an array of random bytes. These bytes are generated by the PRG of the module.

Parameters:: length - is requested number of bytes
Returns:: an array of random bytes
Throws: CryptoManException: if the module is not initialised

generateSymKey

  public static synchronized CryptoKeyInfo generateSymKey(int alg,
                                                          byte seed[]) throws CryptoManException

Generate a random symmetric key. A key for use by a symmetric algorithm is generated and returned. A key identifier is associated with the key. It is of the following form: "CryptoKeyInfo_userId_algId_serialnumber". The serial number is the unique number maintained by the and the algorithm is int2Str(alg).

Parameters:: alg - the symmetric algorithm for which a key is requested; seed - (optional) is used as random seed for the key generation. If no seed (at least 16 byts) is supplied a seed generated by the PRG will be used
Returns:: a cryptographic key token containing the random key
Throws: CryptoManException: if the algorithm is not suported, the pseudo random generator is not initialised (and no seed is provided), or an error occured in the module
See Also:: randomBytes, updateSerialNo

generatePubKeyPair

  public static synchronized void generatePubKeyPair(int alg,
                                                     int keyLength,
                                                     byte seed[],
                                                     CryptoKeyInfo commonKeyInfo,
                                                     CryptoKeyInfo secKeyInfo,
                                                     CryptoKeyInfo pubKeyInfo) throws CryptoManException

Generate a random public key pair. A key pair for use by an asymmetric algorithm is generated and returned. A key identifier is associated with the key. It is of the following form: "CryptoKeyInfo_userId_algId_Type_serialnumber", where Type is "sk", "pk" or "ck" depending on whether the key is secret, public or common. The serial number is obtained from the manager itself and the algorithm is int2Str(alg). The identity of commonKeyInfo is only set if a new common part is generated. For the moment the key lenght is hard coded to 64 bytes. This is clearly insufficient for real security, but is chosen to make test programs faster. In the future it will be possible to define the key length in the preferences (probably with 128 bytes as default).

Parameters:: alg - the asymmetric algorithm for which a key pair is requested; keyLength - is the length of the key (in bytes); seed - is the seed to be used. If no seed supplied (null or seed.length == 0) the CryptoModule will use its own PRG); commonKeyInfo - contains common part of the publie key (e.g., a description of the group in case of DL based schemes). If such a value is supplied as input the keys will be generated with respect to this common part); secKeyInfo - the generated secret key (contains a pointer to commonKeyInfo if appropriate); pubKeyInfo - the generated public key (contains a pointer to commonKeyInfo if appropriate)
Returns:: void
Throws: CryptoManException: if the algorithm is not supported or no seed is provided and the manager is not initilised, or an error occured in the module
See Also:: CRMModule

generatePubKeyPair

  public static synchronized void generatePubKeyPair(int alg,
                                                     byte seed[],
                                                     CryptoKeyInfo commonKeyInfo,
                                                     CryptoKeyInfo secKeyInfo,
                                                     CryptoKeyInfo pubKeyInfo) throws CryptoManException

Generate a random public key pair as above, but with 512 bits key length. A key pair for use by an asymmetric algorithm is generated and returned. A key identifier is associated with the key. It is of the following form: "CryptoKeyInfo_userId_algId_Type_serialnumber", where Type is "sk", "pk" or "ck" depending on whether the key is secret, public or common. The serial number is obtained from the manager itself and the algorithm is int2Str(alg). The identity of commonKeyInfo is only set if a new common part is generated. For the moment the key lenght is hard coded to 64 bytes. This is clearly insufficient for real security, but is chosen to make test programs faster. In the future it will be possible to define the key length in the preferences (probably with 128 bytes as default).

Parameters:: alg - the asymmetric algorithm for which a key pair is requested; seed - is the seed to be used. If no seed supplied (null or seed.length == 0) the CryptoModule will use its own PRG); commonKeyInfo - contains common part of the publie key (e.g., a description of the group in case of DL based schemes). If such a value is supplied as input the keys will be generated with respect to this common part); secKeyInfo - the generated secret key (contains a pointer to commonKeyInfo if appropriate); pubKeyInfo - the generated public key (contains a pointer to commonKeyInfo if appropriate)
Returns:: void
Throws: CryptoManException: if the algorithm is not supported or no seed is provided and the manager is not initilised, or an error occured in the module
See Also:: CRMModule

generatePubKeyPair

  public static synchronized void generatePubKeyPair(boolean signing,
                                                     byte seed[],
                                                     CryptoKeyInfo commonKeyInfo,
                                                     CryptoKeyInfo secKeyInfo,
                                                     CryptoKeyInfo pubKeyInfo) throws CryptoManException

Generate a random public key pair as above, but algorithm as well as key length define in a dialog with the user (through TINGUIN). A key pair for use by an asymmetric algorithm is generated and returned. A key identifier is associated with the key. It is of the following form: "CryptoKeyInfo_userId_algId_Type_serialnumber", where Type is "sk", "pk" or "ck" depending on whether the key is secret, public or common. The serial number is obtained from the manager itself and the algorithm is int2Str(alg). The identity of commonKeyInfo is only set if a new common part is generated. For the moment the key lenght is hard coded to 64 bytes. This is clearly insufficient for real security, but is chosen to make test programs faster. In the future it will be possible to define the key length in the preferences (probably with 128 bytes as default).

Parameters:: signing - is a boolean indicating the type of functionality requested (true: signing, false: encryption); seed - is the seed to be used. If no seed supplied (null or seed.length == 0) the CryptoModule will use its own PRG); commonKeyInfo - contains common part of the publie key (e.g., a description of the group in case of DL based schemes). If such a value is supplied as input the keys will be generated with respect to this common part); secKeyInfo - the generated secret key (contains a pointer to commonKeyInfo if appropriate); pubKeyInfo - the generated public key (contains a pointer to commonKeyInfo if appropriate)
Returns:: void
Throws: CryptoManException: if the algorithm is not supported or no seed is provided and the manager is not initilised, or an error occured in the module
See Also:: CRMModule

generateHash

  public static byte[] generateHash(int alg,
                                    byte message[],
                                    boolean fileInput) throws CryptoManException

Hash a string. The input array is hashed using the given hash algorithm.

Parameters:: alg - the hash algorithm; message - the message to hash; if - fileInput is true, this method will interpret message as the name of a file, the contents of which will be hashed.
Returns:: the hash value
Throws: CryptoManException: if the algorithm is not supported or an error occured in the module

encipher

  public static byte[] encipher(byte message[],
                                boolean fileEncryption,
                                int msgPadding,
                                CryptoKeyInfo keyInfo) throws CryptoManException

Encipher a message using the conventional algorithm described by keyInfo.

Parameters:: message - the message to encipher or filename of cleartext; fileEncryption - is a boolean indicating if input/output is from/to files. If fileEncryption is requested message is the name of the input file.; msgPadding - indicates how the message is padded before encryption; keyInfo - the key token identifying the algorithm and key to be used
Returns:: the enciphered string (if file encryption, the name of the encrypted file is returned).
Throws: CryptoManException: if encryption failed or some input is missing
See Also:: decipher, pkEncipher

decipher

  public static byte[] decipher(byte cipher[],
                                boolean fileDecryption,
                                int msgPadding,
                                CryptoKeyInfo keyInfo) throws CryptoManException

Decipher an array of bytes using the algorithm described by keyInfo. After the ciphertext has been decrypted the padding (added during encipherment) is removed.

Parameters:: cipher - the (ciphered) message to decipher; fileDecryption - is a boolean indicating if input/output is from/to files. If fileDecryption is requested cipher is the name of the input file.; msgPadding - indicates how the message is padded before encryption; keyInfo - the key token identifying the algorithm and key
Returns:: the deciphered string
Throws: CryptoManException: if decryption failed
See Also:: encipher

pkEncipher

  public static byte[] pkEncipher(CryptoKeyInfo convKeyInfo,
                                  boolean makeConvKey,
                                  CryptoKeyInfo pubKeyInfo,
                                  int keyEncryption) throws CryptoManException

Encipher a conventional key using the asymmetric algorithm described by keyInfo. The key is padded as described by the parameter keyEncryption before being encrypted.

Parameters:: convKeyInfo - contains the symmetric key in clear to be enciphered (possibly generated by pkEncipher and returned in convKeyInfo); makeKeyInfo - if true a new symmetric key is generated (corresponding to the algorithm designated by convKeyInfo); pubKeyInfo - is the public key to be used; keyEncryption - describes how the conventional key is embedded in a block for public key encryption
Returns:: the enciphered key
Throws: CryptoManException: if pubKeyInfo is missing or an error occurs in the module
See Also:: encipher, pkDecipher

pkDecipher

  public static byte[] pkDecipher(byte cipher[],
                                  CryptoKeyInfo keyInfo,
                                  int keyEncryption,
                                  int convAlg) throws CryptoManException

Decipher an encrypted key using the algorithm described by keyInfo.

Parameters:: cipher - the (ciphered) message to decipher; keyInfo - the key token identifying the algorithm and key; keyEncryption - describes how the conventional key is embedded in a block for public key encryption; convAlg - designates the conventional algorithm corresponding to the encrypted key
Returns:: the deciphered string
Throws: CryptoManException: if decryption failed
See Also:: pkEncipher, decipher

generateSignature

  public static byte[] generateSignature(byte message[],
                                         boolean fileInput,
                                         CryptoKeyInfo signatureKeyInfo,
                                         int hashAlg) throws CryptoManException

Sign a string. A digital signature is applied to the message using a secret signature key. IF a DSA signature is requested SHS-1 will automatically be used as hash function.

Parameters:: message - the message on which to generate a signature; fileInput - indicates if message is the name of a file to be signed; keyInfo - the key token identifying the signature algorithm and secret key; hashAlg - indicates the hashing algorithm to be used (not needed in case of DSA)
Returns:: the digital signature
Throws: CryptoManException: if the algorithm is not supported or an error in module
See Also:: verifySignature

verifySignature

  public static boolean verifySignature(byte message[],
                                        boolean fileInput,
                                        byte signature[],
                                        CryptoKeyInfo keyInfo,
                                        int hashAlg) throws CryptoManException

Verify a signature. A digital signature on a message is verified using a public signature key.

Parameters:: message - the message on which to verify a signature; fileInput - indicates if message is the name of a file to be signed; signature - the digital signature; keyInfo - the key token identifying the signature algorithm and public key; hashAlg - defines the hashing algorithm to be used
Returns:: true if signature valid, otherwise false
Throws: CryptoManException: if the algorithm is not supported or an error in module
See Also:: generateSignature

generateMAC

  public static byte[] generateMAC(byte message[],
                                   boolean fileInput,
                                   int MACalg,
                                   CryptoKeyInfo keyInfo) throws CryptoManException

Generate a MAC. A message authentication code is generated on a message using a symmetric key. The MAC algorithm is specified using two parameters:

The input key (keyInfo) designates the key and the conventional algorithm for which the key is used
The integer MACalg specifies how this conventional algorithm is used to compute the hash value.

Parameters:: message - the message on which to generate a MAC; fileInput - is true if message is the name of a file; MACalg - designates the MAC algorithm; keyInfo - the key token identifying the MAC algorithm and key
Returns:: the MAC string
Throws: CryptoManException: if the algorithm is not supported, a key is missing or an error in module
See Also:: verifyMAC

verifyMAC

  public static boolean verifyMAC(byte message[],
                                  boolean fileInput,
                                  int MACalg,
                                  byte MAC[],
                                  CryptoKeyInfo keyInfo) throws CryptoManException

Verify a MAC. A message authentication code is verified using a symmetric key key.

Parameters:: message - the message on which to verify the MAC; fileInput - is true if message is the name of a file; MACalg - designates the MAC algorithm; MAC - the MAC to verify; keyInfo - the key token identifying the MAC algorithm and key
Returns:: true if MAC valid, otherwise false
Throws: CryptoManException: if the algorithm is not supported, a key is missing or an error in module
See Also:: generateMAC

whichAlgs

  public static Vector whichAlgs(int secService)

Gives information of supported algorithms. The security services supported by CryptoMan are encoded as follows. 0: Conventional krypto system 1: MAC algorithm 2: Public key de/encryption 3: Methods for making signatures 4: Hash functions

Parameters:: secService - describes the service
Returns:: a vector of algorithms implementing the requested service

getLength

  public static int getLength(int algId) throws CryptoManException

Returns the maximal lenght of a key of the algorithm.

Parameters:: algId - the algorithm for which the maximal key length is requested
Returns:: lenght of keys (representation) for the algorithm
Throws: CryptoManException: if the algorithm is not supported

signatureLength

  public static int signatureLength(int algId) throws CryptoManException

Returns the maximal lenght of a signature using the given algorithm. This is useful when allocating space for a signature.

Parameters:: algId - the algorithm for which the maximal signature length is requested
Returns:: maximal length of the signature
Throws: CryptoManException: if the algorithm is not supported

generateMasterKey

  public static void generateMasterKey(CryptoKeyInfo passwdKeyInfo) throws CryptoManException

Method for generating and installing a masterkey. Generates a DES key to be used as a master key. The attribute masterKey is updated as part of this. The actual key value is encrypted under the password and stored in archive

Parameters:: passwordKeyInfo - protects the master key
Throws: CryptoManException: in case of errors when generating or storing the key
See Also:: generateSymKey

updateMasterKey

  public static void updateMasterKey(CryptoKeyInfo passwdKeyInfo) throws CryptoManException

Decrypt the masterKey under a key derived from the password. This function requires that the masterKey object has been retrieved from archive. If the key value of the master key is not encrypted, this function has no effect. Otherwise, if it is encrypted on the password corresponding to the input key, the key value in the master key object will be replaced by the key value in clear.

Parameters:: passwdKeyInfo - protects the master key
Throws: CryptoManException: if the key cannot be decrypted
See Also:: getKeyVal

masterKeyEncrypt

  public static byte[] masterKeyEncrypt(byte keyBytes[]) throws CryptoManException

Encrypts the input under the master key (used to encrypt keys before being stored). This is only possible if the crypto manager has been initialised (otherwise an exception is thrown).

Parameters:: keyBytes - is the byte array corresponding ot the key to be encrypted
Returns:: byte array with the encrypted key
Throws: CryptoManException: if the encryption fails
See Also:: masterKeyDecrypt

masterKeyDecrypt

  public static byte[] masterKeyDecrypt(byte encryptedKey[]) throws CryptoManException

Decrypts the input under masterKey. This function only works if the master key has been decrypted.

Parameters:: encryptedKey - is the byte array corresponding to the encrypted key
Returns:: byte array with the key
Throws: CryptoManException: if the decryption fails
See Also:: masterKeyEncrypt

initConstString

  public static void initConstString()

This function initialises a vectore of descriptions of the constants used to designatre cryptographic constants. This is a helper function.

initConstInt

  public static void initConstInt()

Initialises the vector of integers encoding the cryptographic parameters. This is a help function corresponding to initConstString.

int2Str

  public static String int2Str(int elem)

Converts a constant to a string describing the constant. The conversion is based on presumes that initConstInt and initConstString has been executed (as they are. when the crypto manager is initialised).

Parameters:: elem - is the integer constant
Returns:: string describing the constant (null if the constant is not defined)
See Also:: initConstString, initConstInt

str2Int

  public static int str2Int(String str)

Converts a String to a constant. The conversion is based on two vectors which must have been initialised. The conversion is based on presumes that initConstInt and initConstString has been executed (as they are. when the crypto manager is initialised).

Parameters:: str - is the string constant
Returns:: the corresponding integer (0 if the str does not define a constant)
See Also:: initConstString, initConstInt

All Packages  Class Hierarchy  This Package  Previous  Next  Index