com.subgraph.orchid.crypto

Class TorTapKeyAgreement

java.lang.Object

com.subgraph.orchid.crypto.TorTapKeyAgreement

All Implemented Interfaces:

TorKeyAgreement

public class TorTapKeyAgreement
extends Object
implements TorKeyAgreement

The TorKeyAgreement class implements the diffie-hellman key agreement protocol using the parameters specified in the main Tor specification (tor-spec.txt). An instance of this class can only be used to perform a single key agreement operation. After instantiating the class, a user calls getPublicValue() or getPublicKeyBytes() to retrieve the public value to transmit to the peer in the key agreement operation. After receiving a public value from the peer, this value should be converted into a BigInteger and isValidPublicValue(BigInteger) should be called to verify that the peer has sent a safe and legal public value. If isValidPublicValue(BigInteger) returns true, the peer public value is valid and getSharedSecret(BigInteger) can be called to complete the key agreement protocol and return the shared secret value.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DH_LEN
static int	DH_SEC_LEN

Constructor Summary

Constructors

Constructor and Description
TorTapKeyAgreement()
TorTapKeyAgreement(TorPublicKey onionKey) Create a new TorKeyAgreement instance which can be used to perform a single key agreement operation.

Method Summary

Modifier and Type	Method and Description
byte[]	createOnionSkin()
boolean	deriveKeysFromDHPublicAndHash(BigInteger peerPublic, byte[] keyHash, byte[] keyMaterialOut, byte[] verifyHashOut)
boolean	deriveKeysFromHandshakeResponse(byte[] handshakeResponse, byte[] keyMaterialOut, byte[] verifyHashOut)
byte[]	getPublicKeyBytes() Return the generated public value for this key agreement operation as an array with the value encoded in big-endian byte order.
BigInteger	getPublicValue() Return the generated public value for this key agreement operation as a BigInteger.
byte[]	getSharedSecret(BigInteger otherPublic) Complete the key agreement protocol with the peer public value otherPublic and return the calculated shared secret.
static boolean	isValidPublicValue(BigInteger publicValue) Return true if the specified value is a legal public value rather than a dangerous degenerate or confined subgroup value.

Methods inherited from class java.lang.Object

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

Field Detail

DH_LEN

public static final int DH_LEN

See Also:

Constant Field Values

DH_SEC_LEN

public static final int DH_SEC_LEN

See Also:

Constant Field Values

Constructor Detail

TorTapKeyAgreement

public TorTapKeyAgreement(TorPublicKey onionKey)

Create a new TorKeyAgreement instance which can be used to perform a single key agreement operation. A new set of ephemeral Diffie-Hellman parameters are generated when this class is instantiated.

TorTapKeyAgreement

public TorTapKeyAgreement()

Method Detail

getPublicValue

public BigInteger getPublicValue()

Return the generated public value for this key agreement operation as a BigInteger.

Returns:

The diffie-hellman public value as a BigInteger.

getPublicKeyBytes

public byte[] getPublicKeyBytes()

Return the generated public value for this key agreement operation as an array with the value encoded in big-endian byte order.

Returns:

A byte array containing the encoded public value for this key agreement operation.

isValidPublicValue

public static boolean isValidPublicValue(BigInteger publicValue)

Return true if the specified value is a legal public value rather than a dangerous degenerate or confined subgroup value. tor-spec 5.2 Before computing g^xy, both client and server MUST verify that the received g^x or g^y value is not degenerate; that is, it must be strictly greater than 1 and strictly less than p-1 where p is the DH modulus. Implementations MUST NOT complete a handshake with degenerate keys.

getSharedSecret

public byte[] getSharedSecret(BigInteger otherPublic)

Complete the key agreement protocol with the peer public value otherPublic and return the calculated shared secret.

Parameters:

otherPublic - The peer public value.

Returns:

The shared secret value produced by the protocol.

createOnionSkin

public byte[] createOnionSkin()

Specified by:

createOnionSkin in interface TorKeyAgreement

deriveKeysFromHandshakeResponse

public boolean deriveKeysFromHandshakeResponse(byte[] handshakeResponse,
                                               byte[] keyMaterialOut,
                                               byte[] verifyHashOut)

Specified by:

deriveKeysFromHandshakeResponse in interface TorKeyAgreement

deriveKeysFromDHPublicAndHash

public boolean deriveKeysFromDHPublicAndHash(BigInteger peerPublic,
                                             byte[] keyHash,
                                             byte[] keyMaterialOut,
                                             byte[] verifyHashOut)