Uploaded image for project: 'Fabric'
  1. Fabric
  2. FAB-5363

Common "connection profile" definition for client applications

    Details

      Description

      All applications have a need to capture information of the target fabric backend and associated materials (eg. MSP and TLS certificates).

      The general idea is that a client/channel instance can be initialized directly from the connection profile, and have a code snippet like the following:

      1. var client = Client.loadFromConfig(json)
      2. var mychannel = client.getChannel('mychannel')
      3. mychannel.sendTransactionProposal()
      4. mychannel.sendTransaction()

      note that the app then doesn't need to manually construct the channel, add peers, add orderers, get the org admin, etc.

      The latest design resulted from the discussions

      ---
      #
      # The network connection profile provides client applications the information about the target
      # blockchain network that are necessary for the applications to interact with it. These are all 
      # knowledge that must be acquired from out-of-band sources. This file provides such a source.
      #
      name: "global-trade-network"
      
      #
      # Any properties with an "x-" prefix will be treated as application-specific, exactly like how naming
      # in HTTP headers or swagger properties work. The SDK will simply ignore these fields and leave
      # them for the applications to process. This is a mechanism for different components of an application
      # to exchange information that are not part of the standard schema described below. In particular,
      # the "x-type" property with the "hlfv1" value example below is used by Hyperledger Composer to
      # determine the type of Fabric networks (v0.6 vs. v1.0) it needs to work with.
      #
      x-type: "hlfv1"
      x-loggingLevel: info
      
      #
      # Describe what the target network is/does.
      #
      description: "The network to be in if you want to stay in the global trade business"
      
      #
      # Schema version of the content. Used by the SDK to apply the corresponding parsing rules.
      #
      version: 1.0.0
      
      #
      # The client section is SDK-specific. The sample below is for the node.js SDK
      #
      client:
        # Which organization does this application instance belong to? The value must be the name of an org
        # defined under "organizations"
        organization: Org1
      
        # set connection timeouts for the peer and orderer for the client
        connection:
          timeout:
           peer:
            endorser: 3s
            eventHub: 3s
            eventReg: 3s
           orderer: 3s
      
        # Needed to load users crypto keys and certs.
        cryptoconfig:
          path: path/to/fixtures/channel/crypto-config
      
        # Some SDKs support pluggable KV stores, the properties under "credentialStore" 
        # are implementation specific
        credentialStore:
          # [Optional]. Specific to FileKeyValueStore.js or similar implementations in other SDKs. Can be others
          # if using an alternative impl. For instance, CouchDBKeyValueStore.js would require an object
          # here for properties like url, db name, etc.
          path: "/tmp/hfc-kvs"
      
          # [Optional]. Specific to the CryptoSuite implementation. Software-based implementations like 
          # CryptoSuite_ECDSA_AES.js in node SDK requires a key store. PKCS#11 based implementations does 
          # not.
          cryptoStore:
            # Specific to the underlying KeyValueStore that backs the crypto key store. 
            path: "/tmp/hfc-cvs"
      
          # [Optional]. Specific to Composer environment
          wallet: wallet-name
      
        # BCCSP config for the client.
        BCCSP:
         security:
          enabled: true
          default:
           provider: "SW"
          hashAlgorithm: "SHA2"
          softVerify: true
          ephemeral: false
          level: 256
          pin: "12345678"
          label: "ForFabric"
          library: /path/to/bccsp/libraries
      
      #
      # [Optional]. But most apps would have this section so that channel objects can be constructed 
      # based on the content below. If an app is creating channels, then it likely will not need this 
      # section.
      #
      channels:
        # name of the channel
        mychannel:
          # Required. list of orderers designated by the application to use for transactions on this 
          # channel. This list can be a result of access control ("org1" can only access "ordererA"), or 
          # operational decisions to share loads from applications among the orderers.  The values must 
          # be "names" of orgs defined under "organizations/peers"
          orderers:
            - orderer.example.com
      
          # Required. list of peers from participating orgs
          peers:
            peer0.org1.example.com:
              # [Optional]. will this peer be sent transaction proposals for endorsement? The peer must 
              # have the chaincode installed. The app can also use this property to decide which peers 
              # to send the chaincode install request. Default: true
              endorsingPeer: true
      
              # [Optional]. will this peer be sent query proposals? The peer must have the chaincode
              # installed. The app can also use this property to decide which peers to send the 
              # chaincode install request. Default: true
              chaincodeQuery: true
      
              # [Optional]. will this peer be sent query proposals that do not require chaincodes, like 
              # queryBlock(), queryTransaction(), etc. Default: true
              ledgerQuery: true
      
              # [Optional]. will this peer be the target of the SDK's listener registration? All peers can 
              # produce events but the app typically only needs to connect to one to listen to events. 
              # Default: true
              eventSource: true
      
            peer0.org2.example.com:
              endorsingPeer: true
              chaincodeQuery: false
              ledgerQuery: true
              eventSource: false
      
          # [Optional]. what chaincodes are expected to exist on this channel? The application can use
          # this information to validate that the target peers are in the expected state by comparing
          # this list with the query results of getInstalledChaincodes() and getInstantiatedChaincodes()
          chaincodes:
            # the format follows the "cannonical name" of chaincodes by fabric code
            - example02:v1
            - marbles:1.0
      
      #
      # list of participating organizations in this network
      #
      organizations:
        Org1:
          mspid: Org1MSP
      
          peers:
            - peer0.org1.example.com
            - peer1.org1.example.com
      
          # [Optional]. Certificate Authorities issue certificates for identification purposes in a Fabric based
          # network. Typically certificates provisioning is done in a separate process outside of the 
          # runtime network. Fabric-CA is a special certificate authority that provides a REST APIs for 
          # dynamic certificate management (enroll, revoke, re-enroll). The following section is only for 
          # Fabric-CA servers.
          certificateAuthorities:
            - ca-org1
      
          # [Optional]. If the application is going to make requests that are reserved to organization 
          # administrators, including creating/updating channels, installing/instantiating chaincodes, it 
          # must have access to the admin identity represented by the private key and signing certificate. 
          # Both properties can be the PEM string or local path to the PEM file. Note that this is mainly for
          # convenience in development mode, production systems should not expose sensitive information
          # this way. The SDK should allow applications to set the org admin identity via APIs, and only use
          # this route as an alternative when it exists.
          adminPrivateKey: 
            pem: "-----BEGIN PRIVATE KEY----- <etc>"
          signedCert:
            path: "/tmp/somepath/signed-cert.pem"
      
        # the profile will contain public information about organizations other than the one it belongs to. 
        # These are necessary information to make transaction lifecycles work, including MSP IDs and 
        # peers with a public URL to send transaction proposals. The file will not contain private 
        # information reserved for members of the organization, such as admin key and certificate, 
        # fabric-ca registrar enroll ID and secret, etc.
        Org2:
          mspid: Org2MSP
          peers:
            - peer0.org2.example.com
      
      #
      # List of orderers to send transaction and channel create/update requests to. For the time
      # being only one orderer is needed. If more than one is defined, which one get used by the
      # SDK is implementation specific. Consult each SDK's documentation for its handling of orderers.
      #
      orderers:
        orderer.example.com:
          url: grpcs://localhost:7050
      
          # these are standard properties defined by the gRPC library
          # they will be passed in as-is to gRPC client constructor
          grpcOptions:
            ssl-target-name-override: orderer.example.com
            grpc-max-send-message-length: 15
      
          tlsCACerts:
            pem: "-----BEGIN CERTIFICATE----- <etc> "
      
      #
      # List of peers to send various requests to, including endorsement, query
      # and event listener registration.
      #
      peers:
        peer0.org1.example.com:
          # this URL is used to send endorsement and query requests
          url: grpcs://localhost:7051
      
          # this URL is used to connect the EventHub and registering event listeners
          eventUrl: grpcs://localhost:7053
      
          grpcOptions:
            ssl-target-name-override: peer0.org1.example.com
            grpc.http2.keepalive_time: 15
      
          tlsCACerts:
            # Comma-Separated list of paths
            path: peer0.org1.example.com/tlscacerts/org1.example.com-cert.pem
      
        peer0.org2.example.com:
          url: grpcs://localhost:8051
          eventUrl: grpcs://localhost:8053
          grpcOptions:
            ssl-target-name-override: peer0.org2.example.com
          tlsCACerts:
            # Comma-Separated list of paths
            path: peer0.org2.example.com/tlscacerts/org2.example.com-cert.pem
      
      #
      # Fabric-CA is a special kind of Certificate Authority provided by Hyperledger Fabric which allows 
      # certificate management to be done via REST APIs. Application may choose to use a standard 
      # Certificate Authority instead of Fabric-CA, in which case this section would not be specified.
      #
      certificateAuthorities:
        ca-org1:
          url: https://localhost:7054
          # the properties specified under this object are passed to the 'http' client verbatim when
          # making the request to the Fabric-CA server
          httpOptions:
            verify: true
          tlsCACerts:
            # Comma-Separated list of paths
            path: peerOrganizations/org1.example.com/ca/org1.example.com-cert.pem
            # Client key and cert for TLS mutual auth with Fabric CA. If the target Fabric CA server
            # does not have TLS mutual auth turned on, then this section is not needed
            client:
              keyfile: path/to/tls/fabricca/certs/client/client_fabric_client-key.pem
              certfile: path/to/tls/fabricca/certs/client/client_fabric_client.pem
      
      
          # Fabric-CA supports dynamic user enrollment via REST APIs. A "root" user, a.k.a registrar, is 
          # needed to enroll and invoke new users.
          registrar:
             enrollId: admin
             enrollSecret: adminpw
          # [Optional] The optional name of the CA.
          caName: caNameHere
      

      FAB-3621

       

        Attachments

          Issue Links

            Activity

              Toggl

              Enter your Toggl API token
              Mark as billable
              Apply JIRA issue labels


              {{ currentTimer.description|limitTo:35 }}...
              {{hours}} hour{{hoursS}}, {{minutes}} minute{{minutesS}}, {{seconds}} second{{secondsS}}

                People

                • Assignee:
                  harrisob@us.ibm.com Bret Harrison
                  Reporter:
                  jimthematrix Jim Zhang
                  Watchers:
                  Alan Atkinson, Aleksandar Likic, Anthony O'Dowd, Antonio Vassell, Baha A Shaaban, Baohua Yang, Bret Harrison, Chris Poole, Christopher Ferris, Dave Kelsey, David Enyeart, David Huffman, Elisabetta Flamini, Emil Nikolov, Ian Mitchell, Martin Cocks, Paul Sitoh, Qiang Wang, Rick Rine, Simon Stone, Tatsushi Inagaki, Troy Ronda, Yohei Ueda
                • Votes:
                  1 Vote for this issue
                  Watchers:
                  23 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved: