github.com/adecaro/fabric-ca@v2.0.0-alpha+incompatible/docs/source/users-guide.rst (about) 1 Fabric CA User's Guide 2 ====================== 3 4 The Hyperledger Fabric CA is a Certificate Authority (CA) 5 for Hyperledger Fabric. 6 7 It provides features such as: 8 9 * registration of identities, or connects to LDAP as the user 10 registry 11 * issuance of Enrollment Certificates (ECerts) 12 * certificate renewal and revocation 13 14 Hyperledger Fabric CA consists of both a server and a client component as 15 described later in this document. 16 17 For developers interested in contributing to Hyperledger Fabric CA, see the 18 `Fabric CA repository <https://github.com/hyperledger/fabric-ca>`__ for more 19 information. 20 21 22 .. _Back to Top: 23 24 Table of Contents 25 ----------------- 26 27 1. `Overview`_ 28 29 2. `Getting Started`_ 30 31 1. `Prerequisites`_ 32 2. `Install`_ 33 3. `Explore the Fabric CA CLI`_ 34 35 3. `Configuration Settings`_ 36 37 1. `A word on file paths`_ 38 39 4. `Fabric CA Server`_ 40 41 1. `Initializing the server`_ 42 2. `Starting the server`_ 43 3. `Configuring the database`_ 44 4. `Configuring LDAP`_ 45 5. `Setting up a cluster`_ 46 6. `Setting up multiple CAs`_ 47 7. `Enrolling an intermediate CA`_ 48 8. `Upgrading the server`_ 49 9. `Operations Service`_ 50 51 5. `Fabric CA Client`_ 52 53 1. `Enrolling the bootstrap identity`_ 54 2. `Registering a new identity`_ 55 3. `Enrolling a peer identity`_ 56 4. `Getting Identity Mixer credential for a user`_ 57 5. `Getting Idemix CRI`_ 58 6. `Reenrolling an identity`_ 59 7. `Revoking a certificate or identity`_ 60 8. `Generating a CRL (Certificate Revocation List)`_ 61 9. `Attribute-Based Access Control`_ 62 10. `Dynamic Server Configuration Update`_ 63 11. `Enabling TLS`_ 64 12. `Contact specific CA instance`_ 65 66 6. `HSM`_ 67 68 1. `Configuring Fabric CA server to use softhsm2`_ 69 70 7. `File Formats`_ 71 72 1. `Fabric CA server's configuration file format`_ 73 2. `Fabric CA client's configuration file format`_ 74 75 8. `Troubleshooting`_ 76 77 78 Overview 79 -------- 80 81 The diagram below illustrates how the Hyperledger Fabric CA server fits into the 82 overall Hyperledger Fabric architecture. 83 84 .. image:: ./images/fabric-ca.png 85 86 There are two ways of interacting with a Hyperledger Fabric CA server: 87 via the Hyperledger Fabric CA client or through one of the Fabric SDKs. 88 All communication to the Hyperledger Fabric CA server is via REST APIs. 89 See `fabric-ca/swagger/swagger-fabric-ca.json` for the swagger documentation 90 for these REST APIs. 91 You may view this documentation via the http://editor2.swagger.io online editor. 92 93 The Hyperledger Fabric CA client or SDK may connect to a server in a cluster 94 of Hyperledger Fabric CA servers. This is illustrated in the top right section 95 of the diagram. The client routes to an HA Proxy endpoint which load balances 96 traffic to one of the fabric-ca-server cluster members. 97 98 All Hyperledger Fabric CA servers in a cluster share the same database for 99 keeping track of identities and certificates. If LDAP is configured, the identity 100 information is kept in LDAP rather than the database. 101 102 A server may contain multiple CAs. Each CA is either a root CA or an 103 intermediate CA. Each intermediate CA has a parent CA which is either a 104 root CA or another intermediate CA. 105 106 Getting Started 107 --------------- 108 109 Prerequisites 110 ~~~~~~~~~~~~~~~ 111 112 - Go 1.10+ installation 113 - ``GOPATH`` environment variable is set correctly 114 - libtool and libtdhl-dev packages are installed 115 116 The following installs the libtool dependencies on Ubuntu: 117 118 .. code:: bash 119 120 sudo apt install libtool libltdl-dev 121 122 The following installs the libtool dependencies on MacOSX: 123 124 .. code:: bash 125 126 brew install libtool 127 128 .. note:: libtldl-dev is not necessary on MacOSX if you instal 129 libtool via Homebrew 130 131 For more information on libtool, see https://www.gnu.org/software/libtool. 132 133 For more information on libltdl-dev, see https://www.gnu.org/software/libtool/manual/html_node/Using-libltdl.html. 134 135 Install 136 ~~~~~~~ 137 138 The following installs both the `fabric-ca-server` and `fabric-ca-client` binaries 139 in $GOPATH/bin. 140 141 .. code:: bash 142 143 go get -u github.com/hyperledger/fabric-ca/cmd/... 144 145 Note: If you have already cloned the fabric-ca repository, make sure you are on the 146 master branch before running the 'go get' command above. Otherwise, you might see the 147 following error: 148 149 :: 150 151 <gopath>/src/github.com/hyperledger/fabric-ca; git pull --ff-only 152 There is no tracking information for the current branch. 153 Please specify which branch you want to merge with. 154 See git-pull(1) for details. 155 156 git pull <remote> <branch> 157 158 If you wish to set tracking information for this branch you can do so with: 159 160 git branch --set-upstream-to=<remote>/<branch> tlsdoc 161 162 package github.com/hyperledger/fabric-ca/cmd/fabric-ca-client: exit status 1 163 164 Start Server Natively 165 ~~~~~~~~~~~~~~~~~~~~~ 166 167 The following starts the `fabric-ca-server` with default settings. 168 169 .. code:: bash 170 171 fabric-ca-server start -b admin:adminpw 172 173 The `-b` option provides the enrollment ID and secret for a bootstrap 174 administrator; this is required if LDAP is not enabled with the "ldap.enabled" 175 setting. 176 177 A default configuration file named `fabric-ca-server-config.yaml` 178 is created in the local directory which can be customized. 179 180 Start Server via Docker 181 ~~~~~~~~~~~~~~~~~~~~~~~ 182 183 Docker Hub 184 ^^^^^^^^^^^^ 185 186 Go to: https://hub.docker.com/r/hyperledger/fabric-ca/tags/ 187 188 Find the tag that matches the architecture and version of fabric-ca 189 that you want to pull. 190 191 Navigate to `$GOPATH/src/github.com/hyperledger/fabric-ca/docker/server` 192 and open up docker-compose.yml in an editor. 193 194 Change the `image` line to reflect the tag you found previously. The file 195 may look like this for an x86 architecture for version beta. 196 197 .. code:: yaml 198 199 fabric-ca-server: 200 image: hyperledger/fabric-ca:x86_64-1.0.0-beta 201 container_name: fabric-ca-server 202 ports: 203 - "7054:7054" 204 environment: 205 - FABRIC_CA_HOME=/etc/hyperledger/fabric-ca-server 206 volumes: 207 - "./fabric-ca-server:/etc/hyperledger/fabric-ca-server" 208 command: sh -c 'fabric-ca-server start -b admin:adminpw' 209 210 Open up a terminal in the same directory as the docker-compose.yml file 211 and execute the following: 212 213 .. code:: bash 214 215 # docker-compose up -d 216 217 This will pull down the specified fabric-ca image in the compose file 218 if it does not already exist, and start an instance of the fabric-ca 219 server. 220 221 Building Your Own Docker image 222 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 223 224 You can build and start the server via docker-compose as shown below. 225 226 .. code:: bash 227 228 cd $GOPATH/src/github.com/hyperledger/fabric-ca 229 make docker 230 cd docker/server 231 docker-compose up -d 232 233 The hyperledger/fabric-ca docker image contains both the fabric-ca-server and 234 the fabric-ca-client. 235 236 .. code:: bash 237 238 # cd $GOPATH/src/github.com/hyperledger/fabric-ca 239 # FABRIC_CA_DYNAMIC_LINK=true make docker 240 # cd docker/server 241 # docker-compose up -d 242 243 Explore the Fabric CA CLI 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 245 246 This section simply provides the usage messages for the Fabric CA server and client 247 for convenience. Additional usage information is provided in following sections. 248 249 The following links shows the :doc:`Server Command Line <servercli>` and 250 :doc:`Client Command Line <clientcli>`. 251 252 .. note:: Note that command line options that are string slices (lists) can be 253 specified either by specifying the option with comma-separated list 254 elements or by specifying the option multiple times, each with a 255 string value that make up the list. For example, to specify 256 ``host1`` and ``host2`` for the ``csr.hosts`` option, you can either 257 pass ``--csr.hosts 'host1,host2'`` or 258 ``--csr.hosts host1 --csr.hosts host2``. When using the former format, 259 please make sure there are no space before or after any commas. 260 261 `Back to Top`_ 262 263 Configuration Settings 264 ~~~~~~~~~~~~~~~~~~~~~~ 265 266 The Fabric CA provides 3 ways to configure settings on the Fabric CA server 267 and client. The precedence order is: 268 269 1. CLI flags 270 2. Environment variables 271 3. Configuration file 272 273 In the remainder of this document, we refer to making changes to 274 configuration files. However, configuration file changes can be 275 overridden through environment variables or CLI flags. 276 277 For example, if we have the following in the client configuration file: 278 279 .. code:: yaml 280 281 tls: 282 # Enable TLS (default: false) 283 enabled: false 284 285 # TLS for the client's listenting port (default: false) 286 certfiles: 287 client: 288 certfile: cert.pem 289 keyfile: 290 291 The following environment variable may be used to override the ``cert.pem`` 292 setting in the configuration file: 293 294 .. code:: bash 295 296 export FABRIC_CA_CLIENT_TLS_CLIENT_CERTFILE=cert2.pem 297 298 If we wanted to override both the environment variable and configuration 299 file, we can use a command line flag. 300 301 .. code:: bash 302 303 fabric-ca-client enroll --tls.client.certfile cert3.pem 304 305 The same approach applies to fabric-ca-server, except instead of using 306 ``FABIRC_CA_CLIENT`` as the prefix to environment variables, 307 ``FABRIC_CA_SERVER`` is used. 308 309 .. _server: 310 311 A word on file paths 312 ^^^^^^^^^^^^^^^^^^^^^ 313 All the properties in the Fabric CA server and client configuration file 314 that specify file names support both relative and absolute paths. 315 Relative paths are relative to the config directory, where the 316 configuration file is located. For example, if the config directory is 317 ``~/config`` and the tls section is as shown below, the Fabric CA server 318 or client will look for the ``root.pem`` file in the ``~/config`` 319 directory, ``cert.pem`` file in the ``~/config/certs`` directory and the 320 ``key.pem`` file in the ``/abs/path`` directory 321 322 .. code:: yaml 323 324 tls: 325 enabled: true 326 certfiles: 327 - root.pem 328 client: 329 certfile: certs/cert.pem 330 keyfile: /abs/path/key.pem 331 332 `Back to Top`_ 333 334 335 336 Fabric CA Server 337 ---------------- 338 339 This section describes the Fabric CA server. 340 341 You may initialize the Fabric CA server before starting it. This provides an 342 opportunity for you to generate a default configuration file that can be 343 reviewed and customized before starting the server. 344 345 The Fabric CA server's home directory is determined as follows: 346 - if the --home command line option is set, use its value 347 - otherwise, if the ``FABRIC_CA_SERVER_HOME`` environment variable is set, use 348 its value 349 - otherwise, if ``FABRIC_CA_HOME`` environment variable is set, use 350 its value 351 - otherwise, if the ``CA_CFG_PATH`` environment variable is set, use 352 its value 353 - otherwise, use current working directory 354 355 For the remainder of this server section, we assume that you have set 356 the ``FABRIC_CA_HOME`` environment variable to 357 ``$HOME/fabric-ca/server``. 358 359 The instructions below assume that the server configuration file exists 360 in the server's home directory. 361 362 .. _initialize: 363 364 Initializing the server 365 ~~~~~~~~~~~~~~~~~~~~~~~ 366 367 Initialize the Fabric CA server as follows: 368 369 .. code:: bash 370 371 fabric-ca-server init -b admin:adminpw 372 373 The ``-b`` (bootstrap identity) option is required for initialization when 374 LDAP is disabled. At least one bootstrap identity is required to start the 375 Fabric CA server; this identity is the server administrator. 376 377 The server configuration file contains a Certificate Signing Request (CSR) 378 section that can be configured. The following is a sample CSR. 379 380 .. _csr-fields: 381 382 .. code:: yaml 383 384 cn: fabric-ca-server 385 names: 386 - C: US 387 ST: "North Carolina" 388 L: 389 O: Hyperledger 390 OU: Fabric 391 hosts: 392 - host1.example.com 393 - localhost 394 ca: 395 expiry: 131400h 396 pathlength: 1 397 398 All of the fields above pertain to the X.509 signing key and certificate which 399 is generated by the ``fabric-ca-server init``. This corresponds to the 400 ``ca.certfile`` and ``ca.keyfile`` files in the server's configuration file. 401 The fields are as follows: 402 403 - **cn** is the Common Name 404 - **O** is the organization name 405 - **OU** is the organizational unit 406 - **L** is the location or city 407 - **ST** is the state 408 - **C** is the country 409 410 If custom values for the CSR are required, you may customize the configuration 411 file, delete the files specified by the ``ca.certfile`` and ``ca.keyfile`` 412 configuration items, and then run the ``fabric-ca-server init -b admin:adminpw`` 413 command again. 414 415 The ``fabric-ca-server init`` command generates a self-signed CA certificate 416 unless the ``-u <parent-fabric-ca-server-URL>`` option is specified. 417 If the ``-u`` is specified, the server's CA certificate is signed by the 418 parent Fabric CA server. 419 In order to authenticate to the parent Fabric CA server, the URL must 420 be of the form ``<scheme>://<enrollmentID>:<secret>@<host>:<port>``, where 421 <enrollmentID> and <secret> correspond to an identity with an 'hf.IntermediateCA' 422 attribute whose value equals 'true'. 423 The ``fabric-ca-server init`` command also generates a default configuration 424 file named **fabric-ca-server-config.yaml** in the server's home directory. 425 426 If you want the Fabric CA server to use a CA signing certificate and key file which you provide, 427 you must place your files in the location referenced by ``ca.certfile`` and ``ca.keyfile`` respectively. 428 Both files must be PEM-encoded and must not be encrypted. 429 More specifically, the contents of the CA certificate file must begin with ``-----BEGIN CERTIFICATE-----`` 430 and the contents of the key file must begin with ``-----BEGIN PRIVATE KEY-----`` and not 431 ``-----BEGIN ENCRYPTED PRIVATE KEY-----``. 432 433 Algorithms and key sizes 434 435 The CSR can be customized to generate X.509 certificates and keys that 436 support Elliptic Curve (ECDSA). The following setting is an 437 example of the implementation of Elliptic Curve Digital Signature 438 Algorithm (ECDSA) with curve ``prime256v1`` and signature algorithm 439 ``ecdsa-with-SHA256``: 440 441 .. code:: yaml 442 443 key: 444 algo: ecdsa 445 size: 256 446 447 The choice of algorithm and key size are based on security needs. 448 449 Elliptic Curve (ECDSA) offers the following key size options: 450 451 +--------+--------------+-----------------------+ 452 | size | ASN1 OID | Signature Algorithm | 453 +========+==============+=======================+ 454 | 256 | prime256v1 | ecdsa-with-SHA256 | 455 +--------+--------------+-----------------------+ 456 | 384 | secp384r1 | ecdsa-with-SHA384 | 457 +--------+--------------+-----------------------+ 458 | 521 | secp521r1 | ecdsa-with-SHA512 | 459 +--------+--------------+-----------------------+ 460 461 Starting the server 462 ~~~~~~~~~~~~~~~~~~~ 463 464 Start the Fabric CA server as follows: 465 466 .. code:: bash 467 468 fabric-ca-server start -b <admin>:<adminpw> 469 470 If the server has not been previously initialized, it will initialize 471 itself as it starts for the first time. During this initialization, the 472 server will generate the ca-cert.pem and ca-key.pem files if they don't 473 yet exist and will also create a default configuration file if it does 474 not exist. See the `Initialize the Fabric CA server <#initialize>`__ section. 475 476 Unless the Fabric CA server is configured to use LDAP, it must be 477 configured with at least one pre-registered bootstrap identity to enable you 478 to register and enroll other identities. The ``-b`` option specifies the 479 name and password for a bootstrap identity. 480 481 To cause the Fabric CA server to listen on ``https`` rather than 482 ``http``, set ``tls.enabled`` to ``true``. 483 484 SECURITY WARNING: The Fabric CA server should always be started with TLS 485 enabled (``tls.enabled`` set to true). Failure to do so leaves the 486 server vulnerable to an attacker with access to network traffic. 487 488 To limit the number of times that the same secret (or password) can be 489 used for enrollment, set the ``registry.maxenrollments`` in the configuration 490 file to the appropriate value. If you set the value to 1, the Fabric CA 491 server allows passwords to only be used once for a particular enrollment 492 ID. If you set the value to -1, the Fabric CA server places no limit on 493 the number of times that a secret can be reused for enrollment. The 494 default value is -1. Setting the value to 0, the Fabric CA server will 495 disable enrollment for all identities and registration of identities will 496 not be allowed. 497 498 The Fabric CA server should now be listening on port 7054. 499 500 You may skip to the `Fabric CA Client <#fabric-ca-client>`__ section if 501 you do not want to configure the Fabric CA server to run in a cluster or 502 to use LDAP. 503 504 Configuring the database 505 ~~~~~~~~~~~~~~~~~~~~~~~~ 506 507 This section describes how to configure the Fabric CA server to connect 508 to PostgreSQL or MySQL databases. The default database is SQLite and the 509 default database file is ``fabric-ca-server.db`` in the Fabric CA 510 server's home directory. 511 512 If you don't care about running the Fabric CA server in a cluster, you 513 may skip this section; otherwise, you must configure either PostgreSQL or 514 MySQL as described below. Fabric CA supports the following database 515 versions in a cluster setup: 516 517 - PostgreSQL: 9.5.5 or later 518 - MySQL: 5.7 or later 519 520 PostgreSQL 521 ^^^^^^^^^^ 522 523 The following sample may be added to the server's configuration file in 524 order to connect to a PostgreSQL database. Be sure to customize the 525 various values appropriately. There are limitations on what characters are allowed 526 in the database name. Please refer to the following Postgres documentation 527 for more information: https://www.postgresql.org/docs/current/static/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS 528 529 .. code:: yaml 530 531 db: 532 type: postgres 533 datasource: host=localhost port=5432 user=Username password=Password dbname=fabric_ca sslmode=verify-full 534 535 Specifying *sslmode* configures the type of SSL authentication. Valid 536 values for sslmode are: 537 538 | 539 540 +----------------+----------------+ 541 | Mode | Description | 542 +================+================+ 543 | disable | No SSL | 544 +----------------+----------------+ 545 | require | Always SSL | 546 | | (skip | 547 | | verification) | 548 +----------------+----------------+ 549 | verify-ca | Always SSL | 550 | | (verify that | 551 | | the | 552 | | certificate | 553 | | presented by | 554 | | the server was | 555 | | signed by a | 556 | | trusted CA) | 557 +----------------+----------------+ 558 | verify-full | Same as | 559 | | verify-ca AND | 560 | | verify that | 561 | | the | 562 | | certificate | 563 | | presented by | 564 | | the server was | 565 | | signed by a | 566 | | trusted CA and | 567 | | the server | 568 | | hostname | 569 | | matches the | 570 | | one in the | 571 | | certificate | 572 +----------------+----------------+ 573 574 | 575 576 If you would like to use TLS, then the ``db.tls`` section in the Fabric CA server 577 configuration file must be specified. If SSL client authentication is enabled 578 on the PostgreSQL server, then the client certificate and key file must also be 579 specified in the ``db.tls.client`` section. The following is an example 580 of the ``db.tls`` section: 581 582 .. code:: yaml 583 584 db: 585 ... 586 tls: 587 enabled: true 588 certfiles: 589 - db-server-cert.pem 590 client: 591 certfile: db-client-cert.pem 592 keyfile: db-client-key.pem 593 594 | **certfiles** - A list of PEM-encoded trusted root certificate files. 595 | **certfile** and **keyfile** - PEM-encoded certificate and key files that are used by the Fabric CA server to communicate securely with the PostgreSQL server 596 597 PostgreSQL SSL Configuration 598 """"""""""""""""""""""""""""" 599 600 **Basic instructions for configuring SSL on the PostgreSQL server:** 601 602 1. In postgresql.conf, uncomment SSL and set to "on" (SSL=on) 603 604 2. Place certificate and key files in the PostgreSQL data directory. 605 606 Instructions for generating self-signed certificates for: 607 https://www.postgresql.org/docs/9.5/static/ssl-tcp.html 608 609 Note: Self-signed certificates are for testing purposes and should not 610 be used in a production environment 611 612 **PostgreSQL Server - Require Client Certificates** 613 614 1. Place certificates of the certificate authorities (CAs) you trust in the file root.crt in the PostgreSQL data directory 615 616 2. In postgresql.conf, set "ssl\_ca\_file" to point to the root cert of the client (CA cert) 617 618 3. Set the clientcert parameter to 1 on the appropriate hostssl line(s) in pg\_hba.conf. 619 620 For more details on configuring SSL on the PostgreSQL server, please refer 621 to the following PostgreSQL documentation: 622 https://www.postgresql.org/docs/9.4/static/libpq-ssl.html 623 624 MySQL 625 ^^^^^^^ 626 627 The following sample may be added to the Fabric CA server configuration file in 628 order to connect to a MySQL database. Be sure to customize the various 629 values appropriately. There are limitations on what characters are allowed 630 in the database name. Please refer to the following MySQL documentation 631 for more information: https://dev.mysql.com/doc/refman/5.7/en/identifiers.html 632 633 On MySQL 5.7.X, certain modes affect whether the server permits '0000-00-00' as a valid date. 634 It might be necessary to relax the modes that MySQL server uses. We want to allow 635 the server to be able to accept zero date values. 636 637 In my.cnf, find the configuration option *sql_mode* and remove *NO_ZERO_DATE* if present. 638 Restart MySQL server after making this change. 639 640 Please refer to the following MySQL documentation on different modes available 641 and select the appropriate settings for the specific version of MySQL that is 642 being used. 643 644 https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html 645 646 .. code:: yaml 647 648 db: 649 type: mysql 650 datasource: root:rootpw@tcp(localhost:3306)/fabric_ca?parseTime=true&tls=custom 651 652 If connecting over TLS to the MySQL server, the ``db.tls.client`` 653 section is also required as described in the **PostgreSQL** section above. 654 655 MySQL SSL Configuration 656 """""""""""""""""""""""" 657 658 **Basic instructions for configuring SSL on MySQL server:** 659 660 1. Open or create my.cnf file for the server. Add or uncomment the 661 lines below in the [mysqld] section. These should point to the key and 662 certificates for the server, and the root CA cert. 663 664 Instructions on creating server and client-side certficates: 665 http://dev.mysql.com/doc/refman/5.7/en/creating-ssl-files-using-openssl.html 666 667 [mysqld] ssl-ca=ca-cert.pem ssl-cert=server-cert.pem ssl-key=server-key.pem 668 669 Can run the following query to confirm SSL has been enabled. 670 671 mysql> SHOW GLOBAL VARIABLES LIKE 'have\_%ssl'; 672 673 Should see: 674 675 +----------------+----------------+ 676 | Variable_name | Value | 677 +================+================+ 678 | have_openssl | YES | 679 +----------------+----------------+ 680 | have_ssl | YES | 681 +----------------+----------------+ 682 683 2. After the server-side SSL configuration is finished, the next step is 684 to create a user who has a privilege to access the MySQL server over 685 SSL. For that, log in to the MySQL server, and type: 686 687 mysql> GRANT ALL PRIVILEGES ON *.* TO 'ssluser'@'%' IDENTIFIED BY 688 'password' REQUIRE SSL; mysql> FLUSH PRIVILEGES; 689 690 If you want to give a specific IP address from which the user will 691 access the server change the '%' to the specific IP address. 692 693 **MySQL Server - Require Client Certificates** 694 695 Options for secure connections are similar to those used on the server side. 696 697 - ssl-ca identifies the Certificate Authority (CA) certificate. This 698 option, if used, must specify the same certificate used by the server. 699 - ssl-cert identifies MySQL server's certificate. 700 - ssl-key identifies MySQL server's private key. 701 702 Suppose that you want to connect using an account that has no special 703 encryption requirements or was created using a GRANT statement that 704 includes the REQUIRE SSL option. As a recommended set of 705 secure-connection options, start the MySQL server with at least 706 --ssl-cert and --ssl-key options. Then set the ``db.tls.certfiles`` property 707 in the server configuration file and start the Fabric CA server. 708 709 To require that a client certificate also be specified, create the 710 account using the REQUIRE X509 option. Then the client must also specify 711 proper client key and certificate files; otherwise, the MySQL server 712 will reject the connection. To specify client key and certificate files 713 for the Fabric CA server, set the ``db.tls.client.certfile``, 714 and ``db.tls.client.keyfile`` configuration properties. 715 716 Configuring LDAP 717 ~~~~~~~~~~~~~~~~ 718 719 The Fabric CA server can be configured to read from an LDAP server. 720 721 In particular, the Fabric CA server may connect to an LDAP server to do 722 the following: 723 724 - authenticate an identity prior to enrollment 725 - retrieve an identity's attribute values which are used for authorization. 726 727 Modify the LDAP section of the Fabric CA server's configuration file to configure the 728 server to connect to an LDAP server. 729 730 .. code:: yaml 731 732 ldap: 733 # Enables or disables the LDAP client (default: false) 734 enabled: false 735 # The URL of the LDAP server 736 url: <scheme>://<adminDN>:<adminPassword>@<host>:<port>/<base> 737 userfilter: <filter> 738 attribute: 739 # 'names' is an array of strings that identify the specific attributes 740 # which are requested from the LDAP server. 741 names: <LDAPAttrs> 742 # The 'converters' section is used to convert LDAP attribute values 743 # to fabric CA attribute values. 744 # 745 # For example, the following converts an LDAP 'uid' attribute 746 # whose value begins with 'revoker' to a fabric CA attribute 747 # named "hf.Revoker" with a value of "true" (because the expression 748 # evaluates to true). 749 # converters: 750 # - name: hf.Revoker 751 # value: attr("uid") =~ "revoker*" 752 # 753 # As another example, assume a user has an LDAP attribute named 754 # 'member' which has multiple values of "dn1", "dn2", and "dn3". 755 # Further assume the following configuration. 756 # converters: 757 # - name: myAttr 758 # value: map(attr("member"),"groups") 759 # maps: 760 # groups: 761 # - name: dn1 762 # value: orderer 763 # - name: dn2 764 # value: peer 765 # The value of the user's 'myAttr' attribute is then computed to be 766 # "orderer,peer,dn3". This is because the value of 'attr("member")' is 767 # "dn1,dn2,dn3", and the call to 'map' with a 2nd argument of 768 # "group" replaces "dn1" with "orderer" and "dn2" with "peer". 769 converters: 770 - name: <fcaAttrName> 771 value: <fcaExpr> 772 maps: 773 <mapName>: 774 - name: <from> 775 value: <to> 776 777 Where: 778 779 * ``scheme`` is one of *ldap* or *ldaps*; 780 * ``adminDN`` is the distinquished name of the admin user; 781 * ``pass`` is the password of the admin user; 782 * ``host`` is the hostname or IP address of the LDAP server; 783 * ``port`` is the optional port number, where default 389 for *ldap* 784 and 636 for *ldaps*; 785 * ``base`` is the optional root of the LDAP tree to use for searches; 786 * ``filter`` is a filter to use when searching to convert a login 787 user name to a distinguished name. For example, a value of 788 ``(uid=%s)`` searches for LDAP entries with the value of a ``uid`` 789 attribute whose value is the login user name. Similarly, 790 ``(email=%s)`` may be used to login with an email address. 791 * ``LDAPAttrs`` is an array of LDAP attribute names to request from the 792 LDAP server on a user's behalf; 793 * the attribute.converters section is used to convert LDAP attributes to fabric 794 CA attributes, where 795 * ``fcaAttrName`` is the name of a fabric CA attribute; 796 * ``fcaExpr`` is an expression whose evaluated value is assigned to the fabric CA attribute. 797 For example, suppose that <LDAPAttrs> is ["uid"], <fcaAttrName> is 'hf.Revoker', 798 and <fcaExpr> is 'attr("uid") =~ "revoker*"'. This means that an attribute 799 named "uid" is requested from the LDAP server on a user's behalf. The user is 800 then given a value of 'true' for the 'hf.Revoker' attribute if the value of 801 the user's 'uid' LDAP attribute begins with 'revoker'; otherwise, the user 802 is given a value of 'false' for the 'hf.Revoker' attribute. 803 * the attribute.maps section is used to map LDAP response values. The typical 804 use case is to map a distinguished name associated with an LDAP group to an 805 identity type. 806 807 The LDAP expression language uses the govaluate package as described at 808 https://github.com/Knetic/govaluate/blob/master/MANUAL.md. This defines 809 operators such as "=~" and literals such as "revoker*", which is a regular 810 expression. The LDAP-specific variables and functions which extend the 811 base govaluate language are as follows: 812 813 * ``DN`` is a variable equal to the user's distinguished name. 814 * ``affiliation`` is a variable equal to the user's affiliation. 815 * ``attr`` is a function which takes 1 or 2 arguments. The 1st argument 816 is an LDAP attribute name. The 2nd argument is a separator string which is 817 used to join multiple values into a single string; the default separator 818 string is ",". The ``attr`` function always returns a value of type 819 'string'. 820 * ``map`` is a function which takes 2 arguments. The 1st argument 821 is any string. The second argument is the name of a map which is used to 822 perform string substitution on the string from the 1st argument. 823 * ``if`` is a function which takes a 3 arguments where the first argument 824 must resolve to a boolean value. If it evaluates to true, the second 825 argument is returned; otherwise, the third argument is returned. 826 827 For example, the following expression evaluates to true if the user has 828 a distinguished name ending in "O=org1,C=US", or if the user has an affiliation 829 beginning with "org1.dept2." and also has the "admin" attribute of "true". 830 831 **DN =~ "*O=org1,C=US" || (affiliation =~ "org1.dept2.*" && attr('admin') = 'true')** 832 833 NOTE: Since the ``attr`` function always returns a value of type 'string', 834 numeric operators may not be used to construct expressions. 835 For example, the following is NOT a valid expression: 836 837 .. code:: yaml 838 839 value: attr("gidNumber) >= 10000 && attr("gidNumber) < 10006 840 841 Alternatively, a regular expression enclosed in quotes as shown below may be used 842 to return an equivalent result: 843 844 .. code:: yaml 845 846 value: attr("gidNumber") =~ "1000[0-5]$" || attr("mail") == "root@example.com" 847 848 The following is a sample configuration section for the default setting 849 for the OpenLDAP server whose docker image is at 850 ``https://github.com/osixia/docker-openldap``. 851 852 .. code:: yaml 853 854 ldap: 855 enabled: true 856 url: ldap://cn=admin,dc=example,dc=org:admin@localhost:10389/dc=example,dc=org 857 userfilter: (uid=%s) 858 859 See ``FABRIC_CA/scripts/run-ldap-tests`` for a script which starts an 860 OpenLDAP docker image, configures it, runs the LDAP tests in 861 ``FABRIC_CA/cli/server/ldap/ldap_test.go``, and stops the OpenLDAP 862 server. 863 864 When LDAP is configured, enrollment works as follows: 865 866 867 - The Fabric CA client or client SDK sends an enrollment request with a 868 basic authorization header. 869 - The Fabric CA server receives the enrollment request, decodes the 870 identity name and password in the authorization header, looks up the DN (Distinguished 871 Name) associated with the identity name using the "userfilter" from the 872 configuration file, and then attempts an LDAP bind with the identity's 873 password. If the LDAP bind is successful, the enrollment processing is 874 authorized and can proceed. 875 876 Setting up a cluster 877 ~~~~~~~~~~~~~~~~~~~~ 878 879 You may use any IP sprayer to load balance to a cluster of Fabric CA 880 servers. This section provides an example of how to set up Haproxy to 881 route to a Fabric CA server cluster. Be sure to change hostname and port 882 to reflect the settings of your Fabric CA servers. 883 884 haproxy.conf 885 886 .. code:: 887 888 global 889 maxconn 4096 890 daemon 891 892 defaults 893 mode http 894 maxconn 2000 895 timeout connect 5000 896 timeout client 50000 897 timeout server 50000 898 899 listen http-in 900 bind *:7054 901 balance roundrobin 902 server server1 hostname1:port 903 server server2 hostname2:port 904 server server3 hostname3:port 905 906 907 Note: If using TLS, need to use ``mode tcp``. 908 909 Setting up multiple CAs 910 ~~~~~~~~~~~~~~~~~~~~~~~ 911 912 The fabric-ca server by default consists of a single default CA. However, additional CAs 913 can be added to a single server by using `cafiles` or `cacount` configuration options. 914 Each additional CA will have its own home directory. 915 916 cacount: 917 ^^^^^^^^ 918 919 The `cacount` provides a quick way to start X number of default additional 920 CAs. The home directory will be relative to the server directory. With this option, 921 the directory structure will be as follows: 922 923 .. code:: yaml 924 925 --<Server Home> 926 |--ca 927 |--ca1 928 |--ca2 929 930 Each additional CA will get a default configuration file generated in it's home 931 directory, within the configuration file it will contain a unique CA name. 932 933 For example, the following command will start 2 default CA instances: 934 935 .. code:: bash 936 937 fabric-ca-server start -b admin:adminpw --cacount 2 938 939 cafiles: 940 ^^^^^^^^ 941 942 If absolute paths are not provided when using the cafiles configuration option, 943 the CA home directory will be relative to the server directory. 944 945 To use this option, CA configuration files must have already been generated and 946 configured for each CA that is to be started. Each configuration file must have 947 a unique CA name and Common Name (CN), otherwise the server will fail to start as these 948 names must be unique. The CA configuration files will override any default 949 CA configuration, and any missing options in the CA configuration files will be 950 replaced by the values from the default CA. 951 952 The precedence order will be as follows: 953 954 1. CA Configuration file 955 2. Default CA CLI flags 956 3. Default CA Environment variables 957 4. Default CA Configuration file 958 959 A CA configuration file must contain at least the following: 960 961 .. code:: yaml 962 963 ca: 964 # Name of this CA 965 name: <CANAME> 966 967 csr: 968 cn: <COMMONNAME> 969 970 You may configure your directory structure as follows: 971 972 .. code:: yaml 973 974 --<Server Home> 975 |--ca 976 |--ca1 977 |-- fabric-ca-config.yaml 978 |--ca2 979 |-- fabric-ca-config.yaml 980 981 For example, the following command will start two customized CA instances: 982 983 .. code:: bash 984 985 fabric-ca-server start -b admin:adminpw --cafiles ca/ca1/fabric-ca-config.yaml 986 --cafiles ca/ca2/fabric-ca-config.yaml 987 988 989 Enrolling an intermediate CA 990 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 991 992 In order to create a CA signing certificate for an intermediate CA, the intermediate 993 CA must enroll with a parent CA in the same way that a fabric-ca-client enrolls with a CA. 994 This is done by using the -u option to specify the URL of the parent CA and the enrollment ID 995 and secret as shown below. The identity associated with this enrollment ID must have an 996 attribute with a name of "hf.IntermediateCA" and a value of "true". The CN (or Common Name) 997 of the issued certificate will be set to the enrollment ID. An error will occur if an intermediate 998 CA tries to explicitly specify a CN value. 999 1000 .. code:: bash 1001 1002 fabric-ca-server start -b admin:adminpw -u http://<enrollmentID>:<secret>@<parentserver>:<parentport> 1003 1004 For other intermediate CA flags see `Fabric CA server's configuration file format`_ section. 1005 1006 1007 Upgrading the server 1008 ~~~~~~~~~~~~~~~~~~~~ 1009 1010 The Fabric CA server must be upgraded before upgrading the Fabric CA client. 1011 Prior to upgrade, it is suggested that the current database be backed up: 1012 1013 - If using sqlite3, backup the current database file (which is named fabric-ca-server.db by default). 1014 - For other database types, use the appropriate backup/replication mechanism. 1015 1016 To upgrade a single instance of Fabric CA server: 1017 1018 1. Stop the fabric-ca-server process. 1019 2. Ensure the current database is backed up. 1020 3. Replace previous fabric-ca-server binary with the upgraded version. 1021 4. Launch the fabric-ca-server process. 1022 5. Verify the fabric-ca-server process is available with the following 1023 command where <host> is the hostname on which the server was started:: 1024 1025 fabric-ca-client getcainfo -u http://<host>:7054 1026 1027 Upgrading a cluster: 1028 ^^^^^^^^^^^^^^^^^^^^ 1029 To upgrade a cluster of fabric-ca-server instances using either a MySQL or Postgres database, perform the following procedure. We assume that you are using haproxy to load balance to two fabric-ca-server cluster members on host1 and host2, respectively, both listening on port 7054. After this procedure, you will be load balancing to upgraded fabric-ca-server cluster members on host3 and host4 respectively, both listening on port 7054. 1030 1031 In order to monitor the changes using haproxy stats, enable statistics collection. Add the following lines to the global section of the haproxy configuration file: 1032 1033 :: 1034 1035 stats socket /var/run/haproxy.sock mode 666 level operator 1036 stats timeout 2m 1037 1038 Restart haproxy to pick up the changes:: 1039 1040 # haproxy -f <configfile> -st $(pgrep haproxy) 1041 1042 To display summary information from the haproxy "show stat" command, the following function may prove useful for parsing the copious amount of CSV data returned: 1043 1044 .. code:: bash 1045 1046 haProxyShowStats() { 1047 echo "show stat" | nc -U /var/run/haproxy.sock |sed '1s/^# *//'| 1048 awk -F',' -v fmt="%4s %12s %10s %6s %6s %4s %4s\n" ' 1049 { if (NR==1) for (i=1;i<=NF;i++) f[tolower($i)]=i } 1050 { printf fmt, $f["sid"],$f["pxname"],$f["svname"],$f["status"], 1051 $f["weight"],$f["act"],$f["bck"] }' 1052 } 1053 1054 1055 1) Initially your haproxy configuration file is similar to the following:: 1056 1057 server server1 host1:7054 check 1058 server server2 host2:7054 check 1059 1060 Change this configuration to the following:: 1061 1062 server server1 host1:7054 check backup 1063 server server2 host2:7054 check backup 1064 server server3 host3:7054 check 1065 server server4 host4:7054 check 1066 1067 2) Restart the HA proxy with the new configuration as follows:: 1068 1069 haproxy -f <configfile> -st $(pgrep haproxy) 1070 1071 ``"haProxyShowStats"`` will now reflect the modified configuration, 1072 with two active, older-version backup servers and two (yet to be started) upgraded servers:: 1073 1074 sid pxname svname status weig act bck 1075 1 fabric-cas server3 DOWN 1 1 0 1076 2 fabric-cas server4 DOWN 1 1 0 1077 3 fabric-cas server1 UP 1 0 1 1078 4 fabric-cas server2 UP 1 0 1 1079 1080 3) Install upgraded binaries of fabric-ca-server on host3 and host4. The new 1081 upgraded servers on host3 and host4 should be configured to use the same 1082 database as their older counterparts on host1 and host2. After starting 1083 the upgraded servers, the database will be automatically migrated. The 1084 haproxy will forward all new traffic to the upgraded servers, since they 1085 are not configured as backup servers. Verify using the ``"fabric-ca-client getcainfo"`` 1086 command that your cluster is still functioning appropriately before proceeding. 1087 Also, ``"haProxyShowStats"`` should now reflect that all servers are active, 1088 similar to the following:: 1089 1090 sid pxname svname status weig act bck 1091 1 fabric-cas server3 UP 1 1 0 1092 2 fabric-cas server4 UP 1 1 0 1093 3 fabric-cas server1 UP 1 0 1 1094 4 fabric-cas server2 UP 1 0 1 1095 1096 4) Stop the old servers on host1 and host2. Verify using the 1097 ``"fabric-ca-client getcainfo"`` command that your new cluster is still 1098 functioning appropriately before proceeding. Then remove the older 1099 server backup configuration from the haproxy configuration file, 1100 so that it looks similar to the following:: 1101 1102 server server3 host3:7054 check 1103 server server4 host4:7054 check 1104 1105 5) Restart the HA proxy with the new configuration as follows:: 1106 1107 haproxy -f <configfile> -st $(pgrep haproxy) 1108 1109 ``"haProxyShowStats"`` will now reflect the modified configuration, 1110 with two active servers which have been upgraded to the new version:: 1111 1112 sid pxname svname status weig act bck 1113 1 fabric-cas server3 UP 1 1 0 1114 2 fabric-cas server4 UP 1 1 0 1115 1116 1117 `Back to Top`_ 1118 1119 1120 Operations Service 1121 ~~~~~~~~~~~~~~~~~~~~ 1122 1123 The CA Server hosts an HTTP server that offers a RESTful “operations” API. This API 1124 is intended to be used by operators, not administrators or “users” of the network. 1125 1126 The API exposes the following capabilities: 1127 1128 Prometheus target for operational metrics (when configured) 1129 1130 Configuring the Operations Service 1131 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1132 1133 The operations service requires two basic pieces of configuration: 1134 1135 The **address** and **port** to listen on. 1136 The **TLS certificates** and **keys** to use for authentication and encryption. Note, **these 1137 certificates should be generated by a separate and dedicated CA**. Do not use a CA that 1138 has generated certificates for any organizations in any channels. 1139 1140 The CA server can be configurated in the ``operations`` section of server's configuration file: 1141 1142 .. code:: yaml 1143 1144 operations: 1145 # host and port for the operations server 1146 listenAddress: 127.0.0.1:9443 1147 1148 # TLS configuration for the operations endpoint 1149 tls: 1150 # TLS enabled 1151 enabled: true 1152 1153 # path to PEM encoded server certificate for the operations server 1154 cert: 1155 file: tls/server.crt 1156 1157 # path to PEM encoded server key for the operations server 1158 key: 1159 file: tls/server.key 1160 1161 # require client certificate authentication to access all resources 1162 clientAuthRequired: false 1163 1164 # paths to PEM encoded ca certificates to trust for client authentication 1165 clientRootCAs: 1166 files: [] 1167 1168 The ``listenAddress`` key defines the host and port that the operation server 1169 will listen on. If the server should listen on all addresses, the host portion 1170 can be omitted. 1171 1172 The ``tls`` section is used to indicate whether or not TLS is enabled for the 1173 operations service, the location of the service's certificate and private key, 1174 and the locations of certificate authority root certificates that should be 1175 trusted for client authentication. When ``clientAuthRequired`` is ``true``, 1176 clients will be required to provide a certificate for authentication. 1177 1178 Operations Security 1179 ^^^^^^^^^^^^^^^^^^^^^^ 1180 1181 As the operations service is focused on operations and intentionally unrelated 1182 to the Fabric network, it does not use the Membership Services Provider for 1183 access control. Instead, the operations service relies entirely on mutual TLS with 1184 client certificate authentication. 1185 1186 It is highly recommended to enable mutual TLS by setting the value of ``clientAuthRequired`` 1187 to ``true`` in production environments. With this configuration, clients are 1188 required to provide a valid certificate for authentication. If the client does 1189 not provide a certificate or the service cannot verify the client’s certificate, 1190 the request is rejected. Note that if ``clientAuthRequired`` is set to ``false``, 1191 clients do not need to provide a certificate; if they do, however, and the service 1192 cannot verify the certificate, then the request will be rejected. 1193 1194 When TLS is disabled, authorization is bypassed and any client that can 1195 connect to the operations endpoint will be able to use the API. 1196 1197 Metrics 1198 ^^^^^^^^^ 1199 1200 The Fabric CA exposes metrics that can provide insight into the behavior of the system. 1201 Operators and administrators can use this information to better understand how the system 1202 is performing over time. 1203 1204 Configuring Metrics 1205 ^^^^^^^^^^^^^^^^^^^^ 1206 1207 Fabric CA provides two ways to expose metrics: a **pull** model based on Prometheus 1208 and a **push** model based on StatsD. 1209 1210 Prometheus 1211 ^^^^^^^^^^^ 1212 1213 A typical Prometheus deployment scrapes metrics by requesting them from an HTTP 1214 endpoint exposed by instrumented targets. As Prometheus is responsible for 1215 requesting the metrics, it is considered a pull system. 1216 1217 When configured, a Fabric CA Server will present a ``/metrics`` resource 1218 on the operations service. To enable Prometheus, set the provider value in the 1219 server's configuration file to ``prometheus``. 1220 1221 .. code:: yaml 1222 1223 metrics: 1224 provider: prometheus 1225 1226 StatsD 1227 ^^^^^^^ 1228 1229 StatsD is a simple statistics aggregation daemon. Metrics are sent to a 1230 ``statsd`` daemon where they are collected, aggregated, and pushed to a backend 1231 for visualization and alerting. As this model requires instrumented processes 1232 to send metrics data to StatsD, this is considered a push system. 1233 1234 The CA Server can be configured to send metrics to StatsD by setting the metrics 1235 provider to ``statsd`` in the ``metrics`` section in servers' configuration filel. The ``statsd`` 1236 subsection must also be configured with the address of the StatsD daemon, the 1237 network type to use (``tcp`` or ``udp``), and how often to send the metrics. An 1238 optional ``prefix`` may be specified to help differentiate the source of the 1239 metrics --- for example, differentiating metrics coming from separate servers --- 1240 that would be prepended to all generated metrics. 1241 1242 .. code:: yaml 1243 1244 metrics: 1245 provider: statsd 1246 statsd: 1247 network: udp 1248 address: 127.0.0.1:8125 1249 writeInterval: 10s 1250 prefix: server-0 1251 1252 For a look at the different metrics that are generated, check out 1253 :doc:`metrics_reference`. 1254 1255 `Back to Top`_ 1256 1257 .. _client: 1258 1259 Fabric CA Client 1260 ---------------- 1261 1262 This section describes how to use the fabric-ca-client command. 1263 1264 The Fabric CA client's home directory is determined as follows: 1265 - if the --home command line option is set, use its value 1266 - otherwise, if the ``FABRIC_CA_CLIENT_HOME`` environment variable is set, use 1267 its value 1268 - otherwise, if the ``FABRIC_CA_HOME`` environment variable is set, 1269 use its value 1270 - otherwise, if the ``CA_CFG_PATH`` environment variable is set, use 1271 its value 1272 - otherwise, use ``$HOME/.fabric-ca-client`` 1273 1274 The instructions below assume that the client configuration file exists 1275 in the client's home directory. 1276 1277 Enrolling the bootstrap identity 1278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1279 1280 First, if needed, customize the CSR (Certificate Signing Request) section 1281 in the client configuration file. Note that ``csr.cn`` field must be set 1282 to the ID of the bootstrap identity. Default CSR values are shown below: 1283 1284 .. code:: yaml 1285 1286 csr: 1287 cn: <<enrollment ID>> 1288 key: 1289 algo: ecdsa 1290 size: 256 1291 names: 1292 - C: US 1293 ST: North Carolina 1294 L: 1295 O: Hyperledger Fabric 1296 OU: Fabric CA 1297 hosts: 1298 - <<hostname of the fabric-ca-client>> 1299 ca: 1300 pathlen: 1301 pathlenzero: 1302 expiry: 1303 1304 See `CSR fields <#csr-fields>`__ for description of the fields. 1305 1306 Then run ``fabric-ca-client enroll`` command to enroll the identity. For example, 1307 following command enrolls an identity whose ID is **admin** and password is **adminpw** 1308 by calling Fabric CA server that is running locally at 7054 port. 1309 1310 .. code:: bash 1311 1312 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin 1313 fabric-ca-client enroll -u http://admin:adminpw@localhost:7054 1314 1315 The enroll command stores an enrollment certificate (ECert), corresponding private key and CA 1316 certificate chain PEM files in the subdirectories of the Fabric CA client's ``msp`` directory. 1317 You will see messages indicating where the PEM files are stored. 1318 1319 Registering a new identity 1320 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1321 1322 The identity performing the register request must be currently enrolled, and 1323 must also have the proper authority to register the type of the identity that is being 1324 registered. 1325 1326 In particular, three authorization checks are made by the Fabric CA server 1327 during registration as follows: 1328 1329 1. The registrar (i.e. the invoker) must have the "hf.Registrar.Roles" attribute with a 1330 comma-separated list of values where one of the values equals the type of 1331 identity being registered; for example, if the registrar has the 1332 "hf.Registrar.Roles" attribute with a value of "peer,app,user", the registrar 1333 can register identities of type peer, app, and user, but not orderer. 1334 1335 2. The affiliation of the registrar must be equal to or a prefix of 1336 the affiliation of the identity being registered. For example, an registrar 1337 with an affiliation of "a.b" may register an identity with an affiliation 1338 of "a.b.c" but may not register an identity with an affiliation of "a.c". 1339 If root affiliation is required for an identity, then the affiliation request 1340 should be a dot (".") and the registrar must also have root affiliation. 1341 If no affiliation is specified in the registration request, the identity being 1342 registered will be given the affiliation of the registrar. 1343 1344 3. The registrar can register a user with attributes if all of the following conditions 1345 are satisfied: 1346 1347 - Registrar can register Fabric CA reserved attributes that have the prefix 'hf.' 1348 only if the registrar possesses the attribute and it is part of the value of the 1349 hf.Registrar.Attributes' attribute. Furthermore, if the attribute is of type list 1350 then the value of attribute being registered must be equal to or a subset of the 1351 value that the registrar has. If the attribute is of type boolean, the registrar 1352 can register the attribute only if the registrar's value for the attribute is 'true'. 1353 - Registering custom attributes (i.e. any attribute whose name does not begin with 'hf.') 1354 requires that the registrar has the 'hf.Registar.Attributes' attribute with the value of 1355 the attribute or pattern being registered. The only supported pattern is a string with 1356 a "*" at the end. For example, "a.b.*" is a pattern which matches all attribute names 1357 beginning with "a.b.". For example, if the registrar has hf.Registrar.Attributes=orgAdmin, 1358 then the only attribute which the registrar can add or remove from an identity is the 1359 'orgAdmin' attribute. 1360 - If the requested attribute name is 'hf.Registrar.Attributes', an additional 1361 check is performed to see if the requested values for this attribute are equal 1362 to or a subset of the registrar's values for 'hf.Registrar.Attributes'. For this 1363 to be true, each requested value must match a value in the registrar's value for 1364 'hf.Registrar.Attributes' attribute. For example, if the registrar's value for 1365 'hf.Registrar.Attributes' is 'a.b.*, x.y.z' and the requested attribute 1366 value is 'a.b.c, x.y.z', it is valid because 'a.b.c' matches 'a.b.*' and 'x.y.z' 1367 matches the registrar's 'x.y.z' value. 1368 1369 Examples: 1370 Valid Scenarios: 1371 1. If the registrar has the attribute 'hf.Registrar.Attributes = a.b.*, x.y.z' and 1372 is registering attribute 'a.b.c', it is valid 'a.b.c' matches 'a.b.*'. 1373 2. If the registrar has the attribute 'hf.Registrar.Attributes = a.b.*, x.y.z' and 1374 is registering attribute 'x.y.z', it is valid because 'x.y.z' matches the registrar's 1375 'x.y.z' value. 1376 3. If the registrar has the attribute 'hf.Registrar.Attributes = a.b.*, x.y.z' and 1377 the requested attribute value is 'a.b.c, x.y.z', it is valid because 'a.b.c' matches 1378 'a.b.*' and 'x.y.z' matches the registrar's 'x.y.z' value. 1379 4. If the registrar has the attribute 'hf.Registrar.Roles = peer,client' and 1380 the requested attribute value is 'peer' or 'peer,client', it is valid because 1381 the requested value is equal to or a subset of the registrar's value. 1382 1383 Invalid Scenarios: 1384 1. If the registrar has the attribute 'hf.Registrar.Attributes = a.b.*, x.y.z' and 1385 is registering attribute 'hf.Registar.Attributes = a.b.c, x.y.*', it is invalid 1386 because requested attribute 'x.y.*' is not a pattern owned by the registrar. The value 1387 'x.y.*' is a superset of 'x.y.z'. 1388 2. If the registrar has the attribute 'hf.Registrar.Attributes = a.b.*, x.y.z' and 1389 is registering attribute 'hf.Registar.Attributes = a.b.c, x.y.z, attr1', it is invalid 1390 because the registrar's 'hf.Registrar.Attributes' attribute values do not contain 'attr1'. 1391 3. If the registrar has the attribute 'hf.Registrar.Attributes = a.b.*, x.y.z' and 1392 is registering attribute 'a.b', it is invalid because the value 'a.b' is not contained in 1393 'a.b.*'. 1394 4. If the registrar has the attribute 'hf.Registrar.Attributes = a.b.*, x.y.z' and 1395 is registering attribute 'x.y', it is invalid because 'x.y' is not contained by 'x.y.z'. 1396 5. If the registrar has the attribute 'hf.Registrar.Roles = peer,client' and 1397 the requested attribute value is 'peer,client,orderer', it is invalid because 1398 the registrar does not have the orderer role in its value of hf.Registrar.Roles 1399 attribute. 1400 6. If the registrar has the attribute 'hf.Revoker = false' and the requested attribute 1401 value is 'true', it is invalid because the hf.Revoker attribute is a boolean attribute 1402 and the registrar's value for the attribute is not 'true'. 1403 1404 The table below lists all the attributes that can be registered for an identity. 1405 The names of attributes are case sensitive. 1406 1407 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1408 | Name | Type | Description | 1409 +=============================+============+============================================================================================================+ 1410 | hf.Registrar.Roles | List | List of roles that the registrar is allowed to manage | 1411 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1412 | hf.Registrar.DelegateRoles | List | List of roles that the registrar is allowed to give to a registree for its 'hf.Registrar.Roles' attribute | 1413 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1414 | hf.Registrar.Attributes | List | List of attributes that registrar is allowed to register | 1415 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1416 | hf.GenCRL | Boolean | Identity is able to generate CRL if attribute value is true | 1417 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1418 | hf.Revoker | Boolean | Identity is able to revoke a user and/or certificates if attribute value is true | 1419 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1420 | hf.AffiliationMgr | Boolean | Identity is able to manage affiliations if attribute value is true | 1421 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1422 | hf.IntermediateCA | Boolean | Identity is able to enroll as an intermediate CA if attribute value is true | 1423 +-----------------------------+------------+------------------------------------------------------------------------------------------------------------+ 1424 1425 Note: When registering an identity, you specify an array of attribute names and values. If the array 1426 specifies multiple array elements with the same name, only the last element is currently used. In other words, 1427 multi-valued attributes are not currently supported. 1428 1429 The following command uses the **admin** identity's credentials to register a new 1430 user with an enrollment id of "admin2", an affiliation of 1431 "org1.department1", an attribute named "hf.Revoker" with a value of "true", and 1432 an attribute named "admin" with a value of "true". The ":ecert" suffix means that 1433 by default the "admin" attribute and its value will be inserted into the user's 1434 enrollment certificate, which can then be used to make access control decisions. 1435 1436 .. code:: bash 1437 1438 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin 1439 fabric-ca-client register --id.name admin2 --id.affiliation org1.department1 --id.attrs 'hf.Revoker=true,admin=true:ecert' 1440 1441 The password, also known as the enrollment secret, is printed. 1442 This password is required to enroll the identity. 1443 This allows an administrator to register an identity and give the 1444 enrollment ID and the secret to someone else to enroll the identity. 1445 1446 Multiple attributes can be specified as part of the --id.attrs flag, each 1447 attribute must be comma separated. For an attribute value that contains a comma, 1448 the attribute must be encapsulated in double quotes. See example below. 1449 1450 .. code:: bash 1451 1452 fabric-ca-client register -d --id.name admin2 --id.affiliation org1.department1 --id.attrs '"hf.Registrar.Roles=peer,user",hf.Revoker=true' 1453 1454 or 1455 1456 .. code:: bash 1457 1458 fabric-ca-client register -d --id.name admin2 --id.affiliation org1.department1 --id.attrs '"hf.Registrar.Roles=peer,user"' --id.attrs hf.Revoker=true 1459 1460 You may set default values for any of the fields used in the register command 1461 by editing the client's configuration file. For example, suppose the configuration 1462 file contains the following: 1463 1464 .. code:: yaml 1465 1466 id: 1467 name: 1468 type: user 1469 affiliation: org1.department1 1470 maxenrollments: -1 1471 attributes: 1472 - name: hf.Revoker 1473 value: true 1474 - name: anotherAttrName 1475 value: anotherAttrValue 1476 1477 The following command would then register a new identity with an enrollment id of 1478 "admin3" which it takes from the command line, and the remainder is taken from the 1479 configuration file including the identity type: "user", affiliation: "org1.department1", 1480 and two attributes: "hf.Revoker" and "anotherAttrName". 1481 1482 .. code:: bash 1483 1484 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin 1485 fabric-ca-client register --id.name admin3 1486 1487 To register an identity with multiple attributes requires specifying all attribute names and values 1488 in the configuration file as shown above. 1489 1490 Setting `maxenrollments` to 0 or leaving it out from the configuration will result in the identity 1491 being registered to use the CA's max enrollment value. Furthermore, the max enrollment value for 1492 an identity being registered cannot exceed the CA's max enrollment value. For example, if the CA's 1493 max enrollment value is 5. Any new identity must have a value less than or equal to 5, and also 1494 can't set it to -1 (infinite enrollments). 1495 1496 Next, let's register a peer identity which will be used to enroll the peer in the following section. 1497 The following command registers the **peer1** identity. Note that we choose to specify our own 1498 password (or secret) rather than letting the server generate one for us. 1499 1500 .. code:: bash 1501 1502 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin 1503 fabric-ca-client register --id.name peer1 --id.type peer --id.affiliation org1.department1 --id.secret peer1pw 1504 1505 Note that affiliations are case sensitive except for the non-leaf affiliations that are specified in 1506 the server configuration file, which are always stored in lower case. For example, if the affiliations 1507 section of the server configuration file looks like this: 1508 1509 .. code:: bash 1510 1511 affiliations: 1512 BU1: 1513 Department1: 1514 - Team1 1515 BU2: 1516 - Department2 1517 - Department3 1518 1519 `BU1`, `Department1`, `BU2` are stored in lower case. This is because Fabric CA uses Viper to read configuration. 1520 Viper treats map keys as case insensitive and always returns lowercase value. To register an identity with 1521 `Team1` affiliation, `bu1.department1.Team1` would need to be specified to the 1522 `--id.affiliation` flag as shown below: 1523 1524 .. code:: bash 1525 1526 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin 1527 fabric-ca-client register --id.name client1 --id.type client --id.affiliation bu1.department1.Team1 1528 1529 Enrolling a peer identity 1530 ~~~~~~~~~~~~~~~~~~~~~~~~~ 1531 1532 Now that you have successfully registered a peer identity, you may now 1533 enroll the peer given the enrollment ID and secret (i.e. the *password* 1534 from the previous section). This is similar to enrolling the bootstrap identity 1535 except that we also demonstrate how to use the "-M" option to populate the 1536 Hyperledger Fabric MSP (Membership Service Provider) directory structure. 1537 1538 The following command enrolls peer1. 1539 Be sure to replace the value of the "-M" option with the path to your 1540 peer's MSP directory which is the 1541 'mspConfigPath' setting in the peer's core.yaml file. 1542 You may also set the FABRIC_CA_CLIENT_HOME to the home directory of your peer. 1543 1544 .. code:: bash 1545 1546 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/peer1 1547 fabric-ca-client enroll -u http://peer1:peer1pw@localhost:7054 -M $FABRIC_CA_CLIENT_HOME/msp 1548 1549 Enrolling an orderer is the same, except the path to the MSP directory is 1550 the 'LocalMSPDir' setting in your orderer's orderer.yaml file. 1551 1552 All enrollment certificates issued by the fabric-ca-server have organizational 1553 units (or "OUs" for short) as follows: 1554 1555 1. The root of the OU hierarchy equals the identity type 1556 2. An OU is added for each component of the identity's affiliation 1557 1558 For example, if an identity is of type `peer` and its affiliation is 1559 `department1.team1`, the identity's OU hierarchy (from leaf to root) is 1560 `OU=team1, OU=department1, OU=peer`. 1561 1562 Getting a CA certificate chain from another Fabric CA server 1563 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1564 1565 In general, the cacerts directory of the MSP directory must contain the certificate authority chains 1566 of other certificate authorities, representing all of the roots of trust for the peer. 1567 1568 The ``fabric-ca-client getcainfo`` command is used to retrieve these certificate chains from other 1569 Fabric CA server instances. 1570 1571 For example, the following will start a second Fabric CA server on localhost 1572 listening on port 7055 with a name of "CA2". This represents a completely separate 1573 root of trust and would be managed by a different member on the blockchain. 1574 1575 .. code:: bash 1576 1577 export FABRIC_CA_SERVER_HOME=$HOME/ca2 1578 fabric-ca-server start -b admin:ca2pw -p 7055 -n CA2 1579 1580 The following command will install CA2's certificate chain into peer1's MSP directory. 1581 1582 .. code:: bash 1583 1584 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/peer1 1585 fabric-ca-client getcainfo -u http://localhost:7055 -M $FABRIC_CA_CLIENT_HOME/msp 1586 1587 By default, the Fabric CA server returns the CA chain in child-first order. This means that each CA 1588 certificate in the chain is followed by its issuer's CA certificate. If you need the Fabric CA server 1589 to return the CA chain in the opposite order, then set the environment variable ``CA_CHAIN_PARENT_FIRST`` 1590 to ``true`` and restart the Fabric CA server. The Fabric CA client will handle either order appropriately. 1591 1592 Getting Identity Mixer credential for a user 1593 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1594 Identity Mixer (Idemix) is a cryptographic protocol suite for privacy-preserving authentication and transfer of certified attributes. 1595 Idemix allows users to authenticate with verifiers without the involvement of the issuer (CA) and selectively disclose only those attributes 1596 that are required by the verifier and can do so without being linkable across their transactions. 1597 1598 Fabric CA server can issue Idemix credentials in addition to X509 certificates. An Idemix credential can be requested by sending the request to 1599 the ``/api/v1/idemix/credential`` API endpoint. For more information on this and other Fabric CA server API endpoints, please refer to 1600 `swagger-fabric-ca.json <https://github.com/hyperledger/fabric-ca/blob/master/swagger/swagger-fabric-ca.json>`_. 1601 1602 The Idemix credential issuance is a two step process. First, send a request with an empty body to the ``/api/v1/idemix/credential`` 1603 API endpoint to get a nonce and CA's Idemix public key. Second, create a credential request using the nonce and CA's Idemix public key and 1604 send another request with the credential request in the body to the ``/api/v1/idemix/credential`` API endpoint to get an Idemix credential, 1605 Credential Revocation Information (CRI), and attribute names and values. Currently, only three attributes are supported: 1606 1607 - **OU** - organization unit of the user. The value of this attribute is set to user's affiliation. For example, if user's affiliation is `dept1.unit1`, then OU attribute is set to `dept1.unit1` 1608 - **IsAdmin** - if the user is an admin or not. The value of this attribute is set to the value of `isAdmin` registration attribute. 1609 - **EnrollmentID** - enrollment ID of the user 1610 1611 You can refer to the `handleIdemixEnroll` function in https://github.com/hyperledger/fabric-ca/blob/master/lib/client.go for reference implementation 1612 of the two step process for getting Idemix credential. 1613 1614 The ``/api/v1/idemix/credential`` API endpoint accepts both basic and token authorization headers. The basic authorization header should 1615 contain User's registration ID and password. If the user already has X509 enrollment certificate, it can also be used to create a token authorization header. 1616 1617 Note that Hyperledger Fabric will support clients/users to sign transactions with both X509 and Idemix credentials, but will only support X509 credentials 1618 for peer and orderer identities. As before, applications can use a Fabric SDK to send requests to the Fabric CA server. SDKs hide the complexity 1619 associated with creating authorization header and request payload, and with processing the response. 1620 1621 Getting Idemix CRI (Certificate Revocation Information) 1622 ----------------------------------------------- 1623 An Idemix CRI (Credential Revocation Information) is similar in purpose to an X509 CRL (Certificate Revocation List): 1624 to revoke what was previously issued. However, there are some differences. 1625 1626 In X509, the issuer revokes an end user's certificate and its ID is included in the CRL. 1627 The verifier checks to see if the user's certificate is in the CRL and if so, returns an authorization failure. 1628 The end user is not involved in this revocation process, other than receiving an authorization error from a verifier. 1629 1630 In Idemix, the end user is involved. The issuer revokes an end user's credential similar to X509 and evidence of this 1631 revocation is recorded in the CRI. The CRI is given to the end user (aka "prover"). The end user then generates a 1632 proof that their credential has not been revoked according to the CRI. The end user gives this proof to the verifier 1633 who verifies the proof according to the CRI. 1634 For verification to succeed, the version of the CRI (known as the "epoch") used by the end user and verifier must be same. 1635 The latest CRI can be requested by sending a request to ``/api/v1/idemix/cri`` API endpoint. 1636 1637 The version of the CRI is incremented when an enroll request is received by the fabric-ca-server and there are no revocation 1638 handles remaining in the revocation handle pool. In this case, the fabric-ca-server must generate a new pool of revocation 1639 handles which increments the epoch of the CRI. The number of revocation handles in the revocation handle pool is configurable 1640 via the ``idemix.rhpoolsize`` server configuration property. 1641 1642 Reenrolling an Identity 1643 ~~~~~~~~~~~~~~~~~~~~~~~ 1644 1645 Suppose your enrollment certificate is about to expire or has been compromised. 1646 You can issue the reenroll command to renew your enrollment certificate as follows. 1647 1648 .. code:: bash 1649 1650 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/peer1 1651 fabric-ca-client reenroll 1652 1653 Revoking a certificate or identity 1654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1655 An identity or a certificate can be revoked. Revoking an identity will revoke all 1656 the certificates owned by the identity and will also prevent the identity from getting 1657 any new certificates. Revoking a certificate will invalidate a single certificate. 1658 1659 In order to revoke a certificate or an identity, the calling identity must have 1660 the ``hf.Revoker`` and ``hf.Registrar.Roles`` attribute. The revoking identity 1661 can only revoke a certificate or an identity that has an affiliation that is 1662 equal to or prefixed by the revoking identity's affiliation. Furthermore, the 1663 revoker can only revoke identities with types that are listed in the revoker's 1664 ``hf.Registrar.Roles`` attribute. 1665 1666 For example, a revoker with affiliation **orgs.org1** and 'hf.Registrar.Roles=peer,client' 1667 attribute can revoke either a **peer** or **client** type identity affiliated with 1668 **orgs.org1** or **orgs.org1.department1** but can't revoke an identity affiliated with 1669 **orgs.org2** or of any other type. 1670 1671 The following command disables an identity and revokes all of the certificates 1672 associated with the identity. All future requests received by the Fabric CA server 1673 from this identity will be rejected. 1674 1675 .. code:: bash 1676 1677 fabric-ca-client revoke -e <enrollment_id> -r <reason> 1678 1679 The following are the supported reasons that can be specified using ``-r`` flag: 1680 1681 1. unspecified 1682 2. keycompromise 1683 3. cacompromise 1684 4. affiliationchange 1685 5. superseded 1686 6. cessationofoperation 1687 7. certificatehold 1688 8. removefromcrl 1689 9. privilegewithdrawn 1690 10. aacompromise 1691 1692 For example, the bootstrap admin who is associated with root of the affiliation tree 1693 can revoke **peer1**'s identity as follows: 1694 1695 .. code:: bash 1696 1697 export FABRIC_CA_CLIENT_HOME=$HOME/fabric-ca/clients/admin 1698 fabric-ca-client revoke -e peer1 1699 1700 An enrollment certificate that belongs to an identity can be revoked by 1701 specifying its AKI (Authority Key Identifier) and serial number as follows: 1702 1703 .. code:: bash 1704 1705 fabric-ca-client revoke -a xxx -s yyy -r <reason> 1706 1707 For example, you can get the AKI and the serial number of a certificate using the openssl command 1708 and pass them to the ``revoke`` command to revoke the said certificate as follows: 1709 1710 .. code:: bash 1711 1712 serial=$(openssl x509 -in userecert.pem -serial -noout | cut -d "=" -f 2) 1713 aki=$(openssl x509 -in userecert.pem -text | awk '/keyid/ {gsub(/ *keyid:|:/,"",$1);print tolower($0)}') 1714 fabric-ca-client revoke -s $serial -a $aki -r affiliationchange 1715 1716 The `--gencrl` flag can be used to generate a CRL (Certificate Revocation List) that contains all the revoked 1717 certificates. For example, following command will revoke the identity **peer1**, generates a CRL and stores 1718 it in the **<msp folder>/crls/crl.pem** file. 1719 1720 .. code:: bash 1721 1722 fabric-ca-client revoke -e peer1 --gencrl 1723 1724 A CRL can also be generated using the `gencrl` command. Refer to the `Generating a CRL (Certificate Revocation List)`_ 1725 section for more information on the `gencrl` command. 1726 1727 Generating a CRL (Certificate Revocation List) 1728 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1729 After a certificate is revoked in the Fabric CA server, the appropriate MSPs in Hyperledger Fabric must also be updated. 1730 This includes both local MSPs of the peers as well as MSPs in the appropriate channel configuration blocks. 1731 To do this, PEM encoded CRL (certificate revocation list) file must be placed in the `crls` 1732 folder of the MSP. The ``fabric-ca-client gencrl`` command can be used to generate a CRL. Any identity 1733 with ``hf.GenCRL`` attribute can create a CRL that contains serial numbers of all certificates that were revoked 1734 during a certain period. The created CRL is stored in the `<msp folder>/crls/crl.pem` file. 1735 1736 The following command will create a CRL containing all the revoked certficates (expired and unexpired) and 1737 store the CRL in the `~/msp/crls/crl.pem` file. 1738 1739 .. code:: bash 1740 1741 export FABRIC_CA_CLIENT_HOME=~/clientconfig 1742 fabric-ca-client gencrl -M ~/msp 1743 1744 The next command will create a CRL containing all certificates (expired and unexpired) that were revoked after 1745 2017-09-13T16:39:57-08:00 (specified by the `--revokedafter` flag) and before 2017-09-21T16:39:57-08:00 1746 (specified by the `--revokedbefore` flag) and store the CRL in the `~/msp/crls/crl.pem` file. 1747 1748 .. code:: bash 1749 1750 export FABRIC_CA_CLIENT_HOME=~/clientconfig 1751 fabric-ca-client gencrl --caname "" --revokedafter 2017-09-13T16:39:57-08:00 --revokedbefore 2017-09-21T16:39:57-08:00 -M ~/msp 1752 1753 1754 The `--caname` flag specifies the name of the CA to which this request is sent. In this example, the gencrl request is 1755 sent to the default CA. 1756 1757 The `--revokedafter` and `--revokedbefore` flags specify the lower and upper boundaries of a time period. 1758 The generated CRL will contain certificates that were revoked in this time period. The values must be UTC 1759 timestamps specified in RFC3339 format. The `--revokedafter` timestamp cannot be greater than the 1760 `--revokedbefore` timestamp. 1761 1762 By default, 'Next Update' date of the CRL is set to next day. The `crl.expiry` CA configuration property 1763 can be used to specify a custom value. 1764 1765 The gencrl command will also accept `--expireafter` and `--expirebefore` flags that can be used to generate a CRL 1766 with revoked certificates that expire during the period specified by these flags. For example, the following command 1767 will generate a CRL that contains certificates that were revoked after 2017-09-13T16:39:57-08:00 and 1768 before 2017-09-21T16:39:57-08:00, and that expire after 2017-09-13T16:39:57-08:00 and before 2018-09-13T16:39:57-08:00 1769 1770 .. code:: bash 1771 1772 export FABRIC_CA_CLIENT_HOME=~/clientconfig 1773 fabric-ca-client gencrl --caname "" --expireafter 2017-09-13T16:39:57-08:00 --expirebefore 2018-09-13T16:39:57-08:00 --revokedafter 2017-09-13T16:39:57-08:00 --revokedbefore 2017-09-21T16:39:57-08:00 -M ~/msp 1774 1775 Enabling TLS 1776 ~~~~~~~~~~~~ 1777 1778 This section describes in more detail how to configure TLS for a Fabric CA client. 1779 1780 The following sections may be configured in the ``fabric-ca-client-config.yaml``. 1781 1782 .. code:: yaml 1783 1784 tls: 1785 # Enable TLS (default: false) 1786 enabled: true 1787 certfiles: 1788 - root.pem 1789 client: 1790 certfile: tls_client-cert.pem 1791 keyfile: tls_client-key.pem 1792 1793 The **certfiles** option is the set of root certificates trusted by the 1794 client. This will typically just be the root Fabric CA server's 1795 certificate found in the server's home directory in the **ca-cert.pem** 1796 file. 1797 1798 The **client** option is required only if mutual TLS is configured on 1799 the server. 1800 1801 Attribute-Based Access Control 1802 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1803 1804 Access control decisions can be made by chaincode (and by the Hyperledger Fabric runtime) 1805 based upon an identity's attributes. This is called 1806 **Attribute-Based Access Control**, or **ABAC** for short. 1807 1808 In order to make this possible, an identity's enrollment certificate (ECert) 1809 may contain one or more attribute name and value. The chaincode then 1810 extracts an attribute's value to make an access control decision. 1811 1812 For example, suppose that you are developing application *app1* and want a 1813 particular chaincode operation to be accessible only by app1 administrators. 1814 Your chaincode could verify that the caller's certificate (which was issued by 1815 a CA trusted for the channel) contains an attribute named *app1Admin* with a 1816 value of *true*. Of course the name of the attribute can be anything and the 1817 value need not be a boolean value. 1818 1819 So how do you get an enrollment certificate with an attribute? 1820 There are two methods: 1821 1822 1. When you register an identity, you can specify that an enrollment certificate 1823 issued for the identity should by default contain an attribute. This behavior 1824 can be overridden at enrollment time, but this is useful for establishing 1825 default behavior and, assuming registration occurs outside of your application, 1826 does not require any application change. 1827 1828 The following shows how to register *user1* with two attributes: 1829 *app1Admin* and *email*. 1830 The ":ecert" suffix causes the *appAdmin* attribute to be inserted into user1's 1831 enrollment certificate by default, when the user does not explicitly request 1832 attributes at enrollment time. The *email* attribute is not added 1833 to the enrollment certificate by default. 1834 1835 .. code:: bash 1836 1837 fabric-ca-client register --id.name user1 --id.secret user1pw --id.type user --id.affiliation org1 --id.attrs 'app1Admin=true:ecert,email=user1@gmail.com' 1838 1839 2. When you enroll an identity, you may explicitly request that one or more attributes 1840 be added to the certificate. 1841 For each attribute requested, you may specify whether the attribute is 1842 optional or not. If it is not requested optionally and the identity does 1843 not possess the attribute, an error will occur. 1844 1845 The following shows how to enroll *user1* with the *email* attribute, 1846 without the *app1Admin* attribute, and optionally with the *phone* 1847 attribute (if the user possesses the *phone* attribute). 1848 1849 .. code:: bash 1850 1851 fabric-ca-client enroll -u http://user1:user1pw@localhost:7054 --enrollment.attrs "email,phone:opt" 1852 1853 The table below shows the three attributes which are automatically registered for every identity. 1854 1855 =================================== ===================================== 1856 Attribute Name Attribute Value 1857 =================================== ===================================== 1858 hf.EnrollmentID The enrollment ID of the identity 1859 hf.Type The type of the identity 1860 hf.Affiliation The affiliation of the identity 1861 =================================== ===================================== 1862 1863 To add any of the above attributes **by default** to a certificate, you must 1864 explicitly register the attribute with the ":ecert" specification. 1865 For example, the following registers identity 'user1' so that 1866 the 'hf.Affiliation' attribute will be added to an enrollment certificate if 1867 no specific attributes are requested at enrollment time. Note that the 1868 value of the affiliation (which is 'org1') must be the same in both the 1869 '--id.affiliation' and the '--id.attrs' flags. 1870 1871 .. code:: bash 1872 1873 fabric-ca-client register --id.name user1 --id.secret user1pw --id.type user --id.affiliation org1 --id.attrs 'hf.Affiliation=org1:ecert' 1874 1875 For information on the chaincode library API for Attribute-Based Access Control, 1876 see `https://github.com/hyperledger/fabric/blob/master/core/chaincode/lib/cid/README.md <https://github.com/hyperledger/fabric/blob/master/core/chaincode/lib/cid/README.md>`_ 1877 1878 Dynamic Server Configuration Update 1879 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1880 1881 This section describes how to use fabric-ca-client to dynamically update portions 1882 of the fabric-ca-server's configuration without restarting the server. 1883 1884 All commands in this section require that you first be enrolled by executing the 1885 `fabric-ca-client enroll` command. 1886 1887 Dynamically updating identities 1888 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1889 1890 This section describes how to use fabric-ca-client to dynamically update identities. 1891 1892 An authorization failure will occur if the client identity does not satisfy all of the following: 1893 1894 - The client identity must possess the "hf.Registrar.Roles" attribute with a comma-separated list of 1895 values where one of the values equals the type of identity being updated; for example, if the client's 1896 identity has the "hf.Registrar.Roles" attribute with a value of "client,peer", the client can update 1897 identities of type 'client' and 'peer', but not 'orderer'. 1898 1899 - The affiliation of the client's identity must be equal to or a prefix of the affiliation of the identity 1900 being updated. For example, a client with an affiliation of "a.b" may update an identity with an affiliation 1901 of "a.b.c" but may not update an identity with an affiliation of "a.c". If root affiliation is required for an 1902 identity, then the update request should specify a dot (".") for the affiliation and the client must also have 1903 root affiliation. 1904 1905 The following shows how to add, modify, and remove an affiliation. 1906 1907 Getting Identity Information 1908 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1909 1910 A caller may retrieve information on a identity from the fabric-ca server as long as the caller meets 1911 the authorization requirements highlighted in the section above. The following command shows how to get an 1912 identity. 1913 1914 .. code:: bash 1915 1916 fabric-ca-client identity list --id user1 1917 1918 A caller may also request to retrieve information on all identities that it is authorized to see by 1919 issuing the following command. 1920 1921 .. code:: bash 1922 1923 fabric-ca-client identity list 1924 1925 Adding an identity 1926 """"""""""""""""""" 1927 1928 The following adds a new identity for 'user1'. Adding a new identity performs the same action as registering an 1929 identity via the 'fabric-ca-client register' command. There are two available methods for adding a new identity. 1930 The first method is via the `--json` flag where you describe the identity in a JSON string. 1931 1932 .. code:: bash 1933 1934 fabric-ca-client identity add user1 --json '{"secret": "user1pw", "type": "user", "affiliation": "org1", "max_enrollments": 1, "attrs": [{"name": "hf.Revoker", "value": "true"}]}' 1935 1936 The following adds a user with root affiliation. Note that an affiliation name of "." means the root affiliation. 1937 1938 .. code:: bash 1939 1940 fabric-ca-client identity add user1 --json '{"secret": "user1pw", "type": "user", "affiliation": ".", "max_enrollments": 1, "attrs": [{"name": "hf.Revoker", "value": "true"}]}' 1941 1942 The second method for adding an identity is to use direct flags. See the example below for adding 'user1'. 1943 1944 .. code:: bash 1945 1946 fabric-ca-client identity add user1 --secret user1pw --type user --affiliation . --maxenrollments 1 --attrs hf.Revoker=true 1947 1948 The table below lists all the fields of an identity and whether they are required or optional, and any default values they might have. 1949 1950 +----------------+------------+------------------------+ 1951 | Fields | Required | Default Value | 1952 +================+============+========================+ 1953 | ID | Yes | | 1954 +----------------+------------+------------------------+ 1955 | Secret | No | | 1956 +----------------+------------+------------------------+ 1957 | Affiliation | No | Caller's Affiliation | 1958 +----------------+------------+------------------------+ 1959 | Type | No | client | 1960 +----------------+------------+------------------------+ 1961 | Maxenrollments | No | 0 | 1962 +----------------+------------+------------------------+ 1963 | Attributes | No | | 1964 +----------------+------------+------------------------+ 1965 1966 1967 Modifying an identity 1968 """""""""""""""""""""" 1969 1970 There are two available methods for modifying an existing identity. The first method is via the `--json` flag where you describe 1971 the modifications in to an identity in a JSON string. Multiple modifications can be made in a single request. Any element of an identity that 1972 is not modified will retain its original value. 1973 1974 NOTE: A maxenrollments value of "-2" specifies that the CA's max enrollment setting is to be used. 1975 1976 The command below make multiple modification to an identity using the --json flag. 1977 1978 .. code:: bash 1979 1980 fabric-ca-client identity modify user1 --json '{"secret": "newPassword", "affiliation": ".", "attrs": [{"name": "hf.Regisrar.Roles", "value": "peer,client"},{"name": "hf.Revoker", "value": "true"}]}' 1981 1982 The commands below make modifications using direct flags. The following updates the enrollment secret (or password) for identity 'user1' to 'newsecret'. 1983 1984 .. code:: bash 1985 1986 fabric-ca-client identity modify user1 --secret newsecret 1987 1988 The following updates the affiliation of identity 'user1' to 'org2'. 1989 1990 .. code:: bash 1991 1992 fabric-ca-client identity modify user1 --affiliation org2 1993 1994 The following updates the type of identity 'user1' to 'peer'. 1995 1996 .. code:: bash 1997 1998 fabric-ca-client identity modify user1 --type peer 1999 2000 2001 The following updates the maxenrollments of identity 'user1' to 5. 2002 2003 .. code:: bash 2004 2005 fabric-ca-client identity modify user1 --maxenrollments 5 2006 2007 By specifying a maxenrollments value of '-2', the following causes identity 'user1' to use 2008 the CA's max enrollment setting. 2009 2010 .. code:: bash 2011 2012 fabric-ca-client identity modify user1 --maxenrollments -2 2013 2014 The following sets the value of the 'hf.Revoker' attribute for identity 'user1' to 'false'. 2015 If the identity has other attributes, they are not changed. If the identity did not previously 2016 possess the 'hf.Revoker' attribute, the attribute is added to the identity. An attribute may 2017 also be removed by specifying no value for the attribute. 2018 2019 .. code:: bash 2020 2021 fabric-ca-client identity modify user1 --attrs hf.Revoker=false 2022 2023 The following removes the 'hf.Revoker' attribute for user 'user1'. 2024 2025 .. code:: bash 2026 2027 fabric-ca-client identity modify user1 --attrs hf.Revoker= 2028 2029 The following demonstrates that multiple options may be used in a single `fabric-ca-client identity modify` 2030 command. In this case, both the secret and the type are updated for user 'user1'. 2031 2032 .. code:: bash 2033 2034 fabric-ca-client identity modify user1 --secret newpass --type peer 2035 2036 Removing an identity 2037 """"""""""""""""""""" 2038 2039 The following removes identity 'user1' and also revokes any certificates associated with the 'user1' identity. 2040 2041 .. code:: bash 2042 2043 fabric-ca-client identity remove user1 2044 2045 Note: Removal of identities is disabled in the fabric-ca-server by default, but may be enabled 2046 by starting the fabric-ca-server with the `--cfg.identities.allowremove` option. 2047 2048 Dynamically updating affiliations 2049 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2050 2051 This section describes how to use fabric-ca-client to dynamically update affiliations. The 2052 following shows how to add, modify, remove, and list an affiliation. 2053 2054 Adding an affiliation 2055 """"""""""""""""""""""" 2056 2057 An authorization failure will occur if the client identity does not satisfy all of the following: 2058 2059 - The client identity must possess the attribute 'hf.AffiliationMgr' with a value of 'true'. 2060 - The affiliation of the client identity must be hierarchically above the affiliation being updated. 2061 For example, if the client's affiliation is "a.b", the client may add affiliation "a.b.c" but not 2062 "a" or "a.b". 2063 2064 The following adds a new affiliation named ‘org1.dept1’. 2065 2066 .. code:: bash 2067 2068 fabric-ca-client affiliation add org1.dept1 2069 2070 Modifying an affiliation 2071 """"""""""""""""""""""""" 2072 2073 An authorization failure will occur if the client identity does not satisfy all of the following: 2074 2075 - The client identity must possess the attribute 'hf.AffiliationMgr' with a value of 'true'. 2076 - The affiliation of the client identity must be hierarchically above the affiliation being updated. 2077 For example, if the client's affiliation is "a.b", the client may add affiliation "a.b.c" but not 2078 "a" or "a.b". 2079 - If the '--force' option is true and there are identities which must be modified, the client 2080 identity must also be authorized to modify the identity. 2081 2082 The following renames the 'org2' affiliation to 'org3'. It also renames any sub affiliations 2083 (e.g. 'org2.department1' is renamed to 'org3.department1'). 2084 2085 .. code:: bash 2086 2087 fabric-ca-client affiliation modify org2 --name org3 2088 2089 If there are identities that are affected by the renaming of an affiliation, it will result in 2090 an error unless the '--force' option is used. Using the '--force' option will update the affiliation 2091 of identities that are affected to use the new affiliation name. 2092 2093 .. code:: bash 2094 2095 fabric-ca-client affiliation modify org1 --name org2 --force 2096 2097 Removing an affiliation 2098 """"""""""""""""""""""""" 2099 2100 An authorization failure will occur if the client identity does not satisfy all of the following: 2101 2102 - The client identity must possess the attribute 'hf.AffiliationMgr' with a value of 'true'. 2103 - The affiliation of the client identity must be hierarchically above the affiliation being updated. 2104 For example, if the client's affiliation is "a.b", the client may remove affiliation "a.b.c" but not 2105 "a" or "a.b". 2106 - If the '--force' option is true and there are identities which must be modified, the client 2107 identity must also be authorized to modify the identity. 2108 2109 The following removes affiliation 'org2' and also any sub affiliations. 2110 For example, if 'org2.dept1' is an affiliation below 'org2', it is also removed. 2111 2112 .. code:: bash 2113 2114 fabric-ca-client affiliation remove org2 2115 2116 If there are identities that are affected by the removing of an affiliation, it will result 2117 in an error unless the '--force' option is used. Using the '--force' option will also remove 2118 all identities that are associated with that affiliation, and the certificates associated with 2119 any of these identities. 2120 2121 Note: Removal of affiliations is disabled in the fabric-ca-server by default, but may be enabled 2122 by starting the fabric-ca-server with the `--cfg.affiliations.allowremove` option. 2123 2124 Listing affiliation information 2125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2126 2127 An authorization failure will occur if the client identity does not satisfy all of the following: 2128 2129 - The client identity must possess the attribute 'hf.AffiliationMgr' with a value of 'true'. 2130 - Affiliation of the client identity must be equal to or be hierarchically above the 2131 affiliation being updated. For example, if the client's affiliation is "a.b", 2132 the client may get affiliation information on "a.b" or "a.b.c" but not "a" or "a.c". 2133 2134 The following command shows how to get a specific affiliation. 2135 2136 .. code:: bash 2137 2138 fabric-ca-client affiliation list --affiliation org2.dept1 2139 2140 A caller may also request to retrieve information on all affiliations that it is authorized to see by 2141 issuing the following command. 2142 2143 .. code:: bash 2144 2145 fabric-ca-client affiliation list 2146 2147 Manage Certificates 2148 ~~~~~~~~~~~~~~~~~~~~ 2149 2150 This section describes how to use fabric-ca-client to manage certificates. 2151 2152 Listing certificate information 2153 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2154 2155 The certificates that are visible to a caller include: 2156 2157 - Those certificates which belong to the caller 2158 - If the caller possesses the ``hf.Registrar.Roles`` attribute or the ``hf.Revoker`` attribute with a value of ``true``, 2159 all certificates which belong to identities in and below the caller's affiliation. For example, if the client's 2160 affiliation is ``a.b``, the client may get certificates for identities who's affiliation 2161 is ``a.b`` or ``a.b.c`` but not ``a`` or ``a.c``. 2162 2163 If executing a list command that requests certificates of more than one identity, only certificates of identities 2164 with an affiliation that is equal to or hierarchically below the caller's affiliation will be listed. 2165 2166 The certificates which will be listed may be filtered based on ID, AKI, serial number, expiration time, revocation time, notrevoked, and notexpired flags. 2167 2168 * ``id``: List certificates for this enrollment ID 2169 * ``serial``: List certificates that have this serial number 2170 * ``aki``: List certificates that have this AKI 2171 * ``expiration``: List certificates that have expiration dates that fall within this expiration time 2172 * ``revocation``: List certificates that were revoked within this revocation time 2173 * ``notrevoked``: List certificates that have not yet been revoked 2174 * ``notexpired``: List certificates that have not yet expired 2175 2176 You can use flags ``notexpired`` and ``notrevoked`` as filters to exclude revoked certificates and/or expired certificates from the result set. 2177 For example, if you only care about certificates that have expired but have not been revoked you can use the ``expiration`` and ``notrevoked`` flags to 2178 get back such results. An example of this case is provided below. 2179 2180 Time should be specified based on RFC3339. For instance, to list certificates that have expirations between 2181 March 1, 2018 at 1:00 PM and June 15, 2018 at 2:00 AM, the input time string would look like 2018-03-01T13:00:00z 2182 and 2018-06-15T02:00:00z. If time is not a concern, and only the dates matter, then the time part can be left 2183 off and then the strings become 2018-03-01 and 2018-06-15. 2184 2185 The string ``now`` may be used to denote the current time and the empty string to denote any time. For example, ``now::`` denotes 2186 a time range from now to any time in the future, and ``::now`` denotes a time range from any time in the past until now. 2187 2188 The following command shows how to list certificates using various filters. 2189 2190 List all certificates: 2191 2192 .. code:: bash 2193 2194 fabric-ca-client certificate list 2195 2196 List all certificates by id: 2197 2198 .. code:: bash 2199 2200 fabric-ca-client certificate list --id admin 2201 2202 List certificate by serial and aki: 2203 2204 .. code:: bash 2205 2206 fabric-ca-client certificate list --serial 1234 --aki 1234 2207 2208 List certificate by id and serial/aki: 2209 2210 .. code:: bash 2211 2212 fabric-ca-client certificate list --id admin --serial 1234 --aki 1234 2213 2214 List certificates that are neither revoker nor expired by id: 2215 2216 .. code:: bash 2217 2218 fabric-ca-client certificate list --id admin --notrevoked --notexpired 2219 2220 List all certificates that have not been revoked for an id (admin): 2221 2222 .. code:: bash 2223 2224 fabric-ca-client certificate list --id admin --notrevoked 2225 2226 List all certificates have not expired for an id (admin): 2227 2228 The "--notexpired" flag is equivalent to "--expiration now::", which means certificates 2229 will expire some time in the future. 2230 2231 .. code:: bash 2232 2233 fabric-ca-client certificate list --id admin --notexpired 2234 2235 List all certificates that were revoked between a time range for an id (admin): 2236 2237 .. code:: bash 2238 2239 fabric-ca-client certificate list --id admin --revocation 2018-01-01T01:30:00z::2018-01-30T05:00:00z 2240 2241 List all certificates that were revoked between a time range but have not expired for an id (admin): 2242 2243 .. code:: bash 2244 2245 fabric-ca-client certificate list --id admin --revocation 2018-01-01::2018-01-30 --notexpired 2246 2247 List all revoked certificates using duration (revoked between 30 days and 15 days ago) for an id (admin): 2248 2249 .. code:: bash 2250 2251 fabric-ca-client certificate list --id admin --revocation -30d::-15d 2252 2253 List all revoked certificates before a time 2254 2255 .. code:: bash 2256 2257 fabric-ca-client certificate list --revocation ::2018-01-30 2258 2259 List all revoked certificates after a time 2260 2261 .. code:: bash 2262 2263 fabric-ca-client certificate list --revocation 2018-01-30:: 2264 2265 List all revoked certificates before now and after a certain date 2266 2267 .. code:: bash 2268 2269 fabric-ca-client certificate list --id admin --revocation 2018-01-30::now 2270 2271 List all certificate that expired between a time range but have not been revoked for an id (admin): 2272 2273 .. code:: bash 2274 2275 fabric-ca-client certificate list --id admin --expiration 2018-01-01::2018-01-30 --notrevoked 2276 2277 List all expired certificates using duration (expired between 30 days and 15 days ago) for an id (admin): 2278 2279 .. code:: bash 2280 2281 fabric-ca-client certificate list --expiration -30d::-15d 2282 2283 List all certificates that have expired or will expire before a certain time 2284 2285 .. code:: bash 2286 2287 fabric-ca-client certificate list --expiration ::2058-01-30 2288 2289 List all certificates that have expired or will expire after a certain time 2290 2291 .. code:: bash 2292 2293 fabric-ca-client certificate list --expiration 2018-01-30:: 2294 2295 List all expired certificates before now and after a certain date 2296 2297 .. code:: bash 2298 2299 fabric-ca-client certificate list --expiration 2018-01-30::now 2300 2301 List certificates expiring in the next 10 days: 2302 2303 .. code:: bash 2304 2305 fabric-ca-client certificate list --id admin --expiration ::+10d --notrevoked 2306 2307 The list certificate command can also be used to store certificates on the file 2308 system. This is a convenient way to populate the admins folder in an MSP, The "-store" flag 2309 points to the location on the file system to store the certificates. 2310 2311 Configure an identity to be an admin, by storing certificates for an identity 2312 in the MSP: 2313 2314 .. code:: bash 2315 2316 export FABRIC_CA_CLIENT_HOME=/tmp/clientHome 2317 fabric-ca-client certificate list --id admin --store msp/admincerts 2318 2319 Contact specific CA instance 2320 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2321 2322 When a server is running multiple CA instances, requests can be directed to a 2323 specific CA. By default, if no CA name is specified in the client request the 2324 request will be directed to the default CA on the fabric-ca server. A CA name 2325 can be specified on the command line of a client command using the ``caname`` 2326 filter as follows: 2327 2328 .. code:: bash 2329 2330 fabric-ca-client enroll -u http://admin:adminpw@localhost:7054 --caname <caname> 2331 2332 `Back to Top`_ 2333 2334 HSM 2335 --- 2336 By default, the Fabric CA server and client store private keys in a PEM-encoded file, 2337 but they can also be configured to store private keys in an HSM (Hardware Security Module) 2338 via PKCS11 APIs. This behavior is configured in the BCCSP (BlockChain Crypto Service Provider) 2339 section of the server’s or client’s configuration file. 2340 2341 Configuring Fabric CA server to use softhsm2 2342 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2343 2344 This section shows how to configure the Fabric CA server or client to use a software version 2345 of PKCS11 called softhsm (see https://github.com/opendnssec/SoftHSMv2). 2346 2347 After installing softhsm, make sure to set your SOFTHSM2_CONF environment variable to 2348 point to the location where the softhsm2 configuration file is stored. The config file looks like 2349 2350 .. code:: 2351 2352 directories.tokendir = /tmp/ 2353 objectstore.backend = file 2354 log.level = INFO 2355 2356 You can find example configuration file named softhsm2.conf under testdata directory. 2357 2358 Create a token, label it “ForFabric”, set the pin to ‘98765432’ 2359 (refer to softhsm documentation). 2360 2361 2362 2363 You can use both the config file and environment variables to configure BCCSP 2364 For example, set the bccsp section of Fabric CA server configuration file as follows. 2365 Note that the default field’s value is PKCS11. 2366 2367 .. code:: yaml 2368 2369 ############################################################################# 2370 # BCCSP (BlockChain Crypto Service Provider) section is used to select which 2371 # crypto library implementation to use 2372 ############################################################################# 2373 bccsp: 2374 default: PKCS11 2375 pkcs11: 2376 Library: /usr/local/Cellar/softhsm/2.1.0/lib/softhsm/libsofthsm2.so 2377 Pin: 98765432 2378 Label: ForFabric 2379 hash: SHA2 2380 security: 256 2381 filekeystore: 2382 # The directory used for the software file-based keystore 2383 keystore: msp/keystore 2384 2385 And you can override relevant fields via environment variables as follows: 2386 2387 .. code:: bash 2388 2389 FABRIC_CA_SERVER_BCCSP_DEFAULT=PKCS11 2390 FABRIC_CA_SERVER_BCCSP_PKCS11_LIBRARY=/usr/local/Cellar/softhsm/2.1.0/lib/softhsm/libsofthsm2.so 2391 FABRIC_CA_SERVER_BCCSP_PKCS11_PIN=98765432 2392 FABRIC_CA_SERVER_BCCSP_PKCS11_LABEL=ForFabric 2393 2394 `Back to Top`_ 2395 2396 File Formats 2397 ------------ 2398 2399 Fabric CA server's configuration file format 2400 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2401 2402 A default configuration file is created in the server's home directory 2403 (see `Fabric CA Server <#server>`__ section for more info). The following 2404 link shows a sample :doc:`Server configuration file <serverconfig>`. 2405 2406 Fabric CA client's configuration file format 2407 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2408 2409 A default configuration file is created in the client's home directory 2410 (see `Fabric CA Client <#client>`__ section for more info). The following 2411 link shows a sample :doc:`Client configuration file <clientconfig>`. 2412 2413 `Back to Top`_ 2414 2415 Troubleshooting 2416 --------------- 2417 2418 1. If you see a ``Killed: 9`` error on OSX when trying to execute 2419 ``fabric-ca-client`` or ``fabric-ca-server``, there is a long thread 2420 describing this problem at https://github.com/golang/go/issues/19734. 2421 The short answer is that to work around this issue, you can run the 2422 following command:: 2423 2424 # sudo ln -s /usr/bin/true /usr/local/bin/dsymutil 2425 2426 2. The error ``[ERROR] No certificates found for provided serial and aki`` will occur 2427 if the following sequence of events occurs: 2428 2429 a. You issue a `fabric-ca-client enroll` command, creating an enrollment certificate (i.e. an ECert). 2430 This stores a copy of the ECert in the fabric-ca-server's database. 2431 b. The fabric-ca-server's database is deleted and recreated, thus losing the ECert from step 'a'. 2432 For example, this may happen if you stop and restart a docker container hosting the fabric-ca-server, 2433 but your fabric-ca-server is using the default sqlite database and the database file is not stored 2434 on a volume and is therefore not persistent. 2435 c. You issue a `fabric-ca-client register` command or any other command which tries to use the ECert from 2436 step 'a'. In this case, since the database no longer contains the ECert, the 2437 ``[ERROR] No certificates found for provided serial and aki`` will occur. 2438 2439 To resolve this error, you must enroll again by repeating step 'a'. This will issue a new ECert 2440 which will be stored in the current database. 2441 2442 3. When sending multiple parallel requests to a Fabric CA Server cluster that uses shared sqlite3 databases, 2443 the server occasionally returns a 'database locked' error. This is most probably because the database 2444 transaction timed out while waiting for database lock (held by another cluster member) to be released. 2445 This is an invalid configuration because sqlite is an embedded database, which means the Fabric CA server 2446 cluster must share the same file via a shared file system, which introduces a SPoF (single point of failure), 2447 which contradicts the purpose of cluster topology. The best practice is to use either Postgres or MySQL 2448 databases in a cluster topology. 2449 2450 4. Suppose an error similar to 2451 ``Failed to deserialize creator identity, err The supplied identity is not valid, Verify() returned x509: certificate signed by unknown authority`` 2452 is returned by a peer or orderer when using an enrollment certificate issued by the Fabric CA Server. This indicates that 2453 the signing CA certificate used by the Fabric CA Server to issue certificates does not match a certificate in the `cacerts` or `intermediatecerts` 2454 folder of the MSP used to make authorization checks. 2455 2456 The MSP which is used to make authorization checks depends on which operation you were performing when the error occurred. 2457 For example, if you were trying to install chaincode on a peer, the local MSP on the file system of the peer is used; 2458 otherwise, if you were performing some channel specific operation such as instantiating chaincode on a specific channel, 2459 the MSP in the genesis block or the most recent configuration block of the channel is used. 2460 2461 To confirm that this is the problem, compare the AKI (Authority Key Identifier) of the enrollment certificate 2462 to the SKI (Subject Key Identifier) of the certificate(s) in the `cacerts` and `intermediatecerts` folder of appropriate MSP. 2463 The command `openssl x509 -in <PEM-file> -noout -text | grep -A1 "Authority Key Identifier"` will display the AKI and 2464 `openssl x509 -in <PEM-file> -noout -text | grep -A1 "Subject Key Identifier"` will display the SKI. 2465 If they are not equal, you have confirmed that this is the cause of the error. 2466 2467 This can happen for multiple reasons including: 2468 2469 a. You used `cryptogen` to generate your key material but did not start `fabric-ca-server` with the signing key and certificate generated 2470 by `cryptogen`. 2471 2472 To resolve (assuming `FABRIC_CA_SERVER_HOME` is set to the home directory of your `fabric-ca-server`): 2473 2474 1. Stop `fabric-ca-server`. 2475 2. Copy `crypto-config/peerOrganizations/<orgName>/ca/*pem` to `$FABRIC_CA_SERVER_HOME/ca-cert.pem`. 2476 3. Copy `crypto-config/peerOrganizations/<orgName>/ca/*_sk` to `$FABRIC_CA_SERVER_HOME/msp/keystore/`. 2477 4. Start `fabric-ca-server`. 2478 5. Delete any previously issued enrollment certificates and get new certificates by enrolling again. 2479 2480 b. You deleted and recreated the CA signing key and certificate used by the Fabric CA Server after generating the genesis block. 2481 This can happen if the Fabric CA Server is running in a docker container, the container was restarted, and its home directory 2482 is not on a volume mount. In this case, the Fabric CA Server will create a new CA signing key and certificate. 2483 2484 Assuming that you can not recover the original CA signing key, the only way to recover from this scenario is to update the 2485 certificate in the `cacerts` (or `intermediatecerts`) of the appropriate MSPs to the new CA certificate. 2486 2487 .. Licensed under Creative Commons Attribution 4.0 International License 2488 https://creativecommons.org/licenses/by/4.0/ 2489 ƒ