Pular para conteúdo

Hyperledger Fabric

Pré-requisitos

  • O S.O. onde vai ser feita a integração via PKCS#11 deve ser compatível com as bibliotecas do HSM.
  • Como o default do Fabric é usar o Alpine Linux é preciso alterar o dockerfile para usar um S.O. compatível.

Versões

  • Este procedimento foi feito com a versão abaixo do Hyperledger Fabric, no WSL 2 do Windows 11

    Componente Versão
    fabric-ca (server/client) 1.5.5
    fabric-tool 2.4.7
    fabric-peer 2.4.7
    fabric-orderer 2.4.7
    S.O. base Ubuntu 20.04 sobre WSL2 no Windows 11
    S.O. containers Ubuntu 22.04 (jammy)
    Go 1.20
    Client HSM 4.7.35
    Firmware HSM 5.0.28.0-243-g5a9cb01

Setup Inicial sem PKCS#11

  1. Seguir o procedimento descrito em Fabric test network. No item Getting started guide configurar apenas os seguintes tópicos:

    1. Prerequisite software
    2. Install Fabric and Fabric samples
  2. Inicie uma test network do zero a cada execução. Se o ambiente não estiver limpo, erros irão ocorrer em diversos pontos da subida da test network.

  3. Monitore os logs e outputs dos containers da test network. Os logs do client do HSM podem ser vistos aqui, quando ligados com a opção de stdout:

    HSM_LOG_DIR=stdout
    

Integração com o HSM via PKCS#11

  • Nos exemplos da integração a seguir são utilizados usuários/partições de HSM independentes para cada componente/organização.

    Componente Nome de usuário Observações Onde é usado
    Teste de integração do fabric-ca-client caclient Usado no teste de integração do fabric-ca-client. host
    Fabric-ca ca1 CA da organização 1 container
    Fabric-ca ca2 CA da organização 2 container
    Fabric-ca caorderer CA do orderer container
    Peer 1 peer1 Peer da organização 1 container
    Peer 2 peer2 Peer da organização 2 container

Setup inicial

  1. É necessário seguir os passos da seção Setup Inicial sem PKCS#11 antes de prosseguir.

    Executado em um Ubuntu 20.04 no WSL2 do Windows 11.

  2. Definir a variável de ambiente GOPATH com o diretório de trabalho, neste caso usaremos ~/go. Pode-se definir no arquivo ~/.profile para facilitar o uso.

    export GOPATH=$HOME/go
    

Recompilar as ferramentas do fabric e fabric-ca com suporte à PKCS#11

  1. Criar pastas do Hyperledger e clonar repositório do fabric-ca .

    cd $GOPATH
    mkdir -p src/github.com/hyperledger/
    cd src/github.com/hyperledger
    git clone -b v1.5.5 https://github.com/hyperledger/fabric-ca
    cd fabric-ca/
    
  2. Compilar os binários do fabric-ca e fabric-ca-client com suporte à PKCS#11.

    make fabric-ca-server GO_TAGS=pkcs11
    make fabric-ca-client GO_TAGS=pkcs11
    

    Os binários são gerados na pasta fabric-ca/bin.

  3. Copiar os binários fabric-ca e fabric-ca-client para a pasta fabric-samples/bin.

  4. Clonar repositório do fabric .

    cd $GOPATH/src/github.com/hyperledger
    git clone -b v2.4.7 https://github.com/hyperledger/fabric.git
    cd fabric
    
  5. Compilar os binários das tools com suporte à PKCS#11.

    make tools GO_TAGS=pkcs11
    

    Os binários são gerados na pasta build/bin.

  6. Copiar os binários gerados para a pasta fabric-samples/bin.

Integração com fabric-ca-client

  • Existe um teste de fabric-ca-client na pasta ./fabric-samples/hardware-security-module.
  • O arquivo, ./fabric-samples/hardware-security-module/README.md pode servir de guia, mas precisa de adaptações.

Este teste pode ser executado da própria máquina, sem necessidade de um container. Neste caso foi executado em um Ubuntu 20.04 no WSL2 do Windows 11.

  1. Para o teste precisamos alterar os códigos hard-coded.

    ./fabric-samples/hardware-security-module/ca-client-config/fabric-ca-client-config-template.yaml

    Na opção bccsp, alterar os seguintes campos: - Label: Label do token P11. No caso da Dinamo é "Dinamo HSM". - Pin: Senha utilizada para fazer login na P11. Senha do usuário configurado na P11 Dinamo.

    Não alterar o campo Library. O placeholder é sobrescrito pelo script de execução.

    #############################################################################
    # BCCSP (BlockChain Crypto Service Provider) section allows to select which
    # crypto implementation library to use
    #############################################################################
    bccsp:
        default: PKCS11
        PKCS11:
            Library: REPLACE_ME_HSMLIB
            Pin: 12345678
            Label: "Dinamo HSM"
            hash: SHA2
            security: 256
    
  2. Alterar o IP e usuário do HSM no script abaixo. Este script irá gerar o arquivo de configuração do fabric que será usado para fazer as chamadas do fabric-ca-client para gerar um novo usuário.

    #!/bin/bash
    
    #
    #   Test PKCS#11 CA client
    #
    
    # Add the path to the fabric-ca-client with pkcs11 support
    export PATH=./fabric-samples/bin:$PATH
    export PKCS11_LIB=/usr/lib/libtacndp11.so # path to the installed pkcs11
    
    # Dinamo pkcs11 configuration
    export DFENCE_PKCS11_IP=127.0.0.1     # HSM IP Address
    export DFENCE_PKCS11_USER=caclient  # HSM User
    export DFENCE_PKCS11_AUTO_RECONNECT=1
    #export HSM_LOG_DIR=./
    #export HSM_LOG_LEVEL=3
    
    ./fabric-samples/hardware-security-module/scripts/generate-hsm-user.sh HSMUser
    
  3. Para executar o teste, faça as alterações e execute o script acima.

    Confira se o usuário configurado em test-p11-ca-client.sh existe no HSM.

    ./start-fabric.sh
    ./test-p11-ca-client.sh
    ./stop-fabric.sh
    

    Exemplo de saída

    ./test-p11-ca-client.sh
    2022/11/24 19:06:08 [INFO] TLS Enabled
    2022/11/24 19:06:08 [INFO] generating key: &{A:ecdsa S:256}
    2022-11-24 19:06:08.860 -03 [bccsp_p11] generateECKey -> INFO 001 Generated new P11 key, SKI 80feb3f43df12ef5dae75a3dd3502092d702a8dd80e8fcb92335c41f54e372d0
    2022/11/24 19:06:08 [INFO] encoded CSR
    .
    .
    .
    

Integração com fabric-ca-server

  • Versões utilizadas:

    Componente Versão
    S.O. Ubuntu 22.04 (jammy)
    Go 1.20
    Client HSM 3.7.35-1
  • Para que o Hyperledger funcione com o HSM precisamos recompilar o container com as seguintes configurações:

    • Utilizar uma distro de linux com suporte ao cliente do HSM, neste exemplo usaremos Ubuntu;
    • Habilitar o suporte a PKCS#11.

Gerar imagem com suporte a PKCS#11

  1. Alterar o Dockerfile para compilar executar com o Ubuntu e instalar o client do HSM. O arquivo Dockerfile está localizado na pasta $GOPATH/src/github.com/hyperledger/fabric-ca/images/fabric-ca. Após as alterações, o arquivo deve ficar como o seguinte.

    #
    # Copyright IBM Corp. All Rights Reserved.
    #
    # SPDX-License-Identifier: Apache-2.0
    #
    ARG GO_VER
    
    FROM ubuntu:jammy
    ARG GO_LDFLAGS
    ARG GO_TAGS
    
    # Latest debian url of DINAMO client
    ENV HSM_CLIENT_URL "https://downloads.dinamonetworks.io/bin/client/linux/x64/4.7.35/dinamo-4.7.35-1.x64.deb"
    ENV GO_URL "https://storage.googleapis.com/golang/go1.19.3.linux-amd64.tar.gz"
    ENV DEBIAN_FRONTEND noninteractive
    
    RUN apt-get update -y && \
      apt-get install -y \
      apt-utils \
      gcc \
      binutils-gold \
      git \
      curl;
    
    RUN curl -L $GO_URL | tar -v -C /usr/local -xz
    
    ENV GOPATH /go
    RUN mkdir -p "$GOPATH/src" "$GOPATH/bin"
    ENV PATH $GOPATH/bin:/usr/local/go/bin:$PATH
    
    WORKDIR /tmp
    RUN curl -L $HSM_CLIENT_URL -o ./dinamo.deb
    RUN apt-get install -y ./dinamo.deb
    RUN rm ./dinamo.deb
    
    ADD . /build/fabric-ca
    WORKDIR /build/fabric-ca
    RUN go install -tags "${GO_TAGS}" -ldflags "${GO_LDFLAGS}" \
      github.com/hyperledger/fabric-ca/cmd/fabric-ca-server \
      && go install -tags "${GO_TAGS}" -ldflags "${GO_LDFLAGS}" \
      github.com/hyperledger/fabric-ca/cmd/fabric-ca-client
    
    RUN apt-get install -y \
      tzdata;
    ENV FABRIC_CA_HOME /etc/hyperledger/fabric-ca-server
    EXPOSE 7054
    CMD fabric-ca-server start -b admin:adminpw
    
  2. Compilar a imagem do fabric-ca.

    cd $GOPATH/src/github.com/hyperledger/fabric-ca
    export DOCKER_BUILDKIT=0
    export COMPOSE_DOCKER_CLI_BUILD=0
    make clean-all
    make docker GO_TAGS=pkcs11
    

Configurar a test network

  1. Alterar os arquivos de configuração fabric-ca-server-config.yaml de cada organização para que utilizem a PKCS#11 do HSM. Esses arquivos estão localizados nos caminhos abaixo:

    • fabric-samples/test-network/organizations/fabric-ca/org1/fabric-ca-server-config.yaml.
    • fabric-samples/test-network/organizations/fabric-ca/org2/fabric-ca-server-config.yaml.


    Estas configurações também podem ser definidas por variáveis de ambiente como mostrado na documentação de HSM do Fabric.

  2. Alterar a seção bccsp para os seguintes valores.

    bccsp:
        default: PKCS11
        PKCS11:
            Library: /usr/lib/libtacndp11.so
            Pin: 12345678 # Senha do usuário do HSM
            Label: "Dinamo HSM"
            hash: SHA2
            security: 256
            Immutable: false
    
  3. Configurar as variáveis de ambiente do client do HSM no arquivo compose da ca compose-ca.yaml. Este arquivo se encontra em fabric-samples/test-network/compose/compose-ca.yaml.

    Neste caso estamos configurando a CA da organização 1, incluir as variáveis de ambiente na sua respectiva seção, como abaixo.

    Utilizar um usuário do HSM diferente para cada uma das CAs.

    services:
    
      ca_org1:
        ...
        environment:
          ...
          - DFENCE_PKCS11_IP=host.docker.internal # IP do HSM
          - DFENCE_PKCS11_USER=ca1 # Usuário do HSM
          - DFENCE_PKCS11_AUTO_RECONNECT=1
    
      ...
    
      ca_org2:
        ...
        environment:
          ...
          - DFENCE_PKCS11_IP=host.docker.internal # IP do HSM
          - DFENCE_PKCS11_USER=ca2 # Usuário do HSM
          - DFENCE_PKCS11_AUTO_RECONNECT=1
    

Subir a test network e executar um teste

  1. Execute o script de teste.

  2. Exemplo de saída do teste de básico de transferência

    ./test-basic-transfer.sh
    2022-11-14 18:32:53.487 -03 0001 INFO [chaincodeCmd] chaincodeInvokeOrQuery -> Chaincode invoke successful. result: status:200
    
    2022-11-14 18:32:56.826 -03 0001 INFO [chaincodeCmd] chaincodeInvokeOrQuery -> Chaincode invoke successful. result: status:200 payload:"Michel"
    {"AppraisedValue":800,"Color":"white","ID":"asset6","Owner":"Michel","Size":15}
    
  3. Verificar pelo log remoto do HSM que o usuário configurado (ex: ca1) foi utilizado corretamente.

    2022/11/14 21:28:05 00000062 000000B7 995E9769 ca1/1d571851df3d6f v-attr update|172.17.0.1 172.17.0.2:4433 ca1
    2022/11/14 21:28:05 00000062 000000B8 995E9769 MANAGE_P11 (03:ca1/1d571851df3d6f) [00000000], c: 23|172.17.0.1 172.17.0.2:4433 ca1
    2022/11/14 21:28:05 00000062 000000B9 995E9769 172.17.0.1#23 probe|172.17.0.1 172.17.0.2:4433 ca1
    2022/11/14 21:28:05 00000062 000000BA 995E9769 ecc 1d571851df3d6f!0nMFd8VvAX80FxUQ7L+1Sh6eRZ6SSEJSJLuq6BasfL8=, c: 23|172.17.0.1 172.17.0.2:4433 ca1
    
  4. Verificar que as chaves foram criadas no usuário do teste.

    Dinamo - Remote Management Console v. 4.7.34.0 2018 (c) Dinamo Networks
    
    HSM 127.0.0.1 e - Engine 5.0.28.0-243-g5a9cb01 (DXP) - TCA0000000  - ID ca1
    
    Keys/Objects - List
    
    
    Name                                      Type                 T E Label
    ================================================================================
    1d571851df3d6f                            prime256v1           n n e60bde44a80e532e20e5ac0952a093a4659e2736bca5b729a5708e6fbdfb8aee
    a8d9d38535ec9a                            prime256v1 pub       n y ea1f764edd0e8187409d61dfd78313d706b1b146fecb8a99b5f69309aced5de8
    d6f690620dee1a                            prime256v1           n n ea1f764edd0e8187409d61dfd78313d706b1b146fecb8a99b5f69309aced5de8
    d7ac2114025001                            prime256v1 pub       n y e60bde44a80e532e20e5ac0952a093a4659e2736bca5b729a5708e6fbdfb8aee
    
    Total of objects: 4
    

Integração com o orderer, peer e tools (container)

  • O container tools é um container que tem as ferramentas básicas de interação com o HSM compiladas e executadas no próprio container. Alguns trechos dos scripts da test network intercalam chamadas às ferramentas compiladas localmente (na máquina local) e execuções destas ferramentas do container.

Gerar imagens com suporte a PKCS#11

Os Dockerfiles abaixo estão no path $GOPATH/src/github.com/hyperledger/fabric/images/.

  1. Editar os arquivos Dockerfile do peer e do orderer para serem compilados com Ubuntu e com suporte à PKCS#11.

    # Copyright IBM Corp. All Rights Reserved.
    #
    # SPDX-License-Identifier: Apache-2.0
    
    ARG GO_VER
    ARG ALPINE_VER
    
    FROM ubuntu:jammy as peer-base
    
    # Latest debian url of DINAMO client
    ENV HSM_CLIENT_URL "https://downloads.dinamonetworks.io/bin/client/linux/x64/4.7.35/dinamo-4.7.35-1.x64.deb"
    ENV DEBIAN_FRONTEND noninteractive
    
    RUN apt-get update -y && \
      apt-get install -y tzdata
    
    # Bugfix https://github.com/hyperledger/fabric/issues/3779
    RUN if [[ ! -e /etc/nsswitch.conf ]] ; then echo 'hosts: files dns' > /etc/nsswitch.conf ; fi
    
    RUN apt-get install -y \
      bash \
      binutils-gold \
      gcc \
      git \
      make \
      musl-dev \
      curl
    
    RUN curl -L $HSM_CLIENT_URL -o /tmp/dinamo.deb
    RUN apt-get install -y /tmp/dinamo.deb
    RUN rm /tmp/dinamo.deb
    
    FROM golang:latest as golang
    ADD . $GOPATH/src/github.com/hyperledger/fabric
    WORKDIR $GOPATH/src/github.com/hyperledger/fabric
    
    FROM golang as peer
    ARG GO_TAGS
    #Bugfix https://github.com/hyperledger/fabric/issues/3645
    RUN make peer GO_TAGS=${GO_TAGS}
    RUN make ccaasbuilder
    RUN \
        export MARCH=$(go env GOOS)-$(go env GOARCH) && \
        mkdir -p release/linux-platform && \
        cp -r release/${MARCH}/builders release/linux-platform/.
    
    FROM peer-base
    ENV FABRIC_CFG_PATH /etc/hyperledger/fabric
    VOLUME /etc/hyperledger/fabric
    VOLUME /var/hyperledger
    COPY --from=peer /go/src/github.com/hyperledger/fabric/build/bin /usr/local/bin
    COPY --from=peer /go/src/github.com/hyperledger/fabric/sampleconfig/msp ${FABRIC_CFG_PATH}/msp
    COPY --from=peer /go/src/github.com/hyperledger/fabric/sampleconfig/core.yaml ${FABRIC_CFG_PATH}/core.yaml
    COPY --from=peer /go/src/github.com/hyperledger/fabric/release/linux-platform/builders/ccaas/bin/ /opt/hyperledger/ccaas_builder/bin/
    EXPOSE 7051
    CMD ["peer","node","start"]
    
    # Copyright IBM Corp. All Rights Reserved.
    #
    # SPDX-License-Identifier: Apache-2.0
    
    ARG GO_VER
    ARG ALPINE_VER
    FROM ubuntu:jammy as base
    
    # Latest debian url of DINAMO client
    ENV HSM_CLIENT_URL "https://downloads.dinamonetworks.io/bin/client/linux/x64/4.7.35/dinamo-4.7.35-1.x64.deb"
    ENV GO_URL "https://storage.googleapis.com/golang/go1.19.3.linux-amd64.tar.gz"
    ENV DEBIAN_FRONTEND noninteractive
    
    RUN apt-get update -y && \
      apt-get install -y tzdata
    
    # Bugfix https://github.com/hyperledger/fabric/issues/3779
    RUN if [[ ! -e /etc/nsswitch.conf ]] ; then echo 'hosts: files dns' > /etc/nsswitch.conf ; fi
    
    RUN apt-get install -y \
      bash \
      binutils-gold \
      gcc \
      git \
      make \
      musl-dev \
      curl
    
    RUN curl -L $HSM_CLIENT_URL -o /tmp/dinamo.deb
    RUN apt-get install -y /tmp/dinamo.deb
    RUN rm /tmp/dinamo.deb
    
    FROM golang:latest as golang
    ADD . $GOPATH/src/github.com/hyperledger/fabric
    WORKDIR $GOPATH/src/github.com/hyperledger/fabric
    
    FROM golang as orderer
    ARG GO_TAGS
    #Bugfix https://github.com/hyperledger/fabric/issues/3645
    RUN make orderer GO_TAGS=${GO_TAGS}
    
    FROM base
    ENV FABRIC_CFG_PATH /etc/hyperledger/fabric
    VOLUME /etc/hyperledger/fabric
    VOLUME /var/hyperledger
    COPY --from=orderer /go/src/github.com/hyperledger/fabric/build/bin /usr/local/bin
    COPY --from=orderer /go/src/github.com/hyperledger/fabric/sampleconfig/msp ${FABRIC_CFG_PATH}/msp
    COPY --from=orderer /go/src/github.com/hyperledger/fabric/sampleconfig/orderer.yaml ${FABRIC_CFG_PATH}
    COPY --from=orderer /go/src/github.com/hyperledger/fabric/sampleconfig/configtx.yaml ${FABRIC_CFG_PATH}
    EXPOSE 7050
    CMD ["orderer"]
    
  2. Configurar o Dockerfile de tools para utilizar o client do HSM.

     # Copyright IBM Corp. All Rights Reserved.
     #
     # SPDX-License-Identifier: Apache-2.0
    
     ARG GO_VER
     ARG ALPINE_VER
    
     FROM golang:latest as tools
     ARG GO_TAGS
    
     ADD . $GOPATH/src/github.com/hyperledger/fabric
     WORKDIR $GOPATH/src/github.com/hyperledger/fabric
    
     #Bugfix https://github.com/hyperledger/fabric/issues/3645
     RUN make tools GO_TAGS=${GO_TAGS}
    
     FROM ubuntu:jammy
    
     # Latest debian url of DINAMO client
     ENV HSM_CLIENT_URL "https://downloads.dinamonetworks.io/bin/client/linux/x64/4.7.35/dinamo-4.7.35-1.x64.deb"
     ENV DEBIAN_FRONTEND noninteractive
    
     # git is required to support `go list -m`
     RUN apt-get update -y && \
       apt-get install -y \
       bash \
       binutils-gold \
       gcc \
       git \
       make \
       jq \
       tzdata \
       curl \
       musl-dev;
    
     RUN curl -L $HSM_CLIENT_URL -o /tmp/dinamo.deb
     RUN apt-get install -y /tmp/dinamo.deb
     RUN rm /tmp/dinamo.deb
    
     ENV FABRIC_CFG_PATH /etc/hyperledger/fabric
     VOLUME /etc/hyperledger/fabric
     COPY --from=tools /go/src/github.com/hyperledger/fabric/build/bin /usr/local/bin
     COPY --from=tools /go/src/github.com/hyperledger/fabric/sampleconfig ${FABRIC_CFG_PATH}
    
  3. Compilar as imagens do peer, orderer e tools.

    cd $GOPATH/src/github.com/hyperledger/fabric/
    make  clean-all
    make docker GO_TAGS=pkcs11
    

Configurar a test network

  1. Criar os arquivos de configuração fabric-ca-client-config.yaml dos peers.

    Usar como base o arquivo de configuração gerado em fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/fabric-ca-client-config.yaml e fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/fabric-ca-client-config.yaml.

    Estes arquivos são temporários e gerados a cada execução. Eles são removidos ao parar a test-network. Eles podem ser gerados, iniciando o a test-network (mesmo que com erros). Para acelerar o processo de geração é possível parar com CTRL-C logo após a geração das identidades do Peer2 ou logo ao iniciar a geração das identidades do Orderer.

      ./start-fabric.sh
    
      /mnt/d/tmp/hyperledger/fabric-samples/test-network /mnt/d/tmp/hyperledger
      Using docker and docker-compose
      Creating channel 'mychannel'.
    
      ...
    
      Creating Orderer Org Identities
      Enrolling the CA admin
      + fabric-ca-client enroll -u https://admin:adminpw@localhost:9054 --caname ca-orderer --tls.certfiles /mnt/d/tmp/hyperledger/fabric-samples/test-network/organizations/fabric-ca/ordererOrg/tls-cert.pem
    
      >>> CTRL-C <<<
    
  2. Criar uma pasta para cada organização com os nomes de org1 e org2 na pasta fabric-samples/test-network e fazer uma cópia do arquivo fabric-ca-client-config.yaml para a pasta da respectiva organização.

    cd fabric-samples/test-network
    mkdir org1
    cp organizations/peerOrganizations/org1.example.com/fabric-ca-client-config.yaml org1
    mkdir org2
    cp organizations/peerOrganizations/org2.example.com/fabric-ca-client-config.yaml org2
    cd ../..
    ./stop-fabric.sh
    

    Lembrar de parar o serviço com ./stop-fabric.sh após a cópia dos arquivos, para finalizar corretamente a test-network.

  3. Alterar a seção bccsp com as configurações da PKCS#11, do arquivo fabric-ca-client-config.yaml de cada organização, como a seguir.

    bccsp:
        default: PKCS11
        PKCS11:
            Library: /usr/lib/libtacndp11.so
            Pin: 12345678
            Label: "Dinamo HSM"
            hash: SHA2
            security: 256
            Immutable: false
    
  4. Alterar a chave bccsp do o arquivo de configuração do orderer.

    bccsp:
        default: PKCS11
        PKCS11:
            Library: /usr/lib/libtacndp11.so
            Pin: 12345678
            Label: "Dinamo HSM"
            hash: SHA2
            security: 256
            Immutable: false
    
  5. Configurar as variáveis de ambiente do client do HSM no arquivo compose da ca compose-ca.yaml.

    Este arquivo se encontra no path fabric-samples/test-network/compose/compose-ca.yaml.

    Neste caso estamos configurando o orderer, incluir as variáveis na sua respectiva seção, como abaixo.

    Utilizar um usuário do HSM diferente por orderer.

    services:
    
      ca_orderer:
        ...
        environment:
          ...
          - DFENCE_PKCS11_IP=host.docker.internal # IP do HSM
          - DFENCE_PKCS11_USER=caorderer               # Usuário do HSM
          - DFENCE_PKCS11_AUTO_RECONNECT=1
    
  6. Adicionar as configurações do client do HSM para os peers, no arquivo fabric-samples/test-network/compose/docker/docker-compose-test-net.yaml.

    Adicionar as variáveis de ambiente de configuração do client do HSM para cada peer, peer0.org1.example.com e peer0.org2.example.com, como no exemplo abaixo.

    services:
      peer0.org1.example.com:
        ...
        environment:
          ...
          - DFENCE_PKCS11_IP=host.docker.internal
          - DFENCE_PKCS11_USER=peer1
          - DFENCE_PKCS11_AUTO_RECONNECT=1
          ...
    peer0.org2.example.com:
        ...
        environment:
          ...
          - DFENCE_PKCS11_IP=host.docker.internal
          - DFENCE_PKCS11_USER=peer2
          - DFENCE_PKCS11_AUTO_RECONNECT=1
    
  7. Configurar a PKCS#11 no arquivo fabric-samples/test-network/compose/compose-test-net.yaml. Como no exemplo abaixo.

    services:
      peer0.org1.example.com:
        ...
        environment:
          ...
          - DFENCE_PKCS11_IP=host.docker.internal
          - DFENCE_PKCS11_USER=peer1
          - DFENCE_PKCS11_AUTO_RECONNECT=1
          ...
    peer0.org2.example.com:
        ...
        environment:
          ...
          - DFENCE_PKCS11_IP=host.docker.internal
          - DFENCE_PKCS11_USER=peer2
          - DFENCE_PKCS11_AUTO_RECONNECT=1
    
  8. Adicionar as configurações de client e habilitar PKCS#11 no arquivo fabric-samples/test-network/network.sh.

    Na função createOrgs incluir as configurações antes de cada chamada a createOrg1 e createOrg2, como a seguir.

    .
    .
    .
    infoln "Creating Org1 Identities"
    
        export DFENCE_PKCS11_IP=127.0.0.1
        export DFENCE_PKCS11_USER=peer1
        export DFENCE_PKCS11_AUTO_RECONNECT=1
        export HSM_LOG_DIR=/mnt/d/tmp/hyperledger
        export HSM_LOG_LEVEL=3
        export FABRIC_CA_CLIENT_BCCSP_DEFAULT=PKCS11
        export FABRIC_CA_CLIENT_BCCSP_PKCS11_LIBRARY=/usr/lib/libtacndp11.so
        export FABRIC_CA_CLIENT_BCCSP_PKCS11_PIN=12345678
        export FABRIC_CA_CLIENT_BCCSP_PKCS11_LABEL="Dinamo HSM"
        export FABRIC_CA_CLIENT_BCCSP_PKCS11_IMMUTABLE=false
        export FABRIC_CA_CLIENT_BCCSP_PKCS11_HASH=SHA2
        export FABRIC_CA_CLIENT_BCCSP_PKCS11_SECURITY=256
    
        createOrg1
    
        infoln "Creating Org2 Identities"
    
        export DFENCE_PKCS11_USER=peer2
    
        createOrg2
    
        unset DFENCE_PKCS11_IP
        unset DFENCE_PKCS11_USER
        unset DFENCE_PKCS11_AUTO_RECONNECT
        unset HSM_LOG_DIR
        unset HSM_LOG_LEVEL
        unset FABRIC_CA_CLIENT_BCCSP_DEFAULT
        unset FABRIC_CA_CLIENT_BCCSP_PKCS11_LIBRARY
        unset FABRIC_CA_CLIENT_BCCSP_PKCS11_PIN
        unset FABRIC_CA_CLIENT_BCCSP_PKCS11_LABEL
        unset FABRIC_CA_CLIENT_BCCSP_PKCS11_IMMUTABLE
        unset FABRIC_CA_CLIENT_BCCSP_PKCS11_HASH
        unset FABRIC_CA_CLIENT_BCCSP_PKCS11_SECURITY
    .
    .
    .
    
  9. Criar uma pasta para cada organização com os nomes de org1 e org2 na pasta fabric-samples/config e fazer uma cópia do arquivo core.yaml para a pasta da respectiva organização.

    cd fabric-samples/config
    mkdir org1
    cp ../test-network/compose/docker/peercfg/core.yaml org1
    mkdir org2
    cp ../test-network/compose/docker/peercfg/core.yaml org2
    cd ../..
    
    1. Configurar as opções de PKCS#11, alterando a seção bccsp, como a seguir, nos seguintes arquivos:

    • fabric-samples/test-network/compose/docker/peercfg/core.yaml
    • fabric-samples/config/org1/core.yaml
    • fabric-samples/config/org2/core.yaml
    .
    .
    .
     bccsp:
        default: PKCS11
        PKCS11:
            Library: /usr/lib/libtacndp11.so
            Pin: 12345678
            Label: "Dinamo HSM"
            hash: SHA2
            security: 256
            Immutable: false
    .
    .
    .
    
  10. Alterar o script fabric-samples/test-network/organizations/fabric-ca/registerEnroll.sh para utilizar PKCS#11 e usar os arquivos de configuração necessários.

    1. Editar as funções createOrg1 e createOrg2, com as seguintes alterações:

      1. Adicionar no início da função, abaixo da linha (export FABRIC_CA_CLIENT_HOME...), o código abaixo para habilitar o PKCS#11.

      2. Copiar o arquivo de configuração que será utilizado.

      export FABRIC_CA_CLIENT_BCCSP_DEFAULT=PKCS11
      cp ${PWD}/org1/fabric-ca-client-config.yaml $FABRIC_CA_CLIENT_HOME
      

      Alterar o caminho do arquivo de configuração fabric-ca-client-config.yaml de acordo com a organização utilizada, ex. org1/fabric-ca-client-config.yaml e org2/fabric-ca-client-config.yaml.

    2. Utilizar o BCCSP em software para a geração de certificado TLS do peer.

    Atualmente o Fabric não suporta PKCS#11 para uso em TLS.

    Selecionar o provedor em software logo antes de gerar o certificado TLS e habilitar novamente o PKCS#11 logo após a geração do certificado.

    1. Adicionar a linha:
       ```bash
       export FABRIC_CA_CLIENT_BCCSP_DEFAULT=SW
       ```
    
       logo após a linha:
    
       ```bash
       infoln "Generating the peer0-tls certificates"
       ```
    
    1. Adicionar a linha:
    
       ```bash
       export FABRIC_CA_CLIENT_BCCSP_DEFAULT=PKCS11
       ```
    
       logo após a linha:
    
       ```bash
       { set +x; } 2>/dev/null
       ```
    
  11. Alterar o arquivo fabric-samples/test-network/scripts/createChannel.sh com as configurações do client PKCS#11.

    1. Adicionar as configurações de PKCS#11 no início da função createChannel.
    export DFENCE_PKCS11_IP=127.0.0.1
    export DFENCE_PKCS11_USER=peer1
    export DFENCE_PKCS11_AUTO_RECONNECT=1
    
    1. Adicionar a seguinte linha no início da função joinChannel.
    export FABRIC_CA_CLIENT_BCCSP_DEFAULT=PKCS11
    
    1. Remover a seguinte linha no início da função joinChannel.

      FABRIC_CFG_PATH=$PWD/../config/
      

    2. Adicionar as configurações da PKCS#11 antes da chamada à função createChannelGenesisBlock.

    export DFENCE_PKCS11_IP=host.docker.internal
    export DFENCE_PKCS11_USER=peer1
    export DFENCE_PKCS11_AUTO_RECONNECT=1
    
    1. Adicionar a configuração do usuário e path para a configuração antes de cada chamada (joinChannel, setAnchorPeer) relativa a uma organização.

    2. Exemplo, peer1, adicionar as seguintes linhas, antes da chamada a joinChannel 1.

      export DFENCE_PKCS11_USER=peer1
      FABRIC_CFG_PATH="${PWD}/../config/org1"
      
    3. Exemplo, peer2, adicionar as seguintes linhas, antes da chamada a joinChannel 2, e assim sucessivamente.

      export DFENCE_PKCS11_USER=peer2
      FABRIC_CFG_PATH="${PWD}/../config/org2"
      
  12. Alterar o arquivo fabric-samples/test-network/scripts/deployCC.sh com as configurações de PKCS#11.

    1. No início do arquivo, logo após a impressão dos comandos em execução, por exemplo logo após a linha:
    println "- VERBOSE: ${C_GREEN}${VERBOSE}${C_RESET}"
    
    1. Sobrescrever a linha:
    FABRIC_CFG_PATH=$PWD/../config/
    

    Com as seguintes configurações:

    FABRIC_CFG_PATH=$PWD/../config/org1
    export DFENCE_PKCS11_IP=127.0.0.1
    export DFENCE_PKCS11_USER=peer1
    export DFENCE_PKCS11_AUTO_RECONNECT=1
    
    1. Adicionar a configuração de usuário PKCS#11 e configuração de acordo com cada chamada de função, referente a uma organização.

    2. Exemplo, peer1, adicionar as linhas:

      export DFENCE_PKCS11_USER=peer1
      FABRIC_CFG_PATH="${PWD}/../config/org1"
      

      antes da linha:

      installChaincode 1
      
    3. Exemplo, peer2, adicionar as linhas:

      export DFENCE_PKCS11_USER=peer2
      FABRIC_CFG_PATH="${PWD}/../config/org2"
      

      antes da linha abaixo, e assim sucessivamente.

      installChaincode 2
      
  13. Adicionar as configurações de PKCS#11 no arquivo fabric-samples/test-network/scripts/setAnchorPeer.sh.

    1. Adicionar as linhas abaixo, logo antes da chamada a createAnchorPeerUpdate.

    A variável $ORG recebe o valor 1 ou 2 de acordo com a chamada. No nosso exemplo o usuário do peer da organização 1 é o peer1 e da organização 2 peer2. Essa construção de nome permitiu fazer a seleção automática do usuário.

    export DFENCE_PKCS11_IP=host.docker.internal
    export DFENCE_PKCS11_USER=peer$ORG
    export DFENCE_PKCS11_AUTO_RECONNECT=1
    
  14. Criar script de teste básico com suporte à PKCS#11 test-p11-basic-transfer.sh. Configurar a PKCS#11 de acordo com cada organização.

    #!/bin/bash
    
    #
    #   Execute basic asset transfer test
    #
    
    pushd ./fabric-samples/test-network
    export PATH=${PWD}/../bin:$PATH
    export FABRIC_CFG_PATH=$PWD/../config/org1
    
    # Environment variables for Org1
    export CORE_PEER_TLS_ENABLED=true
    export CORE_PEER_LOCALMSPID="Org1MSP"
    export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
    export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp
    export CORE_PEER_ADDRESS=localhost:7051
    
    # PKCS#11 configurations for Org1
    export DFENCE_PKCS11_IP=127.0.0.1   # HSM IP Address
    export DFENCE_PKCS11_USER=peer1     # HSM User
    export DFENCE_PKCS11_AUTO_RECONNECT=1
    
    peer chaincode invoke -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --tls --cafile "${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem" -C mychannel -n basic --peerAddresses localhost:7051 --tlsRootCertFiles "${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt" --peerAddresses localhost:9051 --tlsRootCertFiles "${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt" -c '{"function":"InitLedger","Args":[]}'
    peer chaincode query -C mychannel -n basic -c '{"Args":["GetAllAssets"]}'
    peer chaincode invoke -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --tls --cafile "${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem" -C mychannel -n basic --peerAddresses localhost:7051 --tlsRootCertFiles "${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt" --peerAddresses localhost:9051 --tlsRootCertFiles "${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt" -c '{"function":"TransferAsset","Args":["asset6","Christopher"]}'
    
    # Environment variables for Org2
    export CORE_PEER_TLS_ENABLED=true
    export CORE_PEER_LOCALMSPID="Org2MSP"
    export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt
    export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp
    export CORE_PEER_ADDRESS=localhost:9051
    
    # PKCS#11 configurations for Org2
    export DFENCE_PKCS11_USER=peer2  # HSM User
    export FABRIC_CFG_PATH=$PWD/../config/org2
    
    peer chaincode query -C mychannel -n basic -c '{"Args":["ReadAsset","asset6"]}'
    popd
    

Subir a test network e executar um teste

  1. Para subir, executar os testes e depois parar a test net, use os seguintes scripts.

    ./start-fabric.sh
    ./test-p11-basic-transfer.sh
    ./test-p11-ca-client.sh
    ./stop-fabric.sh