Class EstablishedSas

java.lang.Object

io.github.fherbreteau.vodozemac.NativeHandle

io.github.fherbreteau.vodozemac.sas.EstablishedSas

All Implemented Interfaces:

AutoCloseable

public final class EstablishedSas
extends NativeHandle

User-friendly key verification using short authentication strings (SAS) with an established shared secret.

An EstablishedSas is obtained by calling Sas.diffieHellman(String) with the other party's public key. Once established, it can be used to:

• Generate SasBytes (emoji indices, decimal numbers, raw bytes) for visual key verification via bytes(String)
• Generate and verify MACs to cryptographically confirm the shared secret via calculateMac(String, String) and verifyMac(String, String, String)

This class implements AutoCloseable and should be used in a try-with-resources block to ensure native resources are properly released.

Author:

François HERBRETEAU

Method Summary

Modifier and Type	Method	Description
SasBytes	bytes(String info)	Generates SasBytes using HKDF with the shared secret as the input key material.
byte[]	bytesRaw(String info, int count)	Generates the given number of bytes using HKDF with the shared secret as the input key material.
String	calculateMac(String input, String info)	Calculates a MAC for the given input using the info string as additional data.
String	calculateMacInvalidBase64(String input, String info)	Calculates a MAC for the given input using the info string as additional data, returning the MAC as an invalid base64-encoded string.
String	ourPublicKey()	Returns the public key that was created by us, that was used to establish the shared secret.
String	theirPublicKey()	Returns the public key that was created by the other party, that was used to establish the shared secret.
void	verifyMac(String input, String info, String mac)	Verifies a MAC that was previously created using calculateMac(String, String).

Methods inherited from class NativeHandle

checkNotClosed, close, invalidate, nativePtr

Methods inherited from class Object

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

Method Details

bytes

public SasBytes bytes(String info)

Generates SasBytes using HKDF with the shared secret as the input key material.

The info string should be agreed upon beforehand — both parties need to use the same info string.

Parameters:

info - the info string, agreed upon by both parties

Returns:

a new SasBytes containing emoji indices, decimals, and raw bytes

Throws:

IllegalStateException - if this EstablishedSas has been closed

bytesRaw

public byte[] bytesRaw(String info,
 int count)

Generates the given number of bytes using HKDF with the shared secret as the input key material.

The info string should be agreed upon beforehand — both parties need to use the same info string. The number of bytes that can be generated is limited to 32 * 255 = 8160 bytes.

Parameters:

info - the info string, agreed upon by both parties

count - the number of bytes to generate

Returns:

an array of bytes

Throws:

IllegalStateException - if this EstablishedSas has been closed

SasException - if the requested count exceeds the maximum

calculateMac

public String calculateMac(String input,
 String info)

Calculates a MAC for the given input using the info string as additional data.

This should be used to calculate a MAC of the Ed25519 identity key of an Account.

Parameters:

input - the input string to MAC

info - the info string, agreed upon by both parties

Returns:

the MAC as a base64-encoded string

Throws:

IllegalStateException - if this EstablishedSas has been closed

calculateMacInvalidBase64

public String calculateMacInvalidBase64(String input,
 String info)

Calculates a MAC for the given input using the info string as additional data, returning the MAC as an invalid base64-encoded string.

Warning: This method should never be used unless you require libolm compatibility. Libolm used to incorrectly encode their MAC because the input buffer was reused as the output buffer. This method replicates the buggy behaviour.

Parameters:

input - the input string to MAC

info - the info string, agreed upon by both parties

Returns:

the MAC as an invalid base64-encoded string

Throws:

IllegalStateException - if this EstablishedSas has been closed

verifyMac

public void verifyMac(String input,
 String info,
 String mac)

Verifies a MAC that was previously created using calculateMac(String, String).

Users should calculate a MAC and send it to the other side, they should then verify each other's MAC using this method.

Parameters:

input - the input string that was MAC-ed

info - the info string, agreed upon by both parties

mac - the MAC received from the other user, as a base64-encoded string

Throws:

IllegalStateException - if this EstablishedSas has been closed

SasException - if the MAC verification fails

ourPublicKey

public String ourPublicKey()

Returns the public key that was created by us, that was used to establish the shared secret.

Returns:

the base64-encoded public key

Throws:

IllegalStateException - if this EstablishedSas has been closed

theirPublicKey

public String theirPublicKey()

Returns the public key that was created by the other party, that was used to establish the shared secret.

Returns:

the base64-encoded public key

Throws:

IllegalStateException - if this EstablishedSas has been closed