1. Using Oracle Blockchain Platform
  2. Extend the Network
  3. Add Organizations with Third-Party Certificates to the Network

Add Organizations with Third-Party Certificates to the Network

This topic contains information about joining organizations using third-party certificates to an Oracle Blockchain Platform network.

Topics:

Typical Workflow to Join an Organization with Third-Party Certificates to an Oracle Blockchain Platform Network

Organization with certificates issued by a third-party certificate authority (CA) can join the Oracle Blockchain Platform network as participants.

Client-only Organizations

These participants are client-only organizations and have no peers or orderers. They cannot create channels, join peers or install chaincode.

After joining the network, these organizations can use an SDK or a Hyperledger Fabric CLI to:
  • Instantiate, invoke, and query chaincode if they're a client organization administrator.
  • Invoke and query chaincode if they're a client organization non-administrator.
To control who can instantiate and invoke chaincode when client-only organizations are part of the network:
  • The chaincode owner who installs the chaincode onto peers can decide who can instantiate the chaincode by using the Hyperledger Fabric peer chaincode package -i instantiation policy command to set the instantiation policy for the chaincode.
  • The chaincode instantiator can use the Hyperledger Fabric peer chaincode instantiate -P endorsement policy command to set the endorsement policy controlling who can invoke the chaincode.
  • The channel owner can decide who can invoke or query a chaincode by setting the channel proposal and query access control list. See Hyperledger Fabric Access Control Lists and What Are Channel Policies?.

Workflow

Here are the tasks that an organization with third-party certificates and the Oracle Blockchain Platform founder need to perform to join the organization to an Oracle Blockchain Platform network.

Task Who Does This? Description More Information
Get the third-party certificates Third-party certificates (participant) organization Go to the third-party CA server and generate the required certificates files. Format the files as needed for import into the network. Third-Party Certificate Requirements
Create the certificates file for import Third-party certificates (participant) organization Find the participant’s Admin and CA certificate information and use it to compose a JSON certificates file. Create an Organization's Third-Party Certificates File
Upload a certificate file for the third-party (participant) organization Founder organization Use the console to upload and import the participant’s certificate file to add the participant to the network. Import Certificates to Add Organizations to the Network
Export the ordering service settings from network founder and provide them to the third-party (participant) organization Founder organization Output the founder’s ordering services settings to a JSON file and send the file to the participant.

Open the ordering service settings file and find the ordering service’s address and port and give them to the participant. For example:

"orderingServiceNodes": [
{
"address": "grpcs://example_address:7777"
...
}]
 Join the Participant or Scaled-Out OSNs to the Founder's Ordering Service
Create the channel Founder Create a new channel and add the participant to it. Create a Channel
Install and instantiate the chaincode Founder In the founder’s instance, upload, install, and instantiate the chaincode. Choose the network peers to install the chaincode on. Use Quick Deployment
Set up the third-party (participant) organization's environment Third-party certificates (participant) organization To query or invoke chaincodes, the participant must:
  • Add the founder's ordering service's address and port to the participant's environment.
  • Configure the environment to use Hyperledger Fabric CLI or SDKs.
  • Install the chaincode on peers.
 Prepare the Third-Party Environment to Use the Oracle Blockchain Platform Network

Third-Party Certificate Requirements

To successfully join the network, an organization must generate the required third-party certificates. The information in these certificates is used to create the organization's certificates file, which is then imported into the founder's instance.

Which Certificates Do Organizations Need to Provide?

You must generate the following certificates from your CA server:

  • Client Public Certificate
  • CA Root Certificate

What Are the Requirements for These Certificates?

The certificates must meet the following requirements:

  • When generating the private key, you must use the Elliptic Curve Digital Signature Algorithm (ECDSA). This algorithm is the only accepted algorithm for Fabric MSP keys.
  • The Subject Key Identifier (SKI) is mandatory and you must indicate it as x509 extensions in the extension file.
  • You must convert the key files from the .key to the .pem format.
  • You must convert the certificates from the .crt to the .pem format.

Creating the Certificates

The following walkthrough is an example of how to use OpenSSL or the Hyperledger Fabric cryptogen utility to generate your certificates. For detailed information on the commands used, refer to:

To create your certificates using OpenSSL:

  1. Create a self-signed CA certificate/key:
    openssl ecparam -name prime256v1 -genkey -out ca.key
openssl pkcs8 -topk8 -inform PEM -in ca.key -outform pem -nocrypt -out ca-key.pem
openssl req -new -key ca-key.pem -out ca.csr
openssl x509 -req -days 365 -in ca.csr -signkey ca-key.pem -out ca.crt -extensions x509_ext -extfile opensslca.conf
openssl x509 -in ca.crt -out ca.pem -outform PEM
    Our example opensslca.conf file:
    [ req ]
default_bits        = 2048
distinguished_name  = subject
req_extensions      = req_ext
x509_extensions     = x509_ext
string_mask         = utf8only
 
 
[ subject ]
countryName         = CN
#countryName_default     = US
 
 
stateOrProvinceName     = Beijing
#stateOrProvinceName_default = NY
 
localityName            = Beijing
#localityName_default        = New York
 
organizationName         = thirdpartyca, LLC
#organizationName_default    = Example, LLC
 
# Use a friendly name here because its presented to the user. The server's DNS
#   names are placed in Subject Alternate Names. Plus, DNS names here is deprecated
#   by both IETF and CA/Browser Forums. If you place a DNS name here, then you
#   must include the DNS name in the SAN too (otherwise, Chrome and others that
#   strictly follow the CA/Browser Baseline Requirements will fail).
commonName          = thirdpartyca
#commonName_default      = Example Company
 
emailAddress            = ca@thirdpartyca.com
 
 
 
# Section x509_ext is used when generating a self-signed certificate. I.e., openssl req -x509 ...
[ x509_ext ]
 
 
subjectKeyIdentifier        = hash
authorityKeyIdentifier  = keyid,issuer
 
# You only need digitalSignature below. *If* you don't allow
#   RSA Key transport (i.e., you use ephemeral cipher suites), then
#   omit keyEncipherment because that's key transport.
basicConstraints        = CA:TRUE
keyUsage            = Certificate Sign, CRL Sign, digitalSignature, keyEncipherment
subjectAltName          = @alternate_names
nsComment           = "OpenSSL Generated Certificate"
 
# RFC 5280, Section 4.2.1.12 makes EKU optional
#   CA/Browser Baseline Requirements, Appendix (B)(3)(G) makes me confused
#   In either case, you probably only need serverAuth.
# extendedKeyUsage  = serverAuth, clientAuth
 
# Section req_ext is used when generating a certificate signing request. I.e., openssl req ...
[ req_ext ]
 
subjectKeyIdentifier        = hash
 
basicConstraints        = CA:FALSE
keyUsage            = digitalSignature, keyEncipherment
subjectAltName          = @alternate_names
nsComment           = "OpenSSL Generated Certificate"
 
# RFC 5280, Section 4.2.1.12 makes EKU optional
#   CA/Browser Baseline Requirements, Appendix (B)(3)(G) makes me confused
#   In either case, you probably only need serverAuth.
# extendedKeyUsage  = serverAuth, clientAuth
 
[ alternate_names ]
 
DNS.1       = localhost
DNS.2       = thirdpartyca.com
#DNS.3       = mail.example.com
#DNS.4       = ftp.example.com
 
# Add these if you need them. But usually you don't want them or
#   need them in production. You may need them for development.
# DNS.5       = localhost
# DNS.6       = localhost.localdomain
# DNS.7       = 127.0.0.1
  2. Create a user certificate/key using above CA key:
    openssl ecparam -name prime256v1 -genkey -out user.key
openssl pkcs8 -topk8 -inform PEM -in user.key -outform pem -nocrypt -out user-key.pem
openssl req -new -key user-key.pem -out user.csr
openssl x509 -req -days 365 -sha256 -CA ca.pem -CAkey ca-key.pem -CAserial ca.srl -CAcreateserial -in user.csr -out user.crt -extensions x509_ext -extfile openssl.conf
openssl x509 -in user.crt -out user.pem -outform PEM
    Our example openssl.conf file:
    [ req ]
default_bits        = 2048
default_keyfile     = tls-key.pem
distinguished_name  = subject
req_extensions      = req_ext
x509_extensions     = x509_ext
string_mask         = utf8only

# The Subject DN can be formed using X501 or RFC 4514 (see RFC 4519 for a description).
# Its sort of a mashup. For example, RFC 4514 does not provide emailAddress.
[ subject ]
countryName         = CN
#countryName_default     = US

stateOrProvinceName     = Beijing
#stateOrProvinceName_default = NY

localityName            = Beijing
#localityName_default        = New York

organizationName         = thirdpartyca, LLC
#organizationName_default    = Example, LLC

# Use a friendly name here because its presented to the user. The server's DNS
#   names are placed in Subject Alternate Names. Plus, DNS names here is deprecated
#   by both IETF and CA/Browser Forums. If you place a DNS name here, then you 
#   must include the DNS name in the SAN too (otherwise, Chrome and others that
#   strictly follow the CA/Browser Baseline Requirements will fail).
commonName          = admin@thirdpartyca.com
#commonName_default      = Example Company

emailAddress            = admin@thirdpartyca.com
#emailAddress_default        = test@example.com

# Section x509_ext is used when generating a self-signed certificate. I.e., openssl req -x509 ...
[ x509_ext ]
subjectKeyIdentifier        = hash
authorityKeyIdentifier  = keyid,issuer

# You only need digitalSignature below. *If* you don't allow
#   RSA Key transport (i.e., you use ephemeral cipher suites), then
#   omit keyEncipherment because that's key transport.
basicConstraints        = CA:FALSE
keyUsage            = digitalSignature, keyEncipherment

subjectAltName          = @alternate_names
nsComment           = "OpenSSL Generated Certificate"

# RFC 5280, Section 4.2.1.12 makes EKU optional
#   CA/Browser Baseline Requirements, Appendix (B)(3)(G) makes me confused
#   In either case, you probably only need serverAuth.
#extendedKeyUsage  = Any Extended Key Usage
#extendedKeyUsage = serverAuth, clientAuth


# Section req_ext is used when generating a certificate signing request. I.e., openssl req ...
[ x509_ca_ext ]
subjectKeyIdentifier        = hash
authorityKeyIdentifier  = keyid,issuer


# You only need digitalSignature below. *If* you don't allow
#   RSA Key transport (i.e., you use ephemeral cipher suites), then
#   omit keyEncipherment because that's key transport.
basicConstraints        = CA:TRUE
keyUsage            = Certificate Sign, CRL Sign, digitalSignature, keyEncipherment
subjectAltName          = @alternate_names
nsComment           = "OpenSSL Generated Certificate"


# RFC 5280, Section 4.2.1.12 makes EKU optional
#   CA/Browser Baseline Requirements, Appendix (B)(3)(G) makes me confused
#   In either case, you probably only need serverAuth.
#extendedKeyUsage  = Any Extended Key Usage
extendedKeyUsage = serverAuth, clientAuth


# Section req_ext is used when generating a certificate signing request. I.e., openssl req ...
[ req_ext ]
subjectKeyIdentifier        = hash
basicConstraints        = CA:FALSE
keyUsage            = digitalSignature, keyEncipherment
subjectAltName          = @alternate_names
nsComment           = "OpenSSL Generated Certificate"


# RFC 5280, Section 4.2.1.12 makes EKU optional
#   CA/Browser Baseline Requirements, Appendix (B)(3)(G) makes me confused
#   In either case, you probably only need serverAuth.
#extendedKeyUsage  = Any Extended Key Usage
#extendedKeyUsage = serverAuth, clientAuth

[ alternate_names ]
DNS.1       = localhost
DNS.3       = 127.0.0.1
DNS.4       = 0.0.0.0
# Add these if you need them. But usually you don't want them or
#   need them in production. You may need them for development.
# DNS.5       = localhost
# DNS.6       = localhost.localdomain
# DNS.7       = 127.0.0.1
# IPv6 localhost
# DNS.8     = ::1
To create your certificates using the Hyperledger Fabric cryptogen utility:
  • The following cryptogen commands are used to create Hyperledger Fabric key material:
    cryptogen generate --config=./crypto-config.yaml
    Our example crypto-config.yaml file:
    # Copyright IBM Corp. All Rights Reserved.
#
# SPDX-License-Identifier: Apache-2.0
#

# ---------------------------------------------------------------------------
# "PeerOrgs" - Definition of organizations managing peer nodes
# ---------------------------------------------------------------------------
PeerOrgs:
  # ---------------------------------------------------------------------------
  # Org1
  # ---------------------------------------------------------------------------
  - Name: Org1
    Domain: org1.example.com
    EnableNodeOUs: true
    # ---------------------------------------------------------------------------
    # "Specs"
    # ---------------------------------------------------------------------------
    # Uncomment this section to enable the explicit definition of hosts in your
    # configuration.  Most users will want to use Template, below
    #
    # Specs is an array of Spec entries.  Each Spec entry consists of two fields:
    #   - Hostname:   (Required) The desired hostname, sans the domain.
    #   - CommonName: (Optional) Specifies the template or explicit override for
    #                 the CN.  By default, this is the template:
    #
    #                              "{{.Hostname}}.{{.Domain}}"
    #
    #                 which obtains its values from the Spec.Hostname and
    #                 Org.Domain, respectively.
    # ---------------------------------------------------------------------------
    # Specs:
    #   - Hostname: foo # implicitly "foo.org1.example.com"
    #     CommonName: foo27.org5.example.com # overrides Hostname-based FQDN set above
    #   - Hostname: bar
    #   - Hostname: baz
    # ---------------------------------------------------------------------------
    # "Template"
    # ---------------------------------------------------------------------------
    # Allows for the definition of 1 or more hosts that are created sequentially
    # from a template. By default, this looks like "peer%d" from 0 to Count-1.
    # You may override the number of nodes (Count), the starting index (Start)
    # or the template used to construct the name (Hostname).
    #
    # Note: Template and Specs are not mutually exclusive.  You may define both
    # sections and the aggregate nodes will be created for you.  Take care with
    # name collisions
    # ---------------------------------------------------------------------------
    Template:
      Count: 2
      # Start: 5
      # Hostname: {{.Prefix}}{{.Index}} # default
    # ---------------------------------------------------------------------------
    # "Users"
    # ---------------------------------------------------------------------------
    # Count: The number of user accounts _in addition_ to Admin
    # ---------------------------------------------------------------------------
    Users:
      Count: 1
  # ---------------------------------------------------------------------------
  # Org2: See "Org1" for full specification
  # ---------------------------------------------------------------------------
  - Name: Org2
    Domain: org2.example.com
    EnableNodeOUs: true
    Template:
      Count: 2
    Users:
      Count: 1

What's Next?

After confirming that you’ve outputted and updated the proper files, you can then create the certificates file for import into the Oracle Blockchain Platform network. See Create an Organization's Third-Party Certificates File.

Create an Organization's Third-Party Certificates File

To join an Oracle Blockchain Platform network, the organization must write a certificates file containing its admincert and cacert information. The network founder imports this file to add the organization to the network.

Go to the certificates files that you generated from the CA server to find the information that you need to create the certificates file. See Third-Party Certificate Requirements.

The certificates file must be in written in JSON and contain the following fields:

  • mspid — Specifies the name of the organization.
  • type — Indicates that the organization is a network participant. This value must be Participant.
  • admincert — Contains the contents of the organization’s Admin certificates file. When you copy the certificates information into the JSON file, you must replace each new line with \n.
  • cacert — Contains the contents of the organization’s CA certificates file. When you copy the certificates information into the JSON file, you must replace each new line with \n.
This is how the file needs to be structured: 
{
  "mspID": "examplemspID",
  "type":  "Participant",  
  "certs": { 
   "admincert": "-----BEGIN CERTIFICATE-----\nexample_certificate\nexample_certificate==\n-----END CERTIFICATE-----\n",
   "cacert": "-----BEGIN CERTIFICATE-----\nexample_certificate\nexample_certificate==\n-----END CERTIFICATE-----\n"
 }
}

Prepare the Third-Party Environment to Use the Oracle Blockchain Platform Network

You must set up the third-party organization's environment before it can use the Oracle Blockchain Platform network.

Confirm that the following prerequisite tasks were completed. For information, see Typical Workflow to Join an Organization with Third-Party Certificates to an Oracle Blockchain Platform Network.

  • The third-party organization’s certificate file was created and sent to the Oracle Blockchain Platform network founder.
  • The network founder uploaded the certificates file to add the third-party organization to the network.
  • The network founder exported the orderer service's settings and gave the service's address and port to the third-party organization and the organization added them to the environment.
  • The network founder created a new channel and added the third-party organization to it.
  • The network founder installed and instantiated the chaincode.

Setup organization's Environment

Before the third-party organization can successfully use the Oracle Blockchain Platform network, it must set up its environment to use Hyperledger Fabric CLI or SDKs. See Welcome to Hyperledger Fabric.

Install the Chaincode

The third-party organization must install the chaincode on the peers. These peers must then be joined to the channel so that the chaincode can be invoked.

Instantiate the Chaincode

If needed, the third-party organizations can instantiate the chaincode on the channel. For example:

export  CORE_PEER_TLS_ENABLED=true
export  CORE_PEER_TLS_ROOTCERT_FILE=$PWD/tls-ca.pem
export  CORE_PEER_MSPCONFIGPATH=$PWD/crypto-config/peerOrganizations/customerorg1.com/users/Admin@customerorg1.com/msp
export  CORE_PEER_LOCALMSPID="customerorg1" 

### gets channel name from input###
CHANNEL_NAME=$1

echo "######### going to instantiate chaincode on channel ${CHANNEL_NAME} ##########"
CORE_PEER_ADDRESS=${peer_host}:${port} peer chaincode instantiate
-o ${peer_host}:${port}  --tls $CORE_PEER_TLS_ENABLED --cafile 
./tls-ca.pem -C ${CHANNEL_NAME}  -n obcs-example02 -v v0 -c '{"Args":["init","a","100","b","200"]}'

Invoke the Chaincode

Third-party organizations use the Hyperledger Fabric CLI or SDKs to invoke the chaincode. For example:

export CORE_PEER_TLS_ENABLED=true
export CORE_PEER_TLS_ROOTCERT_FILE=$PWD/tls-ca.pem
export CORE_PEER_MSPCONFIGPATH=$PWD/crypto-config/peerOrganizations/customerorg1.com/users/User1@customerorg1.com/msp
export CORE_PEER_LOCALMSPID="customerorg1"

### gets channel name from input ###
CHANNEL_NAME=$1

#### do query or invoke on chaincode ####

CORE_PEER_ADDRESS=${peer_host}:${port} peer chaincode query -C
${CHANNEL_NAME} -n $2 -c '{"Args":["query","a"]}'

CORE_PEER_ADDRESS=${peer_host}:${port} peer chaincode invoke -o
${peer_host}:${port} --tls $CORE_PEER_TLS_ENABLED --cafile ./tls-
ca.pem -C ${CHANNEL_NAME} -n $2 -c '{"Args":["invoke","a","b","10"]}'