org.xbill.DNS

Class TSIG

java.lang.Object

org.xbill.DNS.TSIG

public class TSIG
extends java.lang.Object

Transaction signature handling. This class generates and verifies TSIG records on messages, which provide transaction security.

Author:

Brian Wellington

See Also:

TSIGRecord

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TSIG.StreamVerifier

Field Summary

Fields

Modifier and Type	Field and Description
static short	FUDGE The default fudge value for outgoing packets.
static Name	HMAC The domain name representing the HMAC-MD5 algorithm (deprecated).
static Name	HMAC_MD5 The domain name representing the HMAC-MD5 algorithm.
static Name	HMAC_SHA1 The domain name representing the HMAC-SHA1 algorithm.
static Name	HMAC_SHA224 The domain name representing the HMAC-SHA224 algorithm.
static Name	HMAC_SHA256 The domain name representing the HMAC-SHA256 algorithm.
static Name	HMAC_SHA384 The domain name representing the HMAC-SHA384 algorithm.
static Name	HMAC_SHA512 The domain name representing the HMAC-SHA512 algorithm.

Constructor Summary

Constructors

Constructor and Description
TSIG(javax.crypto.Mac mac, Name name) Creates a new TSIG key from a pre-initialized Mac instance.
TSIG(Name name, byte[] key) Creates a new TSIG key with the hmac-md5 algorithm, which can be used to sign or verify a message.
TSIG(Name algorithm, Name name, byte[] keyBytes) Creates a new TSIG key, which can be used to sign or verify a message.
TSIG(Name algorithm, Name name, javax.crypto.SecretKey key) Creates a new TSIG key, which can be used to sign or verify a message.
TSIG(Name algorithm, java.lang.String name, java.lang.String key) Creates a new TSIG object, which can be used to sign or verify a message.
TSIG(java.lang.String name, java.lang.String key) Creates a new TSIG object with the hmac-md5 algorithm, which can be used to sign or verify a message.
TSIG(java.lang.String algorithm, java.lang.String name, java.lang.String key) Creates a new TSIG object, which can be used to sign or verify a message.

Method Summary

Modifier and Type	Method and Description
static Name	algorithmToName(java.lang.String alg)
void	apply(Message m, int error, TSIGRecord old) Generates a TSIG record with a specific error for a message and adds it to the message.
void	apply(Message m, TSIGRecord old) Generates a TSIG record for a message and adds it to the message
void	applyStream(Message m, TSIGRecord old, boolean first) Generates a TSIG record for a message and adds it to the message
static TSIG	fromString(java.lang.String str) Creates a new TSIG object, which can be used to sign or verify a message.
TSIGRecord	generate(Message m, byte[] b, int error, TSIGRecord old) Generates a TSIG record with a specific error for a message that has been rendered.
static java.lang.String	nameToAlgorithm(Name name)
int	recordLength() Returns the maximum length of a TSIG record generated by this key.
byte	verify(Message m, byte[] b, int length, TSIGRecord old) Verifies a TSIG record on an incoming message.
int	verify(Message m, byte[] b, TSIGRecord old) Verifies a TSIG record on an incoming message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HMAC_MD5

public static final Name HMAC_MD5

The domain name representing the HMAC-MD5 algorithm.

HMAC

public static final Name HMAC

The domain name representing the HMAC-MD5 algorithm (deprecated).

HMAC_SHA1

public static final Name HMAC_SHA1

The domain name representing the HMAC-SHA1 algorithm.

HMAC_SHA224

public static final Name HMAC_SHA224

The domain name representing the HMAC-SHA224 algorithm. Note that SHA224 is not supported by Java out-of-the-box, this requires use of a third party provider like BouncyCastle.org.

HMAC_SHA256

public static final Name HMAC_SHA256

The domain name representing the HMAC-SHA256 algorithm.

HMAC_SHA384

public static final Name HMAC_SHA384

The domain name representing the HMAC-SHA384 algorithm.

HMAC_SHA512

public static final Name HMAC_SHA512

The domain name representing the HMAC-SHA512 algorithm.

FUDGE

public static final short FUDGE

The default fudge value for outgoing packets. Can be overriden by the tsigfudge option.

See Also:

Constant Field Values

Constructor Detail

TSIG

public TSIG(Name algorithm,
            Name name,
            byte[] keyBytes)

Creates a new TSIG key, which can be used to sign or verify a message.

Parameters:

algorithm - The algorithm of the shared key.

name - The name of the shared key.

key - The shared key's data.

TSIG

public TSIG(Name algorithm,
            Name name,
            javax.crypto.SecretKey key)

Creates a new TSIG key, which can be used to sign or verify a message.

Parameters:

algorithm - The algorithm of the shared key.

name - The name of the shared key.

key - The shared key.

TSIG

public TSIG(javax.crypto.Mac mac,
            Name name)

Creates a new TSIG key from a pre-initialized Mac instance. This assumes that init() has already been called on the mac to set up the key.

Parameters:

mac - The JCE HMAC object

Name - The name of the key

TSIG

public TSIG(Name name,
            byte[] key)

Creates a new TSIG key with the hmac-md5 algorithm, which can be used to sign or verify a message.

Parameters:

name - The name of the shared key.

key - The shared key's data.

TSIG

public TSIG(Name algorithm,
            java.lang.String name,
            java.lang.String key)

Creates a new TSIG object, which can be used to sign or verify a message.

Parameters:

name - The name of the shared key.

key - The shared key's data represented as a base64 encoded string.

Throws:

java.lang.IllegalArgumentException - The key name is an invalid name

java.lang.IllegalArgumentException - The key data is improperly encoded

TSIG

public TSIG(java.lang.String algorithm,
            java.lang.String name,
            java.lang.String key)

Creates a new TSIG object, which can be used to sign or verify a message.

Parameters:

name - The name of the shared key.

algorithm - The algorithm of the shared key. The legal values are "hmac-md5", "hmac-sha1", "hmac-sha224", "hmac-sha256", "hmac-sha384", and "hmac-sha512".

key - The shared key's data represented as a base64 encoded string.

Throws:

java.lang.IllegalArgumentException - The key name is an invalid name

java.lang.IllegalArgumentException - The key data is improperly encoded

TSIG

public TSIG(java.lang.String name,
            java.lang.String key)

Creates a new TSIG object with the hmac-md5 algorithm, which can be used to sign or verify a message.

Parameters:

name - The name of the shared key

key - The shared key's data, represented as a base64 encoded string.

Throws:

java.lang.IllegalArgumentException - The key name is an invalid name

java.lang.IllegalArgumentException - The key data is improperly encoded

Method Detail

algorithmToName

public static Name algorithmToName(java.lang.String alg)

nameToAlgorithm

public static java.lang.String nameToAlgorithm(Name name)

fromString

public static TSIG fromString(java.lang.String str)

Creates a new TSIG object, which can be used to sign or verify a message.

Parameters:

str - The TSIG key, in the form name:secret, name/secret, alg:name:secret, or alg/name/secret. If an algorithm is specified, it must be "hmac-md5", "hmac-sha1", or "hmac-sha256".

Throws:

java.lang.IllegalArgumentException - The string does not contain both a name and secret.

java.lang.IllegalArgumentException - The key name is an invalid name

java.lang.IllegalArgumentException - The key data is improperly encoded

generate

public TSIGRecord generate(Message m,
                           byte[] b,
                           int error,
                           TSIGRecord old)

Generates a TSIG record with a specific error for a message that has been rendered.

Parameters:

m - The message

b - The rendered message

error - The error

old - If this message is a response, the TSIG from the request

Returns:

The TSIG record to be added to the message

apply

public void apply(Message m,
                  int error,
                  TSIGRecord old)

Generates a TSIG record with a specific error for a message and adds it to the message.

Parameters:

m - The message

error - The error

old - If this message is a response, the TSIG from the request

apply

public void apply(Message m,
                  TSIGRecord old)

Generates a TSIG record for a message and adds it to the message

Parameters:

m - The message

old - If this message is a response, the TSIG from the request

applyStream

public void applyStream(Message m,
                        TSIGRecord old,
                        boolean first)

Generates a TSIG record for a message and adds it to the message

Parameters:

m - The message

old - If this message is a response, the TSIG from the request

verify

public byte verify(Message m,
                   byte[] b,
                   int length,
                   TSIGRecord old)

Verifies a TSIG record on an incoming message. Since this is only called in the context where a TSIG is expected to be present, it is an error if one is not present. After calling this routine, Message.isVerified() may be called on this message.

Parameters:

m - The message

b - An array containing the message in unparsed form. This is necessary since TSIG signs the message in wire format, and we can't recreate the exact wire format (with the same name compression).

length - The length of the message in the array.

old - If this message is a response, the TSIG from the request

Returns:

The result of the verification (as an Rcode)

See Also:

Rcode

verify

public int verify(Message m,
                  byte[] b,
                  TSIGRecord old)

Verifies a TSIG record on an incoming message. Since this is only called in the context where a TSIG is expected to be present, it is an error if one is not present. After calling this routine, Message.isVerified() may be called on this message.

Parameters:

m - The message

b - The message in unparsed form. This is necessary since TSIG signs the message in wire format, and we can't recreate the exact wire format (with the same name compression).

old - If this message is a response, the TSIG from the request

Returns:

The result of the verification (as an Rcode)

See Also:

Rcode

recordLength

public int recordLength()

Returns the maximum length of a TSIG record generated by this key.

See Also:

TSIGRecord