Merge branch 'release/os/5.0' into amiegrace12/DOC-4835/base-docs-review

.snyk

@@ -54,4 +54,13 @@ ignore:
           the components affected.
         expires: 2023-06-19T15:49:59.760Z
         created: 2023-02-24T15:49:59.763Z
+  SNYK-JAVA-COMFASTERXMLWOODSTOX-3091135:
+    - '*':
+        reason: >-
+          Corda5 Shippable artifacts do not make use of dokka-core, which is
+          where this dependency originates, this is used at compile / build time
+          only for Kdoc generation and not shipped in any of our releasable
+          artifacts.
+        expires: 2023-06-19T13:28:02.582Z
+        created: 2023-03-20T13:28:02.597Z
 patch: {}

application/src/main/java/net/corda/v5/application/crypto/CompositeKeyGenerator.java

@@ -14,23 +14,23 @@
  * of leaf keys and their contributing weight, and each leaf can be a conventional single key or a composite key.
  * Keys contribute their weight to the total if they are matched by the signature.
  * <p>
- * For complex scenarios, such as *"Both Alice and Bob need to sign to consume a state S"*, we can represent
+ * For complex scenarios, such as "Both Alice and Bob need to sign to consume a state S", we can represent
  * the requirement by creating a tree with a root {@link CompositeKey}, and Alice and Bob as children.
- * The root node would specify *weights* for each of its children and a *threshold* – the minimum total weight required
- * (e.g. the minimum number of child signatures required) to satisfy the tree signature requirement.
+ * The root node would specify weights for each of its children and a threshold – the minimum total weight required
+ * (for example, the minimum number of child signatures required) to satisfy the tree signature requirement.
  * <p>
- * Using these constructs we can express e.g. 1 of N (OR) or N of N (AND) signature requirements. By nesting we can
- * create multi-level requirements such as *"either the CEO or 3 of 5 of his assistants need to sign"*.
+ * Using these constructs we can express, for example, one of N (OR) or N of N (AND) signature requirements. By nesting we can
+ * create multilevel requirements such as "Either the CEO or three of five of his assistants need to sign".
  * <p>
  * Composite key implementations will track the minimum total weight required (in the simple case – the minimum number of child
  * signatures required) to satisfy the subtree rooted at this node.
  */
 
 public interface CompositeKeyGenerator {
     /**
-     * Return a composite key from a weighted list of keys, and an overall threshold
+     * Return a composite key from a weighted list of keys, and an overall threshold.
      *
-     * @param keys A list of keys, each which its own weight
+     * @param keys A list of keys, each which its own weight.
      * @param threshold The threshold of total weights of keys that can be validated.
      */
     @NotNull

application/src/main/java/net/corda/v5/application/crypto/DigestService.java

@@ -7,6 +7,7 @@
 import org.jetbrains.annotations.NotNull;
 
 import java.io.InputStream;
+import java.util.Set;
 
 /**
  * Provides hashing capabilities to be used in all sandbox types.
@@ -33,11 +34,36 @@ public interface DigestService {
     @NotNull
     SecureHash hash(@NotNull InputStream inputStream, @NotNull DigestAlgorithmName digestName);
 
+    /**
+     * Parses a secure hash in string form into a {@link SecureHash}.
+     * <p>
+     * A valid secure hash string should be containing the algorithm and hexadecimal representation of the bytes
+     * separated by the colon character (':') ({@link net.corda.v5.crypto.SecureHash.DELIMITER}).
+     *
+     * @param algoNameAndHexString The algorithm name followed by the hex string form of the digest,
+     *                             separated by colon (':')
+     *                             e.g. SHA-256:98AF8725385586B41FEFF205B4E05A000823F78B5F8F5C02439CE8F67A781D90.
+     */
+    @NotNull
+    SecureHash parseSecureHash(@NotNull String algoNameAndHexString);
+
     /**
      * Returns the {@link DigestAlgorithmName} digest length in bytes.
      *
      * @param digestName The digest algorithm to get the digest length for.
      */
     @Suspendable
     int digestLength(@NotNull DigestAlgorithmName digestName);
+
+    /**
+     * Returns the defaulted digest algorithm.
+     */
+    @NotNull
+    DigestAlgorithmName defaultDigestAlgorithm();
+
+    /**
+     * Returns the supported digest algorithms.
+     */
+    @NotNull
+    Set<DigestAlgorithmName> supportedDigestAlgorithms();
 }

application/src/main/java/net/corda/v5/application/crypto/DigitalSignatureAndMetadata.java

@@ -1,11 +1,11 @@
 package net.corda.v5.application.crypto;
 
-import java.security.PublicKey;
 import java.util.Objects;
 
 import net.corda.v5.base.annotations.ConstructorForDeserialization;
 import net.corda.v5.base.annotations.CordaSerializable;
 import net.corda.v5.crypto.DigitalSignature;
+import net.corda.v5.crypto.SecureHash;
 import net.corda.v5.crypto.merkle.MerkleProof;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -15,7 +15,7 @@
  */
 @CordaSerializable
 public final class DigitalSignatureAndMetadata {
-    private final DigitalSignature.WithKey signature;
+    private final DigitalSignature.WithKeyId signature;
     private final DigitalSignatureMetadata metadata;
     private final MerkleProof proof;
 
@@ -32,7 +32,7 @@ private static void requireNotNull(@Nullable Object obj, @NotNull String message
      */
     @ConstructorForDeserialization
     public DigitalSignatureAndMetadata(
-        @NotNull DigitalSignature.WithKey signature,
+        @NotNull DigitalSignature.WithKeyId signature,
         @NotNull DigitalSignatureMetadata metadata,
         @Nullable MerkleProof proof
     ) {
@@ -44,14 +44,14 @@ public DigitalSignatureAndMetadata(
     }
 
     public DigitalSignatureAndMetadata(
-        @NotNull DigitalSignature.WithKey signature,
+        @NotNull DigitalSignature.WithKeyId signature,
         @NotNull DigitalSignatureMetadata metadata
     ) {
         this(signature, metadata, null);
     }
 
     @NotNull
-    public DigitalSignature.WithKey getSignature() {
+    public DigitalSignature.WithKeyId getSignature() {
         return signature;
     }
 
@@ -66,10 +66,10 @@ public MerkleProof getProof() {
     }
 
     /**
-     * @return The {@link PublicKey} that created the signature.
+     * @return The key id of the public key, whose private key complement created the signature.
      */
     @NotNull
-    public PublicKey getBy() {
+    public SecureHash getBy() {
         return signature.getBy();
     }
 

application/src/main/java/net/corda/v5/application/crypto/DigitalSignatureVerificationService.java

@@ -15,33 +15,30 @@
  */
 @DoNotImplement
 public interface DigitalSignatureVerificationService {
-    // TODO The following `verify` overload should be aligned with the other one as per: https://r3-cev.atlassian.net/browse/CORE-9332
     /**
      * Verifies a digital signature by using {@code signatureSpec}.
      * Always throws an exception if verification fails.
      *
-     * @param publicKey The signer's {@link PublicKey}.
-     * @param signatureSpec The signature spec.
+     * @param originalData  The original data/message that was signed (usually the Merkle root).
      * @param signatureData The signatureData on a message.
-     * @param clearData The clear data/message that was signed (usually the Merkle root).
-     *
+     * @param publicKey     The signer's {@link PublicKey}.
+     * @param signatureSpec The signature spec.
      * @throws CryptoSignatureException If verification of the digital signature fails.
-     * @throws IllegalArgumentException If the signature scheme is not supported or if any of the clear or signature
-     * data is empty.
+     * @throws IllegalArgumentException If the signature scheme is not supported or if any of the original or signature
+     *                                  data is empty.
      */
-    void verify(@NotNull PublicKey publicKey, @NotNull SignatureSpec signatureSpec, @NotNull byte[] signatureData, @NotNull byte[] clearData);
+    void verify(@NotNull byte[] originalData, @NotNull byte[] signatureData, @NotNull PublicKey publicKey, @NotNull SignatureSpec signatureSpec);
 
     /**
      * Verifies a digital signature against data. Throws {@link CryptoSignatureException} if verification fails.
      *
-     * @param originalData The original data on which the signature was applied (usually the Merkle root).
-     * @param signature The digital signature.
-     * @param publicKey The signer's {@link PublicKey}.
+     * @param originalData  The original data on which the signature was applied (usually the Merkle root).
+     * @param signature     The digital signature.
+     * @param publicKey     The signer's {@link PublicKey}.
      * @param signatureSpec The signature spec.
-     *
      * @throws CryptoSignatureException If verification of the digital signature fails.
-     * @throws IllegalArgumentException If the signature scheme is not supported or if any of the clear or signature
-     * data is empty.
+     * @throws IllegalArgumentException If the signature scheme is not supported or if any of the original or signature
+     *                                  data is empty.
      */
     void verify(@NotNull byte[] originalData, @NotNull DigitalSignature signature, @NotNull PublicKey publicKey, @NotNull SignatureSpec signatureSpec);
 }

application/src/main/java/net/corda/v5/application/crypto/MerkleTreeFactory.java

@@ -16,7 +16,7 @@
 @DoNotImplement
 public interface MerkleTreeFactory {
     /**
-     * Creates a {@link MerkleTree}
+     * Creates a {@link MerkleTree}.
      *
      * @param leaves The leaves of the tree.
      * @param digest Merkle Tree Hash digest used to construct the tree's node and leaf hashes.
@@ -33,8 +33,8 @@ MerkleTree createTree(
     /**
      * Creates a {@link MerkleTreeHashDigest}.
      *
-     * @param merkleTreeHashDigestProviderName name of the hash digest provider class
-     * @param digestAlgorithmName name of the base hash algorithm
+     * @param merkleTreeHashDigestProviderName Name of the hash digest provider class.
+     * @param digestAlgorithmName Name of the base hash algorithm.
      *
      * @return A new {@link MerkleTreeHashDigest} instance.
      */
@@ -48,9 +48,9 @@ MerkleTreeHashDigest createHashDigest(
     /**
      * Creates a {@link MerkleTreeHashDigest}.
      *
-     * @param merkleTreeHashDigestProviderName name of the hash digest provider class
-     * @param digestAlgorithmName name of the base hash algorithm
-     * @param options Hash digest provider specific options
+     * @param merkleTreeHashDigestProviderName Name of the hash digest provider class.
+     * @param digestAlgorithmName Name of the base hash algorithm.
+     * @param options Hash digest provider-specific options.
      *
      * @return A new {@link MerkleTreeHashDigest} instance.
      */

application/src/main/java/net/corda/v5/application/crypto/SignatureSpecService.java

@@ -15,7 +15,7 @@ public interface SignatureSpecService {
     /**
      * Works out a default signature spec for specified public key, given current security policies.
      *
-     * @param publicKey the public key to be used for signing
+     * @param publicKey The public key to be used for signing.
      *
      * @return An appropriate {@link SignatureSpec}, or {@code null} if nothing is available for the key type.
      */
@@ -26,10 +26,10 @@ public interface SignatureSpecService {
     /**
      * Works out a default signature spec for specified public key and digest algorithm given current security policies.
      *
-     * @param publicKey the public key to be used for signing
-     * @param digestAlgorithmName the digest algorithm to use, e.g. {@link DigestAlgorithmName#SHA2_256}
+     * @param publicKey The public key to be used for signing.
+     * @param digestAlgorithmName The digest algorithm to use, for example, {@link DigestAlgorithmName#SHA2_256}.
      *
-     * @return An appropriate {@link SignatureSpec}, or null if nothing is available for the key type
+     * @return An appropriate {@link SignatureSpec}, or null if nothing is available for the key type.
      */
     @Suspendable
     @Nullable
@@ -38,7 +38,7 @@ public interface SignatureSpecService {
     /**
      * Returns compatible signature specs for specified public key, given current security policies.
      *
-     * @param publicKey the public key to be used for signing
+     * @param publicKey The public key to be used for signing.
      */
     @Suspendable
     @NotNull
@@ -47,8 +47,8 @@ public interface SignatureSpecService {
     /**
      * Returns compatible signature specs for specified public key and digest algorithm, given current security policies.
      *
-     * @param publicKey the public key to be used for signing
-     * @param digestAlgorithmName the digest algorithm to use, e.g. [DigestAlgorithmName.SHA2_256]
+     * @param publicKey The public key to be used for signing.
+     * @param digestAlgorithmName The digest algorithm to use, for example, [DigestAlgorithmName.SHA2_256].
      */
     @Suspendable
     @NotNull

application/src/main/java/net/corda/v5/application/crypto/SigningService.java

@@ -32,22 +32,27 @@ public interface SigningService {
      * a {@link CompositeKey}, the first leaf signing key hosted by the node is used.
      * @param signatureSpec The {@link SignatureSpec} to use when producing this signature.
      *
-     * @return A {@link DigitalSignature.WithKey} representing the signed data and the {@link PublicKey} that belongs to the
+     * @return A {@link DigitalSignature.WithKeyId} representing the signed data and the {@link PublicKey} that belongs to the
      * same {@link KeyPair} as the {@link PrivateKey} that signed the data.
      *
      * @throws CordaRuntimeException If the input key is not a member of {@code keys}.
      */
     @Suspendable
     @NotNull
-    DigitalSignature.WithKey sign(@NotNull byte[] bytes, @NotNull PublicKey publicKey, @NotNull SignatureSpec signatureSpec);
+    DigitalSignature.WithKeyId sign(@NotNull byte[] bytes, @NotNull PublicKey publicKey, @NotNull SignatureSpec signatureSpec);
 
     /**
-     * Gets a set of signing keys to look into and returns a mapping of the requested signing keys to signing keys
-     * found to be owned by the caller. In case of {@link CompositeKey} it maps the composite key with the firstly found
-     * composite key leaf.
+     * Looks into a set of signing keys to find keys owned by the caller. In case of {@link CompositeKey} it looks into
+     * the composite key leaves and returns the firstly found owned composite key leaf.
      *
      * @param keys The signing keys to look into.
-     * @return A mapping of requested signing keys to found signing keys to be owned by the caller or {@code null} if not found to be owned.
+     * @return A mapping that maps the requested signing key:
+     * <ul>
+     *     <li> to the same key if it is owned by the caller in case the requested signing key is a plain key </li>
+     *     <li> to the firstly found composite key leaf to be owned by the caller, of the composite key's leaves (children)
+     *     in case the requested signing key is a composite key </li>
+     *     <li> to {@code null} if the requested key is not owned by the caller </li>
+     * </ul>
      */
     @Suspendable
     @NotNull

application/src/main/java/net/corda/v5/application/flows/FlowContextPropertyKeys.java

@@ -0,0 +1,15 @@
+package net.corda.v5.application.flows;
+
+public final class FlowContextPropertyKeys {
+
+    private FlowContextPropertyKeys() {
+    }
+
+    public static final String CPI_NAME = "corda.cpiName";
+    public static final String CPI_VERSION = "corda.cpiVersion";
+    public static final String CPI_SIGNER_SUMMARY_HASH = "corda.cpiSignerSummaryHash";
+    public static final String CPI_FILE_CHECKSUM = "corda.cpiFileChecksum";
+    public static final String CPK_FILE_CHECKSUM = "corda.cpkFileChecksum";
+    public static final String INITIAL_PLATFORM_VERSION = "corda.initialPlatformVersion";
+    public static final String INITIAL_SOFTWARE_VERSION = "corda.initialSoftwareVersion";
+}