Cryptology Overview

This page gives you an overview of the cryptology domain in Erbsland Core. You will learn where to find safe password storage, sensitive-data, and general hashing guidance.

Cryptographic APIs protect different properties of data. Hash algorithms create a fixed-size representation of a message, encryption protects confidentiality, signatures establish authenticity, and certificates connect identities to public keys. These mechanisms often work together, but they are not interchangeable. Start with the security property your application needs and then select the matching topic and API.

Authenticating with Tokens

A configured client can prove possession of a private Ed25519 credential by signing a fresh server challenge. The server stores only a public verifier, and a captured response cannot authenticate a later attempt. See Authenticating with Tokens for a complete ELCL-configured TCP example, the limits of the proof, and the interoperable token and response formats.

Signing and Verifying Byte Blocks

A publisher can sign a binary record so a reader with the matching public key can verify its origin and exact bytes. SignedByteBlock includes a purpose to keep one use of a key separate from another and an optional hint for finding the verifier. See Signing and Verifying Byte Blocks for key setup, signing, verification, and the interoperable binary layout.

Storing and Verifying Passwords

Passwords need a deliberately slow, salted password derivation, not a general hash. The PasswordHasher API accepts String, recommends marking password input as sensitive, requires an application key on the normal path, and produces an opaque PasswordHash record. Successful verification can include a replacement record when costs, algorithms, or keys need migration.

See Storing and Verifying Passwords for the complete storage and login workflow and Supported Password Hashing Algorithms for Argon2id, scrypt, presets, and migration policy.

Sensitive Data

A marked String uses securely erased shared UTF-8 storage. Binary secrets use ByteBlock and ByteBlockEditor allocations marked as sensitive. These mechanisms reduce recoverable heap remnants and keep secret-handling intent visible in APIs. They do not lock memory, prevent swapping, or erase ordinary source objects. See About Sensitive Strings and Byte Blocks for their intended uses, ownership behavior, and security limitations.

Using Hash Algorithms

A cryptographic hash maps an arbitrary byte sequence to a fixed-size digest. Applications use digests to identify content, detect changes when the expected digest is trusted, and prepare data for higher-level cryptographic operations.

The Hasher API processes data incrementally, so the complete message does not have to be held in memory. HashAlgorithm represents an explicit algorithm and can also select a recommendation from application requirements.

See Using Hash Algorithms to learn how to hash data, select an algorithm, persist digests, and defend code that processes untrusted input.

Reading X.509 Certificates

X509Certificate reads a single certificate from PEM, DER, or a file and exposes its names, validity period, public-key container, extensions, signature bytes, and exact encoded form. X509CertificateBundle handles ordered PEM files containing multiple certificates. Parsing verifies canonical encoding and the supported certificate profile, but does not establish trust, validate a signature, match a hostname, or decide whether a certificate is acceptable for a connection. See X.509 Certificates for formats, strict and compatible parsing, resource limits, and the typed field API.

Creating TLS Certificates and Requests

The profile-driven X509CertificateBuilder creates a local test CA and its server or client certificates, or produces a PKCS#10 request for an enterprise CA. It supplies the extension and signature defaults that are easy to get wrong while leaving application identity, SANs, validity, and hierarchy policy explicit. See Creating TLS Certificates and Requests for complete test and enterprise workflows.

Configuring TLS Profiles

TLS profiles keep each service’s identity and trust decisions in the application configuration. You can load client and server profiles from ELCL, use system authorities or a private CA, and replace all profiles together when rotating certificates. See Configuring TLS Profiles for setting up HTTPS, presenting client identities, requiring client certificates, and retrieving key passwords from secure storage.

Supported Hash Algorithms

Erbsland Core supports the SHA-3 and SHA-2 families for new cryptographic results. SHA-1 and MD5 remain available only to read or verify legacy formats and are rejected by the normal safety policy.

See Supported Hash Algorithms for the complete catalog, security strengths, intended uses, and differences between related algorithms.