DOCSEARCHbyAlgolia
Submit Docs

cryptography-kotlin

repository·main·Indexed 20 days ago

https://github.com/whyoleg/cryptography-kotlin

A Kotlin Multiplatform cryptography library providing a type-safe, uniform API by wrapping platform-native solutions such as OpenSSL, CryptoKit, WebCrypto, and JCA. It includes modules for core cryptographic primitives, arbitrary-precision integers (cryptography-bigint), secure random number generation (cryptography-random), and serialization for ASN.1/DER and PEM formats.

Tokens
20.6K
Snippets
62
Records
80
Agent score
70%

What's inside cryptography-kotlin

  1. Overview of cryptography-kotlin packages

    main

    The library is organized into several functional packages:

    • dev.whyoleg.cryptography: Contains core primitives for creating and accessing algorithms and providers.
    • dev.whyoleg.cryptography.algorithms: Defines supported algorithms, including digests (e.g., SHA256, SHA512), symmetric ciphers (e.g., AES.GCM, ChaCha20Poly1305), digital signatures (e.g., ECDSA, EdDSA), MAC (HMAC), key derivation (PBKDF2, HKDF), and key agreement (ECDH, DH).
    • dev.whyoleg.cryptography.operations: Provides the functional APIs to perform cryptographic tasks, such as Cipher (encryption/decryption), Hasher (hashing), SignatureGenerator (signatures), SecretDerivation (key derivation), SharedSecretGenerator (key agreement), and KeyGenerator (key management).
    • dev.whyoleg.cryptography.materials: Handles the encoding and decoding of cryptographic materials like keys and parameters.

  3. Use pre-defined ASN.1 modules for RFC 5280 and RFC 5208

    main

    The cryptography-serialization-asn1-modules module provides pre-defined ASN.1 structures based on standard cryptography RFCs. This allows you to work with common cryptographic data formats without manually defining the ASN.1 structures yourself.

    Supported structures include:

  4. Use the cryptography-serialization-pem module for PEM encoding/decoding

    main

    The cryptography-serialization-pem module provides support for PEM (Privacy-Enhanced Mail) encoding and decoding as defined by RFC 7468.

    It exposes two primary types for handling PEM data:

    1. PemLabel: A case-sensitive encapsulation label used to identify the type of content within the PEM document (e.g., RSA PRIVATE KEY).
    2. PemDocument: An immutable value object that represents a single PEM document, consisting of a PemLabel and the associated binary content.

  5. Use CryptographyRandom for secure random numbers

    main

    The cryptography-random module provides a Cryptographically Secure Pseudo-Random Number Generator (CSPRNG) through the CryptographyRandom class. It is designed to be zero-dependency and uses platform-native secure random sources to ensure high security across different environments.

    Supported platform-native sources include:

    • JVM: SecureRandom
    • JS, WasmJs: Crypto.getRandomValues
    • WasmWasi: random_get
    • Apple: CCRandomGenerateBytes
    • Linux: getrandom
    • Mingw: BCryptGenRandom

  6. Use the cryptography-bigint module for multiplatform arbitrary-precision integers

    main

    The cryptography-bigint module provides the BigInt class for arbitrary-precision integer arithmetic across multiple platforms. It is designed for multiplatform use and supports the following platform-specific implementations:

    • JVM: Uses java.math.BigInteger.
    • JS, WasmJs: Uses native JS BigInt.
    • Native, WasmWasi: Uses a custom implementation written from scratch.

    Key capabilities include:

    • Conversions: Convert between primitive number types, String, and ByteArray (using two's complement representation).
    • Comparisons: Compare BigInt instances with themselves or other number types.
    • Serialization: Supports serialization via kotlinx.serialization.

  8. How HKDF and PBKDF2 differ in key derivation

    main

    The library provides two distinct algorithms for different entropy scenarios:

    1. HKDF (HMAC-based Key Derivation Function): Designed for high-entropy input material (e.g., shared secrets from ECDH or random bytes). It is fast and used to format existing entropy into usable keys.
    2. PBKDF2 (Password-Based Key Derivation Function 2): Designed for low-entropy input (e.g., human-chosen passwords). It is deliberately slow, using a high iteration count to resist brute-force attacks.

    When using these, ensure you choose the algorithm that matches your input source's entropy level.

  10. How providers work in cryptography-kotlin

    main

    The cryptography-kotlin library does not implement cryptographic algorithms itself. Instead, it acts as a multiplatform abstraction layer that delegates all operations to platform-native libraries through providers.

    Each provider wraps a specific platform implementation (e.g., JDK on JVM, WebCrypto on JS, or CryptoKit on Apple platforms).

  11. How the cryptography-kotlin architecture works

    main

    The library follows a hierarchical chain of four core concepts to perform cryptographic tasks:

    1. Provider: A wrapper around platform-native implementations (e.g., OpenSSL, CryptoKit, WebCrypto, or JCA).
    2. Algorithm: Obtained from a Provider (e.g., AES.GCM or ECDSA).
    3. Key: Created by an Algorithm, either through generation or by decoding existing key material.
    4. Operation: Produced by a Key, representing the actual cryptographic action (e.g., ciphers, hashers, or signature generators).

    To use the library, you typically follow this flow: Get an algorithm from a provider $\rightarrow$ generate or load a key $\rightarrow$ perform an operation using that key.

    // 1. Get the algorithm from a provider
val aesGcm = CryptographyProvider.Default.get(AES.GCM)
// 2. Generate a key
val key = aesGcm.keyGenerator().generateKey()
// 3. Use the key for operations
val ciphertext = key.cipher().encrypt(plaintext)

  12. Core concepts of cryptography-kotlin

    main

    The cryptography-kotlin library is built around three primary abstractions that manage how cryptographic primitives are accessed and used:

    • CryptographyProvider: The entry point for obtaining specific CryptographyAlgorithm instances. It acts as a factory for algorithms.
    • CryptographyProvider.Default: An auto-configured provider that is available for immediate use without manual setup.
    • CryptographySystem: The top-level manager for the library's global state. It handles the default provider, the provider registry, and the default random number generator.