Crypto - corda

corda / net.corda.core.crypto / Crypto

# Crypto

`object Crypto`

This object controls and provides the available and supported signature schemes for Corda. Any implemented 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:

### Properties

#### COMPOSITE_KEY | Corda CompositeKey signature type. `val COMPOSITE_KEY: SignatureScheme`
#### DEFAULT_SIGNATURE_SCHEME | Our default signature scheme if no algorithm is specified (e.g. for key generation). `val DEFAULT_SIGNATURE_SCHEME: SignatureScheme`
#### ECDSA_SECP256K1_SHA256 | ECDSA signature scheme using the secp256k1 Koblitz curve and SHA256 for message hashing. `val ECDSA_SECP256K1_SHA256: SignatureScheme`
#### ECDSA_SECP256R1_SHA256 | ECDSA signature scheme using the secp256r1 (NIST P-256) curve and SHA256 for message hashing. `val ECDSA_SECP256R1_SHA256: SignatureScheme`
#### EDDSA_ED25519_SHA512 | EdDSA signature scheme using the ed25519 twisted Edwards curve and SHA512 for message hashing. The actual algorithm is PureEdDSA Ed25519 as defined in https://tools.ietf.org/html/rfc8032 Not to be confused with the EdDSA variants, Ed25519ctx and Ed25519ph. `val EDDSA_ED25519_SHA512: SignatureScheme`
#### RSA_SHA256 | RSA PKCS#1 signature scheme using SHA256 for message hashing. The actual algorithm id is 1.2.840.113549.1.1.1 Note: Recommended key size >= 3072 bits. `val RSA_SHA256: SignatureScheme`
#### SHA512_256 | DLSequence (ASN1Sequence) for SHA512 truncated to 256 bits, used in SPHINCS-256 signature scheme. `val SHA512_256: DLSequence`
#### SPHINCS256_SHA256 | SPHINCS-256 hash-based signature scheme using SHA512 for message hashing. It provides 128bit security against post-quantum attackers at the cost of larger key nd signature sizes and loss of compatibility. `val SPHINCS256_SHA256: SignatureScheme`

### Functions

#### decodePrivateKey | Decode a PKCS8 encoded key to its PrivateKey object. Use this method if the key type is a-priori unknown. `fun decodePrivateKey(encodedKey: ByteArray): PrivateKey` Decode a PKCS8 encoded key to its PrivateKey object based on the input scheme code name. This should be used when the type key is known, e.g. during deserialisation or with key caches or key managers. `fun decodePrivateKey(schemeCodeName: String, encodedKey: ByteArray): PrivateKey` `fun decodePrivateKey(signatureScheme: SignatureScheme, encodedKey: ByteArray): PrivateKey`
#### decodePublicKey | Decode an X509 encoded key to its PublicKey object. Use this method if the key type is a-priori unknown. `fun decodePublicKey(encodedKey: ByteArray): PublicKey` Decode an X509 encoded key to its PrivateKey object based on the input scheme code name. This should be used when the type key is known, e.g. during deserialisation or with key caches or key managers. `fun decodePublicKey(schemeCodeName: String, encodedKey: ByteArray): PublicKey` `fun decodePublicKey(signatureScheme: SignatureScheme, encodedKey: ByteArray): PublicKey`
#### deriveKeyPair | Deterministically generate/derive a KeyPair using an existing private key and a seed as inputs. This operation is currently supported for ECDSA secp256r1 (NIST P-256), ECDSA secp256k1 and EdDSA ed25519. `fun deriveKeyPair(signatureScheme: SignatureScheme, privateKey: PrivateKey, seed: ByteArray): KeyPair` Deterministically generate/derive a KeyPair using an existing private key and a seed as inputs. Use this method if the SignatureScheme of the private key input is not known. `fun deriveKeyPair(privateKey: PrivateKey, seed: ByteArray): KeyPair`
#### deriveKeyPairFromEntropy | Returns a key pair derived from the given BigInteger entropy. This is useful for unit tests and other cases where you want hard-coded private keys. Currently, the following schemes are supported: EDDSA_ED25519_SHA512, ECDSA_SECP256R1_SHA256 and ECDSA_SECP256K1_SHA256. `fun deriveKeyPairFromEntropy(signatureScheme: SignatureScheme, entropy: BigInteger): KeyPair` Returns a DEFAULT_SIGNATURE_SCHEME key pair derived from the given BigInteger entropy. `fun deriveKeyPairFromEntropy(entropy: BigInteger): KeyPair`
#### doSign | 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). `fun doSign(privateKey: PrivateKey, clearData: ByteArray): ByteArray` Generic way to sign ByteArray data with a PrivateKey and a known schemeCodeName String. `fun doSign(schemeCodeName: String, privateKey: PrivateKey, clearData: ByteArray): ByteArray` Generic way to sign ByteArray data with a PrivateKey and a known Signature. `fun doSign(signatureScheme: SignatureScheme, privateKey: PrivateKey, clearData: ByteArray): ByteArray` Generic way to sign SignableData objects with a PrivateKey. SignableData is a wrapper over the transaction's id (Merkle root) in order to attach extra information, such as a timestamp or partial and blind signature indicators. `fun doSign(keyPair: KeyPair, signableData: SignableData): TransactionSignature`
#### doVerify | 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. `fun doVerify(schemeCodeName: String, publicKey: PublicKey, signatureData: ByteArray, clearData: ByteArray): Boolean` 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). `fun doVerify(publicKey: PublicKey, signatureData: ByteArray, clearData: ByteArray): Boolean` Method to verify a digital signature. It returns true if it succeeds, but it always throws an exception if verification fails. `fun doVerify(signatureScheme: SignatureScheme, publicKey: PublicKey, signatureData: ByteArray, clearData: ByteArray): Boolean` Utility to simplify the act of verifying a TransactionSignature. It returns true if it succeeds, but it always throws an exception if verification fails. `fun doVerify(txId: SecureHash, transactionSignature: TransactionSignature): Boolean`
#### findProvider | `fun findProvider(name: String): Provider`
#### findSignatureScheme | `fun findSignatureScheme(algorithm: AlgorithmIdentifier): SignatureScheme` Find SignatureScheme by platform specific schemeNumberID. `fun findSignatureScheme(schemeNumberID: Int): SignatureScheme` Factory pattern to retrieve the corresponding SignatureScheme based on SignatureScheme.schemeCodeName. This function is usually called by key generators and verify signature functions. In case the input is not a key in the supportedSignatureSchemes map, null will be returned. `fun findSignatureScheme(schemeCodeName: String): SignatureScheme` Retrieve the corresponding SignatureScheme based on the type of the input Key. This function is usually called when requiring to verify signatures and the signing schemes must be defined. For the supported signature schemes see Crypto. `fun findSignatureScheme(key: PublicKey): SignatureScheme` `fun findSignatureScheme(key: PrivateKey): SignatureScheme`
#### generateKeyPair | 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. `fun generateKeyPair(schemeCodeName: String): KeyPair` Generate a KeyPair for the selected SignatureScheme. Note that RSA is the sole algorithm initialized specifically by its supported keySize. `fun generateKeyPair(signatureScheme: SignatureScheme = DEFAULT_SIGNATURE_SCHEME): KeyPair`
#### isSupportedSignatureScheme | Check if the requested SignatureScheme is supported by the system. `fun isSupportedSignatureScheme(signatureScheme: SignatureScheme): Boolean`
#### isValid | 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 and false if not. In comparison to doVerify 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. `fun isValid(txId: SecureHash, transactionSignature: TransactionSignature): Boolean` 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 and false if not. In comparison to doVerify 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. Use this method if the signature scheme is not a-priori known. `fun isValid(publicKey: PublicKey, signatureData: ByteArray, clearData: ByteArray): Boolean` Method to verify a digital signature. In comparison to doVerify if the key and signature do not match it returns false rather than throwing an exception. Use this method if the signature scheme type is a-priori unknown. `fun isValid(signatureScheme: SignatureScheme, publicKey: PublicKey, signatureData: ByteArray, clearData: ByteArray): Boolean`
#### publicKeyOnCurve | Check if a point's coordinates are on the expected curve to avoid certain types of ECC attacks. Point-at-infinity is not permitted as well. `fun publicKeyOnCurve(signatureScheme: SignatureScheme, publicKey: PublicKey): Boolean`
#### registerProviders | Method to force registering all Crypto-related cryptography Providers. It is recommended that it is invoked first thing on `main` functions, so the Providers are in place before any cryptographic operation is requested outside Crypto (i.e., SecureRandom, KeyStore, cert-path validation, CRL & CSR checks etc.). `fun registerProviders(): Unit`
#### supportedSignatureSchemes | `fun supportedSignatureSchemes(): List<SignatureScheme>`
#### toSupportedPrivateKey | Convert a private key to a supported implementation. This can be used to convert a SUN's EC key to an BC key. This method is usually required to retrieve keys from JKS keystores that by default return SUN implementations. `fun toSupportedPrivateKey(key: PrivateKey): PrivateKey`
#### toSupportedPublicKey | Convert a public key to a supported implementation. `fun toSupportedPublicKey(key: SubjectPublicKeyInfo): PublicKey` Convert a public key to a supported implementation. This can be used to convert a SUN's EC key to an BC key. This method is usually required to retrieve a key (via its corresponding cert) from JKS keystores that by default return SUN implementations. `fun toSupportedPublicKey(key: PublicKey): PublicKey`
#### validatePublicKey | Check if a public key satisfies algorithm specs. For instance, an ECC key should lie on the curve and not being point-at-infinity. `fun validatePublicKey(key: PublicKey): Boolean`