CryptoUtils
Keywords: net.corda.core.crypto.CryptoUtils class
Date: 2023-09-18

net.corda.core.crypto

## Class CryptoUtils

- net.corda.core.crypto.CryptoUtils

-     public class CryptoUtils

- - ### Constructor Detail

    - #### CryptoUtils

          public CryptoUtils()

  - ### Method Detail

    - #### sign

          @NotNull
          public static DigitalSignature sign(@NotNull
                                                       java.security.PrivateKey $this$sign,
                                                       @NotNull
                                                       kotlin.Array[] bytesToSign)

      Utility to simplify the act of signing a byte array.

      Parameters:
        `bytesToSign` - the data/message to be signed in ByteArray form (usually the Merkle root).
      Returns:
        the `class DigitalSignature` object on the input message.
      Throws:
        `IllegalArgumentException` - if the signature scheme is not supported for this private key.
        `InvalidKeyException` - if the private key is invalid.
        `SignatureException` - if signing is not possible due to malformed data or private key.

    - #### sign

          @NotNull
          public static net.corda.core.crypto.DigitalSignature.WithKey sign(@NotNull
                                                                                     java.security.PrivateKey $this$sign,
                                                                                     @NotNull
                                                                                     kotlin.Array[] bytesToSign,
                                                                                     @NotNull
                                                                                     java.security.PublicKey publicKey)

      Utility to simplify the act of signing a byte array and return a `class DigitalSignature.WithKey` object. Note that there is no check if the public key matches with the signing private key.

      Parameters:
        `bytesToSign` - the data/message to be signed in ByteArray form (usually the Merkle root).
      Returns:
        the `class DigitalSignature.WithKey` object on the input message `bytesToSign` and `publicKey`.
      Throws:
        `IllegalArgumentException` - if the signature scheme is not supported for this private key.
        `InvalidKeyException` - if the private key is invalid.
        `SignatureException` - if signing is not possible due to malformed data or private key.
      See Also:
        `class DigitalSignature.WithKey`

    - #### sign

          @NotNull
          public static net.corda.core.crypto.DigitalSignature.WithKey sign(@NotNull
                                                                                     java.security.KeyPair $this$sign,
                                                                                     @NotNull
                                                                                     kotlin.Array[] bytesToSign)

      Helper function to sign with a key pair.

      Parameters:
        `bytesToSign` - the data/message to be signed in ByteArray form (usually the Merkle root).
      Returns:
        the digital signature (in ByteArray) on the input message.
      Throws:
        `IllegalArgumentException` - if the signature scheme is not supported for this private key.
        `InvalidKeyException` - if the private key is invalid.
        `SignatureException` - if signing is not possible due to malformed data or private key.

    - #### sign

          @NotNull
          public static net.corda.core.crypto.DigitalSignature.WithKey sign(@NotNull
                                                                                     java.security.KeyPair $this$sign,
                                                                                     @NotNull
                                                                                     OpaqueBytes bytesToSign)

      Helper function to sign the bytes of `bytesToSign` with a key pair.

      See Also:
        `bytesToSign`

    - #### sign

          @NotNull
          public static TransactionSignature sign(@NotNull
                                                           java.security.KeyPair $this$sign,
                                                           @NotNull
                                                           SignableData signableData)

      Helper function for signing a `class SignableData` object.

      Parameters:
        `signableData` - the object to be signed.
      Returns:
        a `class TransactionSignature` object.
      Throws:
        `IllegalArgumentException` - if the signature scheme is not supported for this private key.
        `InvalidKeyException` - if the private key is invalid.
        `SignatureException` - if signing is not possible due to malformed data or private key.
      See Also:
        `class SignableData`

    - #### verify

          public static boolean verify(@NotNull
                                       java.security.PublicKey $this$verify,
                                       @NotNull
                                       kotlin.Array[] content,
                                       @NotNull
                                       DigitalSignature signature)

      Utility to simplify the act of verifying a signature.

      Throws:
        `InvalidKeyException` - if the key to verify the signature with is not valid (i.e. wrong key type for the signature).
        `SignatureException` - if the signature is invalid (i.e. damaged), or does not match the key (incorrect).
        `IllegalArgumentException` - if the signature scheme is not supported or if any of the clear or signature data is empty.

    - #### isValid

          public static boolean isValid(@NotNull
                                        java.security.PublicKey $this$isValid,
                                        @NotNull
                                        kotlin.Array[] content,
                                        @NotNull
                                        DigitalSignature signature)

      Utility to simplify the act of verifying a signature. In comparison to `verify` if the key and signature do not match it returns false rather than throwing an exception. Normally you should use the function which throws, as it avoids the risk of failing to test the result, but this is for uses such as java.security.Signature.verify implementations.

      Returns:
        whether the signature is correct for this key.
      Throws:
        `InvalidKeyException` - if the key to verify the signature with is not valid (i.e. wrong key type for the signature).
        `SignatureException` - if the signature is invalid (i.e. damaged).
        `IllegalArgumentException` - if the signature scheme is not supported or if any of the clear or signature data is empty.
        `IllegalStateException` - if this is a `class CompositeKey`, because verification of composite key signatures is not supported.
      See Also:
        `verify`, java.security.Signature.verify

    - #### toStringShort

          @NotNull
          public static java.lang.String toStringShort(@NotNull
                                                                java.security.PublicKey $this$toStringShort)

      Render a public key to its hash (in Base58) of its serialised form using the DL prefix.

    - #### getKeys

          @NotNull
          public static java.util.Set<java.security.PublicKey> getKeys(@NotNull
                                                                                java.security.PublicKey $this$keys)

      Return a Set of the contained leaf keys if this is a `class CompositeKey`. Otherwise, return a Set with a single element (this PublicKey). Note that leaf keys cannot be of type `class CompositeKey`.

      See Also:
        Set, `class CompositeKey`, Set, PublicKey, `class CompositeKey`

    - #### isFulfilledBy

          public static boolean isFulfilledBy(@NotNull
                                              java.security.PublicKey $this$isFulfilledBy,
                                              @NotNull
                                              java.security.PublicKey otherKey)

      Return true if `otherKey` fulfils the requirements of this PublicKey.

      See Also:
        `otherKey`, PublicKey

    - #### isFulfilledBy

          public static boolean isFulfilledBy(@NotNull
                                              java.security.PublicKey $this$isFulfilledBy,
                                              @NotNull
                                              java.lang.Iterable<? extends java.security.PublicKey> otherKeys)

      Return true if `otherKeys` fulfil the requirements of this PublicKey.

      See Also:
        `otherKeys`, PublicKey

    - #### containsAny

          public static boolean containsAny(@NotNull
                                            java.security.PublicKey $this$containsAny,
                                            @NotNull
                                            java.lang.Iterable<? extends java.security.PublicKey> otherKeys)

      Checks whether any of the given `keys` matches a leaf on the `class CompositeKey` tree or a single PublicKey.

      Note that this function checks against leaves, which cannot be of type `class CompositeKey`. Due to that, if any of the `otherKeys` is a `class CompositeKey`, this function will not find a match.

      See Also:
        `keys`, `class CompositeKey`, PublicKey, `class CompositeKey`, `otherKeys`, `class CompositeKey`

    - #### byKeys

          @NotNull
          public static java.util.Set<java.security.PublicKey> byKeys(@NotNull
                                                                               java.lang.Iterable<net.corda.core.crypto.TransactionSignature> $this$byKeys)

      Returns the set of all PublicKeys of the signatures.

      See Also:
        PublicKey

    - #### component1

          @NotNull
          public static java.security.PrivateKey component1(@NotNull
                                                                     java.security.KeyPair $this$component1)

    - #### component2

          @NotNull
          public static java.security.PublicKey component2(@NotNull
                                                                    java.security.KeyPair $this$component2)

    - #### generateKeyPair

          @NotNull
          public static java.security.KeyPair generateKeyPair()

      A simple wrapper that will make it easier to swap out the signature algorithm we use in future.

    - #### entropyToKeyPair

          @NotNull
          public static java.security.KeyPair entropyToKeyPair(@NotNull
                                                                        java.math.BigInteger entropy)

      Returns a key pair derived from the given private key entropy. This is useful for unit tests and other cases where you want hard-coded private keys.

      Parameters:
        `entropy` - a BigInteger value.
      Returns:
        a deterministically generated KeyPair for the Crypto.DEFAULT_SIGNATURE_SCHEME.

    - #### verify

          public static boolean verify(@NotNull
                                       java.security.PublicKey $this$verify,
                                       @NotNull
                                       kotlin.Array[] signatureData,
                                       @NotNull
                                       kotlin.Array[] clearData)

      Helper function to verify a signature.

      Parameters:
        `signatureData` - the signature on a message.
        `clearData` - the clear data/message that was signed (usually the Merkle root).
      Throws:
        `InvalidKeyException` - if the key is invalid.
        `SignatureException` - if this signatureData object is not initialized properly, the passed-in signatureData is improperly encoded or of the wrong type, if this signatureData algorithm is unable to process the input data provided, etc.
        `IllegalArgumentException` - if the signature scheme is not supported for this private key or if any of the clear or signature data is empty.

    - #### verify

          public static boolean verify(@NotNull
                                       java.security.KeyPair $this$verify,
                                       @NotNull
                                       kotlin.Array[] signatureData,
                                       @NotNull
                                       kotlin.Array[] clearData)

      Helper function for the signers to verify their own signature.

      Parameters:
        `signatureData` - the signature on a message.
        `clearData` - the clear data/message that was signed (usually the Merkle root).
      Throws:
        `InvalidKeyException` - if the key is invalid.
        `SignatureException` - if this signatureData object is not initialized properly, the passed-in signatureData is improperly encoded or of the wrong type, if this signatureData algorithm is unable to process the input data provided, etc.
        `IllegalArgumentException` - if the signature scheme is not supported for this private key or if any of the clear or signature data is empty.

    - #### secureRandomBytes

          @NotNull
          public static kotlin.Array[] secureRandomBytes(int numOfBytes)

      Generate a securely random ByteArray of requested number of bytes. Usually used for seeds, nonces and keys.

      Parameters:
        `numOfBytes` - how many random bytes to output.
      Returns:
        a random ByteArray.
      Throws:
        `NoSuchAlgorithmException` - thrown if "NativePRNGNonBlocking" is not supported on the JVM or if no strong SecureRandom implementations are available or if Security.getProperty("securerandom.strongAlgorithms") is null or empty, which should never happen and suggests an unusual JVM or non-standard Java library.
      See Also:
        ByteArray

    - #### newSecureRandom

          @NotNull
          public static java.security.SecureRandom newSecureRandom()

      Get an instance of SecureRandom to avoid blocking, due to waiting for additional entropy, when possible. In this version, the NativePRNGNonBlocking is exclusively used on Linux OS to utilize dev/urandom because in high traffic /dev/random may wait for a certain amount of "noise" to be generated on the host machine before returning a result.

      On Solaris, Linux, and OS X, if the entropy gathering device in java.security is set to file:/dev/urandom or file:/dev/random, then NativePRNG is preferred to SHA1PRNG. Otherwise, SHA1PRNG is preferred.

      Returns:
        a SecureRandom object.
      Throws:
        `NoSuchAlgorithmException` - thrown if "NativePRNGNonBlocking" is not supported on the JVM or if no strong SecureRandom implementations are available or if Security.getProperty("securerandom.strongAlgorithms") is null or empty, which should never happen and suggests an unusual JVM or non-standard Java library.
      See Also:
        SecureRandom

    - #### random63BitValue

          public static long random63BitValue()

      Returns a random positive non-zero long generated using a secure RNG. This function sacrifies a bit of entropy in order to avoid potential bugs where the value is used in a context where negative numbers or zero are not expected.

    - #### componentHash

          @Deprecated
           @NotNull
          public static SecureHash componentHash(@NotNull
                                                                       OpaqueBytes opaqueBytes,
                                                                       @NotNull
                                                                       PrivacySalt privacySalt,
                                                                       int componentGroupIndex,
                                                                       int internalIndex)

      Deprecated.

      Compute the hash of each serialised component so as to be used as Merkle tree leaf. The resultant output (leaf) is calculated using the SHA256d algorithm, thus SHA256(SHA256(nonce || serializedComponent)), where nonce is computed from `computeNonce`.

      See Also:
        `computeNonce`

    - #### componentHash

          @Deprecated
           @NotNull
          public static SecureHash componentHash(@NotNull
                                                                       SecureHash nonce,
                                                                       @NotNull
                                                                       OpaqueBytes opaqueBytes)

      Deprecated.

      Return the SHA256(SHA256(nonce || serializedComponent)).

    - #### serializedHash

          @Deprecated
           @NotNull
          public static <T> SecureHash serializedHash(@NotNull
                                                                            T x)

      Deprecated.

      Serialise the object and return the hash of the serialized bytes. Note that the resulting hash may not be deterministic across platform versions: serialization can produce different values if any of the types being serialized have changed, or if the version of serialization specified by the context changes.

    - #### computeNonce

          @Deprecated
           @NotNull
          public static net.corda.core.crypto.SecureHash.SHA256 computeNonce(@NotNull
                                                                                                   PrivacySalt privacySalt,
                                                                                                   int groupIndex,
                                                                                                   int internalIndex)

      Deprecated.

      Method to compute a nonce based on privacySalt, component group index and component internal index. SHA256d (double SHA256) is used to prevent length extension attacks.

      Parameters:
        `privacySalt` - a `class PrivacySalt`.
        `groupIndex` - the fixed index (ordinal) of this component group.
        `internalIndex` - the internal index of this object in its corresponding components list.
      Returns:
        SHA256(SHA256(privacySalt || groupIndex || internalIndex))