gnu.crypto.exp.ust
public class UST extends Object
The Universal Security Transform (UST) is a cryptographic transform for providing confidentiality, message authentication, and replay protection. This transform is sufficient for providing these services to network protocols, though it does not specify a protocol itself.
UST has the following parameters:
All of these parameters MUST remain fixed for any given UST context.
The parameters INDEX_LENGTH
and MAX_KEYSTREAM_LENGTH
are defined by the keystream generator. This is because the keystream
generators used in UST are families of length-expanding pseudorandom
functions. At the time of implementing UST, the only such generators
available are (a) UMacGenerator and (b) ICMGenerator. Yet, both of these two algorithms require more
than just these two parameters to be fully qualified, and hence instantiated.
They both require an underlying block cipher as well as a block
size and key material. While default values are used for the
former two of these parameters -if they are not included in their
initialisation java.util.Map- the latter parameter; i.e. key
material, should be specified.
The parameters TAG_LENGTH
, MAX_HASH_LENGTH
, and
HASH_KEY_LENGTH
are defined by the hash function. Please note
that when the UST document refers to a hash function it actually
means a Universal Hash Function. At the time of implementing UST,
the only such functions available are UHash32 and
TMMH16, with the latter more suited for UST purposes
because it is independent from any other algorithm --the same is not true for
(our implementation of) UHash32
because of its current
dependencies on UMac32; although this may change in
the future. For this reason we shall only allow TMMH16
as the UST's underlying Universal Hash Function.
The length of any Plaintext protected by UST MUST NOT
exceed the smaller of (MAX_KEYSTREAM_LENGTH - TAG_LENGTH)
and
MAX_HASH_LEN
.
The value of HASH_KEY_LENGTH
MUST be no greater than
MAX_KEYSTREAM_LENGTH
. The value of TAG_LENGTH
MUST be no greater than HASH_KEY_LENGTH
.
Once a UST instance is initialised, one can (a) authenticate designated bytes -an operation that does not yield any output- and/or (b) encipher designated bytes -an operation that does yield an output equal in length to the input.
The understanding of the author of this implementation is that an
initialised UST can be used to process different messages while relying on
that UST to generate and use a different index value for each message without
the need for specifying eveytime that value; i.e. the implementation shall
keep track of the index to ensure no previously used value, generated and
used with the same key material, is ever re-used. Furthermore, because we
want to maximise the possible length of messages processed by a UST
with a given key material, each new/updated index value should yield
two keystream generators: one for use with the Integrity Protection
service (referred to as the Authentication Function in the UST draft),
and the other for use to encipher the message (Confidentiality Protection
service) --see Figures 1 and 2 in the UST draft. This way the maximum
plaintext protected by such a UST is (MAX_KEYSTREAM_LENGTH - TAG_LENGTH)
only, and the number of different messages protected by one set of
key material is (2^(8*INDEX_LENGTH) - 1)
--the index
value 0
being reserved to generate all other keying material! To
achieve this objective this implementation does the following:
MAX_INDEX
to be (2^(8*INDEX_LENGTH) - 1)
--all length quantities are expressed in bytes.0
and the user-supplied key material are used to initialise
an internal keystream generator. A message index is initialised
to -1
.MAX_INDEX
. If it is we
throw an exception. Otherwise, we generate from the internal
keystream enough key material to initialise two keystream generators, both
with that same index, one for the Integrity Protection Function
and the other for the Confidentiality Protection Function. Please
note that strictly speaking, the first of this pair of keystreams is NOT
the Confidentiality Protection Function keystream generator, since it is
also used to generate the bytes of the Integrity Protection Function's
Prefix. In other words, as soon as we detect the requirement for
Integrity Protection service, we instantiate the keystream generator
pair, even if the Confidentiality Protection service is not required.MAX_INDEX * 2 * (BLOCK_SIZE - INDEX_LENGTH) <= MAX_KEYSTREAM_LENGTHwhere
BLOCK_SIZE
is the underlying cipher's block size in
bytes.Another alternative to using two keystream generators, would have been to (a) use only one, but (b) in-line the code of the Authentication Function inside the UST. This way, (a) enough output bytes from that keystream would be used to setup the Authentication Function, and (b) the same output bytes from that keystream would be used to compute the authentication context, as well as encipher the message. But this weakens the UST, since an attacker, with a known plaintext, can reconstruct the keystream generator output (used for both the authentication and encipherement functions) by simply xoring the message with the ciphertext.
The next figure depicts a block diagram of our implementation of the UST:
+----------------------------+ +-----------+ | user-supplied key material +------+ +-----+ Index = 0 | +----------------------------+ | | +-----------+ V V +-----------+ +------------------------------+ | Index | | Internal Keystream Generator | +-----+-----+ +-------------+----------------+ | | +----|------------------------------+ | | +-----------------+ | +--->| Confidentiality | +----|--->| Protection +--+-----------------+ | | | Generator | | | | | +-----------------+ V V | | +------------+---------------------------+ | | +------------+ Prefix | Suffix +---+ | | | +------------+---------------------------+ | | | | <------------- message -------------> | | | | +-------+---------------------------+ | | | | +-------+ Clear | Opaque +--(+) | | | | +-------+---------------------------+ | | | | | +---------------------------+ | | | | | +--------+ Ciphertext |<--+ | | | | | +---------------------------+ | | | V V | | | +-----------------+ | | +--->| Integrity | +-----------+ | +-------->| Protection +--->| Auth. Tag | +------------->| Generator | +-----------+ +-----------------+
References:
Version: $Revision: 1.5 $
Field Summary | |
---|---|
static String | CIPHER Property name of the keystream underlying cipher. |
static String | CONFIDENTIALITY Property name of the confidentiality protection flag. |
static String | INDEX_LENGTH Property name of a UST index_length. |
static String | INTEGRITY Property name of the integrity protection flag. |
static String | KEYSTREAM Property name of the keystream generator type to use. |
static String | KEY_MATERIAL Property name of the UST user-supplied key material. |
static String | TAG_LENGTH Property name of the authentication tag length in bytes. |
Method Summary | |
---|---|
byte[] | beginMessage() Signals the start of a new message to process with this |
void | beginMessageWithIndex(int ndx) Signals the start of a new message to process with this |
void | beginMessageWithIndex(BigInteger ndx) Signals the start of a new message to process with this |
void | doClear(byte[] in, int offset, int length) Process the Clear part of the message. |
void | doOpaque(byte[] in, int inOffset, int length, byte[] out, int outOffset) Process the Opaque part of the message. |
byte[] | endMessage() Signals the end of the message transformation. |
void | init(Map attributes) Initialise this instance with the designated set of attributes. The possible attributes for a
|
void | reset() Reset this instance and prepare for processing a new message. |
boolean | selfTest() |
Signals the start of a new message to process with this UST
.
Returns: a byte array containing the representation of the Index used for this message.
Throws: LimitReachedException if the value of the Index has
reached its allowed upper bound. To use this UST
instance
a new initialisation (with a new user-supplied key material) should occur. InvalidKeyException if the underlying cipher, used in either or
both the Integrity Protection and Confidentiality Protection functions
has detected an exception.
Signals the start of a new message to process with this UST
with a designated
Parameters: ndx the Index to use with the new message.
Throws: LimitReachedException if the value of the Index has
reached its allowed upper bound. To use this UST
instance
a new initialisation (with a new user-supplied key material) should occur. InvalidKeyException if the underlying cipher, used in either or
both the Integrity Protection and Confidentiality Protection functions
has detected an exception.
Signals the start of a new message to process with this UST
with a designated
Parameters: ndx the Index to use with the new message.
Throws: LimitReachedException if the value of the Index has
reached its allowed upper bound. To use this UST
instance
a new initialisation (with a new user-supplied key material) should occur. InvalidKeyException if the underlying cipher, used in either or
both the Integrity Protection and Confidentiality Protection functions
has detected an exception.
Process the Clear part of the message.
Parameters: in a byte array containing the Clear part of the message. offset the starting index in in
where the Clear
message bytes should be considered. length the count of bytes in in
, starting from
offset
to consider.
Throws: IllegalStateException if no start-of-message method has been invoked earlier or the Integrity Protection service has not been activated.
Process the Opaque part of the message.
Parameters: in a byte array containing the Clear part of the message. inOffset the starting index in in
where the
Opaque message bytes should be considered. length the count of bytes in in
, starting from
inOffset
to consider. out the byte array where the enciphered opaque message should be
stored. outOffset the starting offset in out
where the
enciphered bytes should be stored.
Throws: IllegalStateException if no start-of-message method has been invoked earlier. LimitReachedException if one or both of the underlying keystream generators have reached their limit.
Signals the end of the message transformation.
Returns: the authentication tag bytes, if and when the Integrity Protection service was specified; otherwise a 0-long byte array is returned.
Throws: IllegalStateException if no start-of-message method has been invoked earlier.
Initialise this instance with the designated set of attributes.
The possible attributes for a UST
are:
ICMGenerator
.
Parameters: attributes the map of attributes to use for this instance.
Reset this instance and prepare for processing a new message.