Cryptography

This section presents the Foundation Libraries providing cryptographic operations.

CRYPTO

The CRYPTO Foundation Library (ej.api:crypto) provides a standard Java API for cryptographic operations: cipher, digest, MAC, signature, secure random and key/certificate management. It implements a subset of the Java Cryptography Architecture (JCA) standard API and uses the same algorithms names.

Note

Earlier versions of this library were named SECURITY and were provided as part of the NET pack. See SECURITY (deprecated).

Provided APIs

The API is documented in the Javadoc bundled with the CRYPTO module (crypto-<version>-javadoc.jar). It implements a subset of the java.security* and javax.crypto* standard packages, and uses the standard algorithm names referenced above.

Usage

Add the CRYPTO API to the Application project build file:

SDK 6 (build.gradle.kts)SDK 5 (module.ivy)

implementation("ej.api:crypto:<latest>")

The VEE Port must provide the CRYPTO Foundation Library implementation. See CRYPTO in the VEE Porting Guide for the VEE Port integration.

On the Simulator, cryptographic operations are performed by a mock based on the host JRE.

Configuring the External KeyStore

On the Simulator, the CRYPTO mock can load keys and certificates from an external keystore file. Configure it by setting the following mock options, each prefixed with microej.mock.property.:

• ej.crypto.mock.externalks.path: file system path to the keystore file. If unset, an empty keystore is used.

• ej.crypto.mock.externalks.type (optional): keystore format, passed to KeyStore.getInstance(type) (defaults to PKCS12).

• ej.crypto.mock.externalks.pub (optional): set to true to fall back to the certificate’s public key when the alias has no private or secret key (defaults to false).

For example:

microej.mock.property.ej.crypto.mock.externalks.path=/path/to/keystore.p12
microej.mock.property.ej.crypto.mock.externalks.type=PKCS12
microej.mock.property.ej.crypto.mock.externalks.pub=false

See the CRYPTO Mock README for the complete list of options.

Reducing the Memory Footprint

The CRYPTO Foundation Library embeds several adapters (with native back-ends) for the different crypto APIs and algorithms. By default, whenever an Application uses the crypto APIs, all of them are embedded in the binary. To reduce the memory footprint, an Application can exclude the JCE providers and algorithms it does not use.

Exclude a CRYPTO Functionality

The MicroEJ CRYPTO provider exposes the following crypto functionalities, all loaded reflectively and embedded by default. An Application can exclude an unused one by setting the Application Option com.microej.type.<fully.qualified.class.name>.enabled to false (for example in configuration.properties):

• com.microej.crypto.internal.x509.X509Factory

• com.microej.crypto.internal.DefaultKeyStore

• com.microej.crypto.internal.provider.ExternalKeyStoreSpi

• com.microej.crypto.internal.provider.PKIXCertPathValidator

• com.microej.crypto.internal.provider.ECDHKeyAgreement

For example, to exclude the external key store back-end:

com.microej.type.com.microej.crypto.internal.provider.ExternalKeyStoreSpi.enabled=false

Excluding Algorithms

Support for specific algorithms (ciphers, digests, MACs, PBE key factories, etc.) can be disabled by setting the corresponding com.microej.security.* BON constants to false in an Application resources/app.constants.list or common.properties file. The complete list of constants is provided in the CRYPTO Foundation Library README, available in the module repository next to the library artifacts.

SECURITY (deprecated)

The SECURITY Foundation Library (ej.api:security) is deprecated and replaced by the CRYPTO library. It provided the same cryptographic operations and is part of the NET Pack up to NET Pack 14. New Applications should use the CRYPTO Foundation Library instead.

Name	Description	Module Link	API Link
Deprecated SECURITY	Deprecated, replaced by CRYPTO. Cryptographic operations.	SECURITY	SECURITY API