CorDapp Packaging

Introduction

This document describes how to build format version 2 CPKs, CPBs and CPIs.

Before you start

You will need a working copy of corda-cli with the mgm and package plugins installed. See https://github.com/corda/corda-cli-plugin-host#setupbuild.

Configure the plugin in gradle

This describes how to convert an existing CorDapp project to the new Gradle plugin.

Add a new version number to gradle.properties:
```
cordaGradlePluginsVersion2=7.0.3
```

Add this repository to pluginManagement/repositories in settings.gradle:

maven {
    url "${artifactoryContextUrl}/corda-dev"
    content {
        includeGroupByRegex 'net\\.corda\\.plugins(\\..*)?'
    }
}

Add the plugin to the plugins section of settings.gradle:

id 'net.corda.plugins.cordapp-cpk2' version cordaGradlePluginsVersion2
id 'net.corda.plugins.cordapp-cpb2' version cordaGradlePluginsVersion2

Inside the cordapp project change the plugins block at the top of the file:

id 'net.corda.plugins.cordapp-cpk2'
// or
id 'net.corda.plugins.cordapp-cpb2'

Build a CPK

To build a CPK, configure the project with either cordapp-cpk2 or cordapp-cpb2 plugin and run the jar Gradle task.

./gradlew jar

Build a CPB

To build a CPB, configure the project with the cordapp-cpb2 plugin and run the cpb Gradle task.

./gradlew cpb

CPI Build Preparation (only needed first time)

Signing key setup

We need to generate a code signing key for signing the CPI. This key can be generated once and kept for reuse.

Generate a signing key:

keytool -genkeypair -alias "signing key 1" -keystore signingkeys.pfx -storepass "keystore password" -dname "cn=CPI Plugin Example - Signing Key 1, o=R3, L=London, c=GB" -keyalg RSA -storetype pkcs12 -validity 4000

Trust the Gradle plugin default signing key

The Gradle plugin can be configured with a cordapp/signing section to define which signing keys the CPK and CPB are signed with. If that section is missing from configuration a default signing key will be used.

If we are using the default signing key, we need to import it into our key store before building a CPI.

Save the following text into a file named gradle-plugin-default-key.pem

Import gradle-plugin-default-key.pem into the keystore

keytool -importcert -keystore signingkeys.pfx -storepass "keystore password" -noprompt -alias gradle-plugin-default-key -file gradle-plugin-default-key.pem

Trust the R3 signing key

The notary CPB is signed with an R3 production code signing certificate issued by the DigiCert. To use it import DigiCert certificate.

Save the following text into a file named digicert-ca.pem

Import digicert-ca.pem into the keystore

keytool -importcert -keystore signingkeys.pfx -storepass "keystore password" -noprompt -alias digicert-ca -file digicert-ca.pem

Prepare a group policy file

Please refer to the group policy wiki page to learn more about the GroupPolicy.json file included in CPIs: Group Policy

If you intend to run a basic static network setup, you can use the corda-cli mgm plugin to generate a group policy file. For example, you could run this command to generate a group policy file:

./corda-cli.sh mgm groupPolicy > TestGroupPolicy.json

Refer to the plugin README.md for more information on this plugin: README.md

If running a dynamic network, you will need to export the group policy file from the MGM using the HTTP API. Information on how to do this can be found on the MGM Onboarding wiki page.

Build a version 2 CPI

The gradle plugin will build the CPB. Run this command to turn a CPB into a CPI:

./corda-cli.sh package create-cpi \
    --cpb mycpb.cpb \
    --group-policy TestGroupPolicy.json \
    --cpi-name "cpi name" \
    --cpi-version "1.0.0.0-SNAPSHOT" \
    --file output.cpi \
    --keystore signingkeys.pfx \
    --storepass "keystore password" \
    --key "signing key 1"

Import trusted code signing certificates into Corda

Corda will validate that uploaded CPIs are signed with a trusted key. To trust your signing keys, upload them with these commands.

Import the DigiCert certificate into Corda

curl --insecure -u admin:admin -X PUT -F alias="digicert-ca" -F [email protected] https://localhost:8888/api/v1/certificates/cluster/code-signer

Export the signing key certificate from the key store

keytool -exportcert -rfc -alias "signing key 1" -keystore signingkeys.pfx -storepass "keystore password" -file signingkey1.pem

Import the signing key into Corda
```
curl --insecure -u admin:admin -X PUT -F alias="signingkey1-2022" -F [email protected] https://localhost:8888/api/v1/certificates/cluster/code-signer
```
Use an alias that will be unique over time. Consider how certificate expiry will require new certificates with the same x500 name as existing certificates and define a naming convention that covers that use case.

Import the gradle plugin default key into Corda

curl --insecure -u admin:admin -X PUT -F alias="gradle-plugin-default-key" -F [email protected] https://localhost:8888/api/v1/certificates/cluster/code-signer

Note: Do not import the gradle plugin key into the Corda in production. This should only be used in development.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CorDapp Packaging

CorDapp Packaging

Introduction

Before you start

Configure the plugin in gradle

Build a CPK

Build a CPB

CPI Build Preparation (only needed first time)

Signing key setup

Trust the Gradle plugin default signing key

Trust the R3 signing key

Prepare a group policy file

Build a version 2 CPI

Import trusted code signing certificates into Corda

Clone this wiki locally