Client and backend. This class is shared: the same code is compiled into your app and into your server, so everything on this page works in both.

public class CryptoEngine

  1. Object
  2. CryptoEngine

Known subtypesNativeCryptoEngine, PortCryptoEngine

The seam through which a platform supplies faster implementations of the compute-heavy cryptography in this package. Every method answers null (or false where noted) when the engine has no faster path for that input, and the caller then runs the portable Java implementation, which produces identical bytes. A missing kernel therefore degrades to slower, never to different.

Client ports install one when Codename One initializes; the backend installs its own. Application code has no reason to call this class: use Pbkdf2, Secp256k1 and Hash, which consult the installed engine.

An engine must be thread safe and must not keep or log the key material it is handed.

Fields

public static final int BATCH_SECP256K1 = 1verifyBatch of ECDSA over secp256k1.
public static final int BATCH_SCHNORR = 2verifyBatch of BIP-340 Schnorr signatures.
public static final int BATCH_ED25519 = 3verifyBatch of Ed25519 signatures.

Constructors

protected CryptoEngine()Creates an engine that accelerates nothing; subclasses override what they accelerate.

Methods

public static CryptoEngine get()The installed engine, never null.
public static void install(CryptoEngine engine)Installs an engine, or restores the portable one when given null.
public boolean randomBytes(byte[] out)Fills out with bytes from the platform’s CSPRNG, answering false when this engine has no source.
public static byte[] random(int length)Fresh secure random bytes from the installed engine.
public byte[] pbkdf2(String hashAlgorithm, byte[] password, byte[] salt, int iterations, int length)PBKDF2 (RFC 8018) with HMAC over hashAlgorithm (Hash.SHA256 or Hash.SHA512), or null to use the Java derivation.
public byte[] ed25519PublicKey(byte[] privateKey)The Ed25519 public key of a 32-byte seed, or null to derive it in Java.
public byte[] ed25519Sign(byte[] privateKey, byte[] publicKey, byte[] message)An Ed25519 signature ([Ed25519#sign(byte[], byte[], byte[])]), or null to sign in Java.
public int ed25519Verify(byte[] message, byte[] signature, byte[] publicKey)An Ed25519 verification: 1 for a valid signature, 0 for an invalid one, or -1 to verify in Java.
public byte[] secpPublicKey(byte[] privateKey, boolean compressed)A secp256k1 public key (Secp256k1.publicKey), or null to derive it in Java.
public byte[] secpSign(byte[] hash, byte[] privateKey)An ECDSA signature over a 32-byte hash as r || s || recoveryId (65 bytes, RFC 6979 nonce, low S), or null to sign in Java.
public int secpVerify(byte[] hash, byte[] compactSignature, byte[] publicKey)An ECDSA verification of r || s (64 bytes): 1 valid, 0 invalid, or -1 to verify in Java.
public byte[] secpRecover(byte[] hash, byte[] compactSignature, int recoveryId, boolean compressed)The public key recovered from r || s and a recovery id, or null to recover in Java (which also decides that no key exists).
public byte[] secpPrivateKeyTweakAdd(byte[] privateKey, byte[] tweak)(privateKey + tweak) mod n, or null to compute it in Java.
public byte[] secpPublicKeyTweakAdd(byte[] publicKey, byte[] tweak, boolean compressed)publicKey + tweak * G, or null to compute it in Java.
public byte[] schnorrPublicKey(byte[] privateKey)A BIP-340 x-only public key, or null to derive it in Java.
public byte[] schnorrSign(byte[] message, byte[] privateKey, byte[] auxRand)A BIP-340 signature; auxRand is 32 bytes or null for zeros.
public int schnorrVerify(byte[] message, byte[] signature, byte[] publicKey)A BIP-340 verification: 1 valid, 0 invalid, or -1 to verify in Java.
public byte[] keccak256(byte[] data)Keccak-256 of data, or null to hash in Java.
public void verifyBatch(int algorithm, byte[][] messages, byte[][] signatures, byte[][] publicKeys, byte[] results)Verifies a batch of signatures of one algorithm (BATCH_SECP256K1, BATCH_SCHNORR, BATCH_ED25519).
public void runInBackground(Runnable task)Runs a CryptoBatch asynchronous call off the calling thread.
public void deliver(Runnable result)Hands the result of an asynchronous CryptoBatch call to the application.
protected static int gpuRecordWords(int algorithm)The size in 32-bit words of one GPU record of BATCH_SECP256K1, BATCH_SCHNORR or BATCH_ED25519.
protected static int gpuRecord(int algorithm, byte[] messages, int msgOff, int msgLen, byte[] signatures, int sigOff, byte[] keys, int keyOff, int keyLen, int[] rec, int at)Prepares one entry of a packed batch for the GPU kernels the native ports run (the same kernels as WGSL, in the JavaScript port’s js/cn1_crypto_gpu.js): everything a verification does before its scalar multiplication, parsing, decompression, the challenge hash and the inverse, leaving a record of gpuRecordWords words at at of rec.
public void verifyPacked(int algorithm, byte[] messages, int messageLength, byte[] signatures, byte[] keys, int keyLength, byte[] results, int count)verifyBatch over packed arrays: entry i is messageLength bytes of messages from messageLength * i, 64 bytes of signatures from 64 * i and keyLength bytes of keys from keyLength * i.
public boolean hashPacked(String algorithm, byte[] inputs, int inputLength, int count, byte[] digests)hashBatch over packed arrays: digest i is of inputLength bytes of inputs from inputLength * i, written at 32 * i of digests.
public byte[][] hashBatch(String algorithm, byte[][] inputs)The digests of inputs under Hash.SHA256 or Hash.KECCAK256, a null for each null input, or null to hash them in Java.
public byte[] sha256(byte[] data, int offset, int length)SHA-256 of length bytes of data from offset, or null to hash in Java.
public byte[] sha512(byte[] data, int offset, int length)SHA-512 of a range of data, or null to hash in Java.
public byte[] ripemd160(byte[] data, int offset, int length)RIPEMD-160 of a range of data, or null to hash in Java.
public byte[] hmac(String hashAlgorithm, byte[] key, byte[] data)HMAC over hashAlgorithm (Hash.SHA256 or Hash.SHA512), or null to compute it in Java.

Inherited methods

From Object

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

Field details

BATCH_SECP256K1

public static final int BATCH_SECP256K1 = 1
verifyBatch of ECDSA over secp256k1.

BATCH_SCHNORR

public static final int BATCH_SCHNORR = 2
verifyBatch of BIP-340 Schnorr signatures.

BATCH_ED25519

public static final int BATCH_ED25519 = 3
verifyBatch of Ed25519 signatures.

Constructor details

CryptoEngine

protected CryptoEngine()
Creates an engine that accelerates nothing; subclasses override what they accelerate.

Method details

get

public static CryptoEngine get()
The installed engine, never null.

install

public static void install(CryptoEngine engine)
Installs an engine, or restores the portable one when given null. Called by a port during initialization.

randomBytes

public boolean randomBytes(byte[] out)
Fills out with bytes from the platform’s CSPRNG, answering false when this engine has no source. Every installed engine has one: the client’s draws on the port, the backend’s on the server runtime.

random

public static byte[] random(int length)
Fresh secure random bytes from the installed engine. Shared code, which cannot reach the client’s SecureRandom, draws its nonces and entropy here.

Throws

CryptoException
when no engine with a random source is installed

pbkdf2

public byte[] pbkdf2(String hashAlgorithm, byte[] password, byte[] salt, int iterations, int length)
PBKDF2 (RFC 8018) with HMAC over hashAlgorithm (Hash.SHA256 or Hash.SHA512), or null to use the Java derivation. The arguments are already validated.

ed25519PublicKey

public byte[] ed25519PublicKey(byte[] privateKey)
The Ed25519 public key of a 32-byte seed, or null to derive it in Java.

ed25519Sign

public byte[] ed25519Sign(byte[] privateKey, byte[] publicKey, byte[] message)
An Ed25519 signature ([Ed25519#sign(byte[], byte[], byte[])]), or null to sign in Java. The arguments are already validated.

ed25519Verify

public int ed25519Verify(byte[] message, byte[] signature, byte[] publicKey)
An Ed25519 verification: 1 for a valid signature, 0 for an invalid one, or -1 to verify in Java.

secpPublicKey

public byte[] secpPublicKey(byte[] privateKey, boolean compressed)
A secp256k1 public key (Secp256k1.publicKey), or null to derive it in Java. The private key has not been range checked: answer null for one that is out of range and Java reports the error.

secpSign

public byte[] secpSign(byte[] hash, byte[] privateKey)
An ECDSA signature over a 32-byte hash as r || s || recoveryId (65 bytes, RFC 6979 nonce, low S), or null to sign in Java.

secpVerify

public int secpVerify(byte[] hash, byte[] compactSignature, byte[] publicKey)
An ECDSA verification of r || s (64 bytes): 1 valid, 0 invalid, or -1 to verify in Java.

secpRecover

public byte[] secpRecover(byte[] hash, byte[] compactSignature, int recoveryId, boolean compressed)
The public key recovered from r || s and a recovery id, or null to recover in Java (which also decides that no key exists).

secpPrivateKeyTweakAdd

public byte[] secpPrivateKeyTweakAdd(byte[] privateKey, byte[] tweak)
(privateKey + tweak) mod n, or null to compute it in Java.

secpPublicKeyTweakAdd

public byte[] secpPublicKeyTweakAdd(byte[] publicKey, byte[] tweak, boolean compressed)
publicKey + tweak * G, or null to compute it in Java.

schnorrPublicKey

public byte[] schnorrPublicKey(byte[] privateKey)
A BIP-340 x-only public key, or null to derive it in Java.

schnorrSign

public byte[] schnorrSign(byte[] message, byte[] privateKey, byte[] auxRand)
A BIP-340 signature; auxRand is 32 bytes or null for zeros. Answers null to sign in Java.

schnorrVerify

public int schnorrVerify(byte[] message, byte[] signature, byte[] publicKey)
A BIP-340 verification: 1 valid, 0 invalid, or -1 to verify in Java. The key is 32 bytes and the signature 64.

keccak256

public byte[] keccak256(byte[] data)
Keccak-256 of data, or null to hash in Java.

verifyBatch

public void verifyBatch(int algorithm, byte[][] messages, byte[][] signatures, byte[][] publicKeys, byte[] results)
Verifies a batch of signatures of one algorithm (BATCH_SECP256K1, BATCH_SCHNORR, BATCH_ED25519). Only the entries whose result byte is 2 are to be verified: the engine writes 1 (valid), 0 (invalid) or 0xff (verify this one in Java) over them, and leaves any it does not reach at 2, which the caller also verifies in Java. Those entries have non-null arrays; signatures are 64 bytes, messages 32 for ECDSA, keys 32 except for ECDSA’s SEC1 keys.

runInBackground

public void runInBackground(Runnable task)
Runs a CryptoBatch asynchronous call off the calling thread. The default starts a thread for it; an engine whose platform has a better place for long work overrides this. The task runs the same batch the synchronous form does, start to finish.

Parameters

task Runnable
the whole batch, including the delivery of its result

deliver

public void deliver(Runnable result)
Hands the result of an asynchronous CryptoBatch call to the application. The default runs it on the thread that computed the batch, which is what a server wants; the client’s engine runs it on the EDT, so a callback can touch the UI.

Parameters

result Runnable
the call to the application’s callback

gpuRecordWords

protected static int gpuRecordWords(int algorithm)
The size in 32-bit words of one GPU record of BATCH_SECP256K1, BATCH_SCHNORR or BATCH_ED25519. For an engine that runs the multiplications of a batch on a GPU: see gpuRecord.

Parameters

algorithm int
one of the batch algorithms

Returns

49 for ECDSA, 40 for the other two

gpuRecord

protected static int gpuRecord(int algorithm, byte[] messages, int msgOff, int msgLen, byte[] signatures, int sigOff, byte[] keys, int keyOff, int keyLen, int[] rec, int at)
Prepares one entry of a packed batch for the GPU kernels the native ports run (the same kernels as WGSL, in the JavaScript port’s js/cn1_crypto_gpu.js): everything a verification does before its scalar multiplication, parsing, decompression, the challenge hash and the inverse, leaving a record of gpuRecordWords words at at of rec. The kernel’s answer for that record is the verification’s answer.

Parameters

algorithm int
one of the batch algorithms
messages byte[]
the packed messages, the entry’s at msgOff, msgLen bytes (32 for ECDSA)
msgOff int
Not documented.
msgLen int
Not documented.
signatures byte[]
the packed signatures, the entry’s 64 bytes at sigOff
sigOff int
Not documented.
keys byte[]
the packed public keys, the entry’s at keyOff, keyLen bytes
keyOff int
Not documented.
keyLen int
Not documented.
rec int[]
Not documented.
at int
Not documented.

Returns

0 when the entry is invalid without a multiplication, 2 when the record is the kernel’s to decide

verifyPacked

public void verifyPacked(int algorithm, byte[] messages, int messageLength, byte[] signatures, byte[] keys, int keyLength, byte[] results, int count)
verifyBatch over packed arrays: entry i is messageLength bytes of messages from messageLength * i, 64 bytes of signatures from 64 * i and keyLength bytes of keys from keyLength * i. The same result bytes as verifyBatch, and every range is already validated. An engine that can should read the arrays in place.

hashPacked

public boolean hashPacked(String algorithm, byte[] inputs, int inputLength, int count, byte[] digests)
hashBatch over packed arrays: digest i is of inputLength bytes of inputs from inputLength * i, written at 32 * i of digests. Answers false to hash in Java. The ranges are already validated.

hashBatch

public byte[][] hashBatch(String algorithm, byte[][] inputs)
The digests of inputs under Hash.SHA256 or Hash.KECCAK256, a null for each null input, or null to hash them in Java.

sha256

public byte[] sha256(byte[] data, int offset, int length)
SHA-256 of length bytes of data from offset, or null to hash in Java. The range is already validated.

sha512

public byte[] sha512(byte[] data, int offset, int length)
SHA-512 of a range of data, or null to hash in Java.

ripemd160

public byte[] ripemd160(byte[] data, int offset, int length)
RIPEMD-160 of a range of data, or null to hash in Java.

hmac

public byte[] hmac(String hashAlgorithm, byte[] key, byte[] data)
HMAC over hashAlgorithm (Hash.SHA256 or Hash.SHA512), or null to compute it in Java. Neither array is null.