Class CryptoEngine

java.lang.Object
com.codename1.security.CryptoEngine
Direct Known Subclasses:
NativeCryptoEngine, PortCryptoEngine
public class CryptoEngine extends Object

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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    BATCH_ED25519
    verifyBatch(int, byte[][], byte[][], byte[][], byte[]) of Ed25519 signatures.
    static final int
    BATCH_SCHNORR
    verifyBatch(int, byte[][], byte[][], byte[][], byte[]) of BIP-340 Schnorr signatures.
    static final int
    BATCH_SECP256K1
    verifyBatch(int, byte[][], byte[][], byte[][], byte[]) of ECDSA over secp256k1.

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    deliver(Runnable result)
    Hands the result of an asynchronous CryptoBatch call to the application.
    byte[]
    ed25519PublicKey(byte[] privateKey)
    The Ed25519 public key of a 32-byte seed, or null to derive it in Java.
    byte[]
    ed25519Sign(byte[] privateKey, byte[] publicKey, byte[] message)
    An Ed25519 signature ([Ed25519#sign(byte[], byte[], byte[])]), or null to sign in Java.
    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.
    static CryptoEngine
    get()
    The installed engine, never null.
    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(int) words at at of rec.
    protected static int
    gpuRecordWords(int algorithm)
    The size in 32-bit words of one GPU record of BATCH_SECP256K1, BATCH_SCHNORR or BATCH_ED25519.
    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.
    boolean
    hashPacked(String algorithm, byte[] inputs, int inputLength, int count, byte[] digests)
    hashBatch(String, byte[][]) over packed arrays: digest i is of inputLength bytes of inputs from inputLength * i, written at 32 * i of digests.
    byte[]
    hmac(String hashAlgorithm, byte[] key, byte[] data)
    HMAC over hashAlgorithm (Hash.SHA256 or Hash.SHA512), or null to compute it in Java.
    static void
    install(CryptoEngine engine)
    Installs an engine, or restores the portable one when given null.
    byte[]
    keccak256(byte[] data)
    Keccak-256 of data, or null to hash in Java.
    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.
    static byte[]
    random(int length)
    Fresh secure random bytes from the installed engine.
    boolean
    randomBytes(byte[] out)
    Fills out with bytes from the platform's CSPRNG, answering false when this engine has no source.
    byte[]
    ripemd160(byte[] data, int offset, int length)
    RIPEMD-160 of a range of data, or null to hash in Java.
    void
    runInBackground(Runnable task)
    Runs a CryptoBatch asynchronous call off the calling thread.
    byte[]
    schnorrPublicKey(byte[] privateKey)
    A BIP-340 x-only public key, or null to derive it in Java.
    byte[]
    schnorrSign(byte[] message, byte[] privateKey, byte[] auxRand)
    A BIP-340 signature; auxRand is 32 bytes or null for zeros.
    int
    schnorrVerify(byte[] message, byte[] signature, byte[] publicKey)
    A BIP-340 verification: 1 valid, 0 invalid, or -1 to verify in Java.
    byte[]
    secpPrivateKeyTweakAdd(byte[] privateKey, byte[] tweak)
    (privateKey + tweak) mod n, or null to compute it in Java.
    byte[]
    secpPublicKey(byte[] privateKey, boolean compressed)
    A secp256k1 public key (Secp256k1.publicKey(byte[], boolean)), or null to derive it in Java.
    byte[]
    secpPublicKeyTweakAdd(byte[] publicKey, byte[] tweak, boolean compressed)
    publicKey + tweak * G, or null to compute it in Java.
    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).
    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.
    int
    secpVerify(byte[] hash, byte[] compactSignature, byte[] publicKey)
    An ECDSA verification of r || s (64 bytes): 1 valid, 0 invalid, or
    byte[]
    sha256(byte[] data, int offset, int length)
    SHA-256 of length bytes of data from offset, or null to hash in Java.
    byte[]
    sha512(byte[] data, int offset, int length)
    SHA-512 of a range of data, or null to hash in Java.
    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).
    void
    verifyPacked(int algorithm, byte[] messages, int messageLength, byte[] signatures, byte[] keys, int keyLength, byte[] results, int count)
    verifyBatch(int, byte[][], byte[][], byte[][], byte[]) 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.

    Methods inherited from class Object

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

  • Field Details

  • 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(byte[], boolean)), 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: 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: 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(int, byte[], int, int, byte[], int, byte[], int, int, int[], int).

      Parameters
      • algorithm: 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(int) words at at of rec. The kernel's answer for that record is the verification's answer.

      Parameters

      • algorithm: one of the batch algorithms

      • messages: the packed messages, the entry's at msgOff, msgLen bytes (32 for ECDSA)

      • signatures: the packed signatures, the entry's 64 bytes at sigOff

      • keys: the packed public keys, the entry's at keyOff, keyLen bytes

      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(int, byte[][], byte[][], byte[][], byte[]) 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(int, byte[][], byte[][], byte[][], byte[]), 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(String, byte[][]) 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.