net.corda.core.crypto

## Class Crypto

- net.corda.core.crypto.Crypto

-     public class Crypto

  This object controls and provides the available and supported signature schemes for Corda. Any implemented `class SignatureScheme` should be strictly defined here. However, only the schemes returned by {@link #listSupportedSignatureSchemes()} are supported. Note that Corda currently supports the following signature schemes by their code names:

  See Also:
    `class SignatureScheme`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Crypto` | `INSTANCE` This object controls and provides the available and supported signature schemes for Corda. Any implemented `class SignatureScheme` should be strictly defined here. However, only the schemes returned by {@link #listSupportedSignatureSchemes()} are supported. Note that Corda currently supports the following signature schemes by their code names:

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.security.PrivateKey` | `decodePrivateKey(byte[] encodedKey)` Decode a PKCS8 encoded key to its PrivateKey object.
    `java.security.PrivateKey` | `decodePrivateKey(byte[] encodedKey, java.lang.String schemeCodeName)` Decode a PKCS8 encoded key to its PrivateKey object based on the input scheme code name. This will be used by Kryo deserialisation.
    `java.security.PublicKey` | `decodePublicKey(byte[] encodedKey)` Decode an X509 encoded key to its PublicKey object.
    `java.security.PublicKey` | `decodePublicKey(byte[] encodedKey, java.lang.String schemeCodeName)` Decode an X509 encoded key to its PrivateKey object based on the input scheme code name. This will be used by Kryo deserialisation.
    `byte[]` | `doSign(java.security.PrivateKey privateKey, byte[] clearData)` Generic way to sign ByteArray data with a PrivateKey. Strategy on on identifying the actual signing scheme is based on the PrivateKey type, but if the schemeCodeName is known, then better use doSign(signatureScheme: String, privateKey: PrivateKey, clearData: ByteArray).
    `byte[]` | `doSign(java.lang.String schemeCodeName, java.security.PrivateKey privateKey, byte[] clearData)` Generic way to sign ByteArray data with a PrivateKey and a known schemeCodeName String.
    `TransactionSignature` | `doSign(java.security.PrivateKey privateKey, MetaData metaData)` Generic way to sign `class MetaData` objects with a PrivateKey. `class MetaData` is a wrapper over the transaction's Merkle root in order to attach extra information, such as a timestamp or partial and blind signature indicators.
    `boolean` | `doVerify(java.lang.String schemeCodeName, java.security.PublicKey publicKey, byte[] signatureData, byte[] clearData)` Utility to simplify the act of verifying a digital signature. It returns true if it succeeds, but it always throws an exception if verification fails.
    `boolean` | `doVerify(java.security.PublicKey publicKey, byte[] signatureData, byte[] clearData)` Utility to simplify the act of verifying a digital signature by identifying the signature scheme used from the input public key's type. It returns true if it succeeds, but it always throws an exception if verification fails. Strategy on identifying the actual signing scheme is based on the PublicKey type, but if the schemeCodeName is known, then better use doVerify(schemeCodeName: String, publicKey: PublicKey, signatureData: ByteArray, clearData: ByteArray).
    `boolean` | `doVerify(java.security.PublicKey publicKey, TransactionSignature transactionSignature)` Utility to simplify the act of verifying a `class TransactionSignature`. It returns true if it succeeds, but it always throws an exception if verification fails.
    `java.lang.String` | `findSignatureSchemeCodeName(java.security.Key key)` Retrieve the corresponding signature scheme code name based on the type of the input Key. See `class Crypto` for the supported scheme code names.
    `java.security.KeyPair` | `generateKeyPair(java.lang.String schemeCodeName)` Utility to simplify the act of generating keys. Normally, we don't expect other errors here, assuming that key generation parameters for every supported signature scheme have been unit-tested.
    `java.security.KeyPair` | `generateKeyPair()` Generate a KeyPair using the default signature scheme.
    `java.lang.String` | `getDefaultSignatureSchemeCodeName()`
    `boolean` | `isSupportedSignatureScheme(java.lang.String schemeCodeName)` Check if the requested signature scheme is supported by the system.
    `java.util.List<java.lang.String>` | `listSupportedSignatureSchemes()`

- - ### Field Detail

    - #### INSTANCE

          public static Crypto INSTANCE

      This object controls and provides the available and supported signature schemes for Corda. Any implemented `class SignatureScheme` should be strictly defined here. However, only the schemes returned by {@link #listSupportedSignatureSchemes()} are supported. Note that Corda currently supports the following signature schemes by their code names:

      See Also:
        `class SignatureScheme`

  - ### Method Detail

    - #### findSignatureSchemeCodeName

          public java.lang.String findSignatureSchemeCodeName(java.security.Key key)

      Retrieve the corresponding signature scheme code name based on the type of the input Key. See `class Crypto` for the supported scheme code names.

      Parameters:
        `key` - either private or public.
      Returns:
        signatureSchemeCodeName for a Key.
      Throws:
        - if the requested key type is not supported.
      See Also:
        Key, `class Crypto`

    - #### decodePrivateKey

          public java.security.PrivateKey decodePrivateKey(byte[] encodedKey)

      Decode a PKCS8 encoded key to its PrivateKey object.

      Parameters:
        `encodedKey` - a PKCS8 encoded private key.
      Throws:
        - on not supported scheme or if the given key specification is inappropriate for this key factory to produce a private key.
      See Also:
        PrivateKey

    - #### decodePrivateKey

          public java.security.PrivateKey decodePrivateKey(byte[] encodedKey,
                                                           java.lang.String schemeCodeName)

      Decode a PKCS8 encoded key to its PrivateKey object based on the input scheme code name. This will be used by Kryo deserialisation.

      Parameters:
        `encodedKey` - a PKCS8 encoded private key.
        `schemeCodeName` - a String that should match a key in supportedSignatureSchemes map (e.g. ECDSA_SECP256K1_SHA256).
      Throws:
        - on not supported scheme or if the given key specification is inappropriate for this key factory to produce a private key.
      See Also:
        PrivateKey

    - #### decodePublicKey

          public java.security.PublicKey decodePublicKey(byte[] encodedKey)

      Decode an X509 encoded key to its PublicKey object.

      Parameters:
        `encodedKey` - an X509 encoded public key.
      Throws:
        - on not supported scheme.
        - on not supported scheme or if the given key specification is inappropriate for this key factory to produce a private key.
      See Also:
        PublicKey

    - #### decodePublicKey

          public java.security.PublicKey decodePublicKey(byte[] encodedKey,
                                                         java.lang.String schemeCodeName)

      Decode an X509 encoded key to its PrivateKey object based on the input scheme code name. This will be used by Kryo deserialisation.

      Parameters:
        `encodedKey` - an X509 encoded public key.
        `schemeCodeName` - a String that should match a key in supportedSignatureSchemes map (e.g. ECDSA_SECP256K1_SHA256).
      Throws:
        - if the requested scheme is not supported
        - if the given key specification is inappropriate for this key factory to produce a public key.
      See Also:
        PrivateKey

    - #### generateKeyPair

          public java.security.KeyPair generateKeyPair(java.lang.String schemeCodeName)

      Utility to simplify the act of generating keys. Normally, we don't expect other errors here, assuming that key generation parameters for every supported signature scheme have been unit-tested.

      Parameters:
        `schemeCodeName` - a signature scheme's code name (e.g. ECDSA_SECP256K1_SHA256).
      Returns:
        a KeyPair for the requested scheme.
      Throws:
        - if the requested signature scheme is not supported.

    - #### generateKeyPair

          public java.security.KeyPair generateKeyPair()

      Generate a KeyPair using the default signature scheme.

      Returns:
        a new KeyPair.

    - #### doSign

          public byte[] doSign(java.security.PrivateKey privateKey,
                               byte[] clearData)

      Generic way to sign ByteArray data with a PrivateKey. Strategy on on identifying the actual signing scheme is based on the PrivateKey type, but if the schemeCodeName is known, then better use doSign(signatureScheme: String, privateKey: PrivateKey, clearData: ByteArray).

      Parameters:
        `privateKey` - the signer's PrivateKey.
        `clearData` - the data/message to be signed in ByteArray form (usually the Merkle root).
      Returns:
        the digital signature (in ByteArray) on the input message.
      Throws:
        - if the signature scheme is not supported for this private key.
        - if the private key is invalid.
        - if signing is not possible due to malformed data or private key.
      See Also:
        PrivateKey, PrivateKey

    - #### doSign

          public byte[] doSign(java.lang.String schemeCodeName,
                               java.security.PrivateKey privateKey,
                               byte[] clearData)

      Generic way to sign ByteArray data with a PrivateKey and a known schemeCodeName String.

      Parameters:
        `schemeCodeName` - a signature scheme's code name (e.g. ECDSA_SECP256K1_SHA256).
        `privateKey` - the signer's PrivateKey.
        `clearData` - the data/message to be signed in ByteArray form (usually the Merkle root).
      Returns:
        the digital signature (in ByteArray) on the input message.
      Throws:
        - if the signature scheme is not supported.
        - if the private key is invalid.
        - if signing is not possible due to malformed data or private key.
      See Also:
        PrivateKey

    - #### doSign

          public TransactionSignature doSign(java.security.PrivateKey privateKey,
                                             MetaData metaData)

      Generic way to sign `class MetaData` objects with a PrivateKey. `class MetaData` is a wrapper over the transaction's Merkle root in order to attach extra information, such as a timestamp or partial and blind signature indicators.

      Parameters:
        `privateKey` - the signer's PrivateKey.
        `metaData` - a `class MetaData` object that adds extra information to a transaction.
      Returns:
        a `class TransactionSignature` object than contains the output of a successful signing and the metaData.
      Throws:
        - if the signature scheme is not supported for this private key or if metaData.schemeCodeName is not aligned with key type.
        - if the private key is invalid.
        - if signing is not possible due to malformed data or private key.
      See Also:
        `class MetaData`, PrivateKey, `class MetaData`

    - #### doVerify

          public boolean doVerify(java.lang.String schemeCodeName,
                                  java.security.PublicKey publicKey,
                                  byte[] signatureData,
                                  byte[] clearData)

      Utility to simplify the act of verifying a digital signature. It returns true if it succeeds, but it always throws an exception if verification fails.

      Parameters:
        `publicKey` - the signer's PublicKey.
        `signatureData` - the signatureData on a message.
        `clearData` - the clear data/message that was signed (usually the Merkle root).
      Returns:
        true if verification passes or throws an exception if verification fails.
      Throws:
        - if the key is invalid.
        - if this signatureData object is not initialized properly, the passed-in signatureData is improperly encoded or of the wrong type, if this signatureData scheme is unable to process the input data provided, if the verification is not possible.
        - if the signature scheme is not supported or if any of the clear or signature data is empty.

    - #### doVerify

          public boolean doVerify(java.security.PublicKey publicKey,
                                  byte[] signatureData,
                                  byte[] clearData)

      Utility to simplify the act of verifying a digital signature by identifying the signature scheme used from the input public key's type. It returns true if it succeeds, but it always throws an exception if verification fails. Strategy on identifying the actual signing scheme is based on the PublicKey type, but if the schemeCodeName is known, then better use doVerify(schemeCodeName: String, publicKey: PublicKey, signatureData: ByteArray, clearData: ByteArray).

      Parameters:
        `publicKey` - the signer's PublicKey.
        `signatureData` - the signatureData on a message.
        `clearData` - the clear data/message that was signed (usually the Merkle root).
      Returns:
        true if verification passes or throws an exception if verification fails.
      Throws:
        - if the key is invalid.
        - if this signatureData object is not initialized properly, the passed-in signatureData is improperly encoded or of the wrong type, if this signatureData scheme is unable to process the input data provided, if the verification is not possible.
        - if the signature scheme is not supported or if any of the clear or signature data is empty.
      See Also:
        PublicKey

    - #### doVerify

          public boolean doVerify(java.security.PublicKey publicKey,
                                  TransactionSignature transactionSignature)

      Utility to simplify the act of verifying a `class TransactionSignature`. It returns true if it succeeds, but it always throws an exception if verification fails.

      Parameters:
        `publicKey` - the signer's PublicKey.
        `transactionSignature` - the signatureData on a message.
      Returns:
        true if verification passes or throws an exception if verification fails.
      Throws:
        - if the key is invalid.
        - if this signatureData object is not initialized properly, the passed-in signatureData is improperly encoded or of the wrong type, if this signatureData scheme is unable to process the input data provided, if the verification is not possible.
        - if the signature scheme is not supported or if any of the clear or signature data is empty.
      See Also:
        `class TransactionSignature`

    - #### isSupportedSignatureScheme

          public boolean isSupportedSignatureScheme(java.lang.String schemeCodeName)

      Check if the requested signature scheme is supported by the system.

      Parameters:
        `schemeCodeName` - a signature scheme's code name (e.g. ECDSA_SECP256K1_SHA256).
      Returns:
        true if the signature scheme is supported.

    - #### getDefaultSignatureSchemeCodeName

          public java.lang.String getDefaultSignatureSchemeCodeName()

      Returns:
        the default signature scheme's code name.

    - #### listSupportedSignatureSchemes

          public java.util.List<java.lang.String> listSupportedSignatureSchemes()

      Returns:
        a List of Strings with the scheme code names defined in `class SignatureScheme` for all of our supported signature schemes, see `class Crypto`.