com.google.crypto.tink.subtle

Class X25519

java.lang.Object

com.google.crypto.tink.subtle.X25519

@Alpha
public final class X25519
extends Object

Defines the ECDH Curve25519 function, also known as the X25519 function.

This implementation is based on curve255-donna.

Warning

Do not use this API or any other APIs including fields and methods marked with the @Alpha annotation. They can be modified in any way, or even removed, at any time. They are in the package, but not for official, production release, but only for testing.

Usage

 Alice:
 byte[] privateKeyA = X25519.generatePrivateKey();
 byte[] publicKeyA = X25519.publicFromPrivate(privateKeyA);
 Bob:
 byte[] privateKeyB = X25519.generatePrivateKey();
 byte[] publicKeyB = X25519.publicFromPrivate(privateKeyB);

 Alice sends publicKeyA to Bob and Bob sends publicKeyB to Alice.
 Alice:
 byte[] sharedSecretA = X25519.computeSharedSecret(privateKeyA, publicKeyB);
 Bob:
 byte[] sharedSecretB = X25519.computeSharedSecret(privateKeyB, publicKeyA);
 such that sharedSecretA == sharedSecretB.
 

Method Summary

Modifier and Type	Method and Description
static byte[]	computeSharedSecret(byte[] privateKey, byte[] peersPublicValue) Returns the 32-byte shared key (i.e., privateKey·peersPublicValue on the curve).
static byte[]	generatePrivateKey() Returns a 32-byte private key for Curve25519.
static byte[]	publicFromPrivate(byte[] privateKey) Returns the 32-byte Diffie-Hellman public value based on the given privateKey (i.e., privateKey·[9] on the curve).

Methods inherited from class java.lang.Object

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

Method Detail

generatePrivateKey

public static byte[] generatePrivateKey()

Returns a 32-byte private key for Curve25519.

Note from BoringSSL: All X25519 implementations should decode scalars correctly (see https://tools.ietf.org/html/rfc7748#section-5). However, if an implementation doesn't then it might interoperate with random keys a fraction of the time because they'll, randomly, happen to be correctly formed.

Thus we do the opposite of the masking here to make sure that our private keys are never correctly masked and so, hopefully, any incorrect implementations are deterministically broken.

This does not affect security because, although we're throwing away entropy, a valid implementation of computeSharedSecret should throw away the exact same bits anyway.

computeSharedSecret

public static byte[] computeSharedSecret(byte[] privateKey,
                                         byte[] peersPublicValue)
                                  throws InvalidKeyException

Returns the 32-byte shared key (i.e., privateKey·peersPublicValue on the curve).

Parameters:

privateKey - 32-byte private key

peersPublicValue - 32-byte public value

Returns:

the 32-byte shared key

Throws:

InvalidKeyException - when privateKey is not 32-byte or peersPublicValue is invalid.

publicFromPrivate

public static byte[] publicFromPrivate(byte[] privateKey)
                                throws InvalidKeyException

Returns the 32-byte Diffie-Hellman public value based on the given privateKey (i.e., privateKey·[9] on the curve).

Parameters:

privateKey - 32-byte private key

Returns:

32-byte Diffie-Hellman public value

Throws:

InvalidKeyException - when the privateKey is not 32 bytes.