Package web5.sdk.crypto

Object Crypto

  • All Implemented Interfaces:
    
public class Crypto

    Cryptography utility object providing key generation, signature creation, and other crypto-related functionalities.

    The Crypto object operates based on provided algorithms and curve types, facilitating a generic approach to handling multiple cryptographic algorithms and their respective key types. It offers convenience methods to:

    Internally, it utilizes predefined mappings to pair algorithms and curve types with their respective KeyGenerator and Signer implementations, ensuring appropriate handlers are utilized for different cryptographic approaches. It also includes mappings to manage multicodec functionality, providing a mapping between byte arrays and respective key generators.

    val privateKey: Jwk = Crypto.generatePrivateKey(JWSAlgorithm.EdDSA, Curve.Ed25519)

    • Manages key generation and signing operations via predefined mappings to handle different crypto approaches.

    • Provides mechanisms to perform actions (e.g., signing, key generation) dynamically based on algorithmId AlgorithmId.

    • Constructor Detail

    • Method Detail

      • generatePrivateKey

        @JvmOverloads() final Jwk generatePrivateKey(AlgorithmId algorithmId, KeyGenOptions options)

        Generates a private key using the specified algorithmId, utilizing the appropriate KeyGenerator.

        Parameters:
        algorithmId - The algorithmId AlgorithmId.
        options - Options for key generation, may include specific parameters relevant to the algorithm.
        Returns:

        The generated private key as a Jwk object.

      • computePublicKey

         final Jwk computePublicKey(Jwk privateKey)

        Computes a public key from the given private key, utilizing relevant KeyGenerator.

        Parameters:
        privateKey - The private key used to compute the public key.
        Returns:

        The computed public key as a Jwk object.

      • sign

        @JvmOverloads() final ByteArray sign(Jwk privateKey, ByteArray payload, SignOptions options)

        Signs a payload using a private key.

        This function utilizes the appropriate Signer to generate a digital signature of the provided payload using the provided private key.

        Parameters:
        privateKey - The Jwk private key to be used for generating the signature.
        payload - The byte array data to be signed.
        options - Options for the signing operation, may include specific parameters relevant to the algorithm.
        Returns:

        The digital signature as a byte array.

      • sign

        @JvmOverloads() final ByteArray sign(Jwk privateKey, ByteArray payload)

        Signs a payload using a private key.

        This function utilizes the appropriate Signer to generate a digital signature of the provided payload using the provided private key.

        Parameters:
        privateKey - The Jwk private key to be used for generating the signature.
        payload - The byte array data to be signed.
        Returns:

        The digital signature as a byte array.

      • verify

         final Unit verify(Jwk publicKey, ByteArray signedPayload, ByteArray signature)

        Verifies a signature against a signed payload using a public key.

        This function utilizes the relevant verifier, determined by the algorithm and curve used in the Jwk, to ensure the provided signature is valid for the signed payload using the provided public key. The algorithm used can either be specified in the public key Jwk or passed explicitly as a parameter. If it is not found in either, an exception will be thrown.

        Algorithm MUST either be present on the Jwk or be provided explicitly

        Parameters:
        publicKey - The Jwk public key to be used for verifying the signature.
        signedPayload - The byte array data that was signed.
        signature - The signature that will be verified.

      • publicKeyToBytes

         final ByteArray publicKeyToBytes(Jwk publicKey)

        Converts a Jwk public key into its byte array representation.

        Parameters:
        publicKey - A Jwk object representing the public key to be converted.
        Returns:

        A ByteArray representing the byte-level information of the provided public key.

        val publicKeyBytes = publicKeyToBytes(myJwkPublicKey)

        This function assumes that the provided Jwk contains valid curve and algorithm information. Malformed or invalid Jwk objects may result in exceptions or unexpected behavior.

      • getKeyGenerator

         final KeyGenerator getKeyGenerator(AlgorithmId algorithmId)

        Retrieves a KeyGenerator based on the provided algorithmId. Currently, we provide key generators for keys that use ECC (see AlgorithmId enum)

        This function looks up and retrieves the relevant KeyGenerator based on the provided algorithmId.

        Parameters:
        algorithmId - The cryptographic algorithmId to find a key generator for.
        Returns:

        The corresponding KeyGenerator.

      • getKeyGenerator

         final KeyGenerator getKeyGenerator(Integer multiCodec)

        Retrieves a KeyGenerator based on the provided multicodec identifier.

        This function looks up and retrieves the relevant KeyGenerator based on the provided multicodec identifier.

        Parameters:
        multiCodec - The multicodec identifier to find a key generator for.
        Returns:

        The corresponding KeyGenerator.

      • getSigner

         final Signer getSigner(AlgorithmId algorithmId)

        Retrieves a Signer based on the provided algorithmId.

        This function looks up and retrieves the relevant Signer based on the provided algorithmId.

        Parameters:
        algorithmId - The algorithmId to find a signer for.
        Returns:

        The corresponding Signer.

      • getVerifier

        @JvmOverloads() final Signer getVerifier(JwaCurve curve)

        Retrieves a Signer to be used for verification based on the provided algorithm and curve.

        This function fetches the appropriate Signer, which contains the verification logic for the cryptographic approach determined by the specified algorithm and curve.

        Parameters:
        curve - The cryptographic curve to find a verifier for.
        Returns:

        The corresponding Signer capable of verification.

      • getVerifier

        @JvmOverloads() final Signer getVerifier()

        Retrieves a Signer to be used for verification based on the provided algorithm and curve.

        This function fetches the appropriate Signer, which contains the verification logic for the cryptographic approach determined by the specified algorithm and curve.

        Returns:

        The corresponding Signer capable of verification.

      • getJwkCurve

         final JwaCurve getJwkCurve(Jwk jwk)

        Extracts the cryptographic curve information from a Jwk object.

        This function parses and returns the curve type used in a Jwk. May return null if the curve information is not present or unsupported.

        Parameters:
        jwk - The Jwk object from which to extract curve information.
        Returns:

        The JwaCurve used in the Jwk, or null if the curve is not defined or recognized.

      • getAlgorithmMultiCodec

         final Integer getAlgorithmMultiCodec(AlgorithmId algorithmId)

        Retrieves the multicodec identifier associated with a given algorithmId.

        This function consults a predefined mapping of algorithmId to their respective multicodec identifiers, returning the matched identifier. Multicodec identifiers are useful for encoding the format or type of the key in systems that leverage multiple cryptographic standards.

        Parameters:
        algorithmId - The algorithmId for which the multicodec is requested.
        Returns:

        The multicodec identifier as an Int if a mapping exists, or null if the algorithmId combination is not supported or mapped.

        val multicodec = getAlgorithmMultiCodec(JWSAlgorithm.EdDSA, Curve.Ed25519)