# Fabric Certification Authority

## Hyperledger Fabric Identity Management
- CA
Agents of trusted certification authorities refer to Registrar who issue the identities and assign privileges to the identities they create

- Creation process
- Step 1.
Registrar generates Enrollment ID and Enrollment Secret (securely provided to the End User).
- Step 2.
Enrollment process leads to the generation of the certificate for the End User.

- Specifications
- Name: /** Free string **/
- Type: /** Represents type **/
(peer, orderer, client ...)
- Affiliation: /** Organization **/

- Max Enrollments: /** Max Re-enrollment count **/
(How many times the identity owner can execute the end rule step, the subsequent calls to end rule is referred to as re-enrollment)
- Attributes: [
/** Standard | Custom **/
]
(the privileges assigned to the identity)

## Hyperledger Fabric CA Components
The Registrar and the Admin use the CA Client for creating and managing identityies on the CA Server.
The Developers or the Users car write applications using the CA SDK to interact with the CA Server

- CA Server
Exposes Certificate Creation & Management services
- Admin and registrar:
- Identity | Certificate Management
- Register
- Affiliation Management
- Revocations
- User:
- Enroll
- Re-enroll

CA Server exposes there services as API, then you can write own applications using any language or library to invoke these API.
The specification for these API are available in `swagger` format.

- CA Client
Utility for interaction with CA server

- CA SDK
Client libraries for writing apps

## Configuring and Launching the CA Server

CA server is available as a single binary(likes peer and orderer) - `fabric-ca-server`.
It can be launched as:
- Single process setup (single point of failure)
- Cluster setup

fabric-ca-server command: `fabric-ca-server command --flags`
- `version`
Version of the binary
- `init`
Initialize the CA Server
It is similar to `start` but it does not launch the CA Server

- `start`
- Launches the CA Server process
- Config may be provided by way of flags | environment | YAML(`fabric-ca-server-config`)
- A server may contain multiple CAs. Each CA is either a root CA or an intermediate CA. Each intermediate CA has a parent CA which is either a root CA or another intermediate CA.
- --flags:
- `--help`
Help documents
- `-d --debug`
To enable debug level logging
- `-b --boot`
Bootstrap new identity
- `--address`
Listening address. Default = 0.0.0.0
- `-p`
Listening port. Default = 7054
- `-n --ca.name`
Name for the CA
- `Certificate`
CA certificate setup
- `TLS`
Transport Layer Security
- `CSR`
Certificate Signing Request
- `Database`
DB config for cluster setup
- `LDAP`
LDAP Config for cluster setup
- `Intermediate CA`
ICA Configuration

Launch without initialization(for test): `fabric-ca-server start -b admin:adminpw`

First time start initializes the CA server will generate the Config file(`fabric-ca-server-config.yaml`) and CA Certificate & Key.
Location of the YAML:
1. Specified by way of `-h` flag
2. Environment variable `FABRIC_CA_SERVER_HOME`
3. Environment variable `FABRIC_CA_HOME`
4. Environment variable `CA_CFG_PATH`
5. Current Folder

All of the Identities on the CA server are managed in a persistent store, by default `SQLite`.(can replace by other database)

:::info
### Exercise: Expolre the CA server
1. Launch the CA server with default configuration
- Open terminal window and switch to folder: `ca/server`
`fabric-ca-server start -b admin:adminpw`
3. Expolore the REST APL swagger
- https://raw.githubusercontent.com/acloudfan/HLF2-Miscellaneous/master/fabric-ca-swagger.yaml
- swagger: Copy & Paste Swager JSON to editor & expolore
https://editor.swagger.io/
:::

### fabric-ca-server-config.yaml
- .
- `version`
Version of the server
- `port`
Port on which the server listens for incoming REST requests.
Default=7054
- `crlsizelimit`
CRL size limit.
Default=512000
- `debug`
Enable/Disable Debug level logging

Root Certificate Specifications
- `ca`
Certification Authority information
- `csr`
Certificate Signing Request

Intermediate CA Setup
- `intermediate`
Intermediate CA Server Setup

Identity enrollment
- `affiliations`
CA server affiliations
- `sigining`
Certificate Signing Configuration

Identity persistence
- `registry`
Registry for managing identities
- `db`
Database configuration
SQLit, MySQL, PostgreSQL
- `Idap`
CA server affiliations

Sections
- `tls`
Transport Layer Security
- `crl`
Certificate Revocation List
- `bccsp`
Blockchain Crypto Service Provider

Multiple Certification Authorities (Single CA Server process may host multiple CA)
- `cacount`
Count of the CA
- `cafiles`
Files related to each of the CA

:::info
### Recipe: Standalone Root CA Server setup
- Suppose
- All of commands are demonstrated under the folder `ca/server`
- Single CA for Acme and Orderer organization
- Use default database for identity persistence SQLite
- TLS = Disabled
- CSR
- Step
1. Setup the parameters in `fabric-ca-server-config.yaml`
Provide values for parameters under four sections
- `ca`

- `affiliations`

- `registry`

- `csr`

3. Execute the init command
Before step.2: Execute ./clean.sh and copy `fabric-ca-server-config.yaml` to `ca/server`
- `fabric-ca-server init`
- `fabric-ca-server start`
5. Examine the Root Certificate
- Copy the content of `ca-cert.pem` to the [decoder web](https://certlogik.com/decoder/) to decode CSR

:::
## Fabric CA Client
- Single binary file `fabric-ca-client` picks up configuration from `fabric-ca-client-config.yaml`

- Needs access to crypto material for the identity that it uses for interacting with the CA Server

- Home folder | Location of the `fabric-ca-client-config.yaml`
1. Specified by way of `-h` flag
2. Environment variable `FABRIC_CA_CLIENT_HOME`
3. Environment variable `FABRIC_CA_HOME`
4. Environment variable `CA_CFG_PATH`
5. Folder $HOME/.fabric-ca-client

- Commands: fabric-ca-client command --flags
- `fabric-ca-client version`
- --help
- `fabric-ca-client --help`
- `fabric-ca-client command --help`
- `getcainfo`
Gets the CA information
- `identity`
Manage the identities
- `enroll`
Enroll an identity
- `reenroll`
RE-Enroll an identity
- `register`
Registers an identity
- `affiliation`
Manage affiliations
- `revoke`
Revoke identity
- `gencrl`
Generate Certificate Revocation List
- `gencsr`
Generate a Certificate Signing Request
- `certificate`
Manage certificate

- Enroll
1. `fabric-ca-server start -b admin:adminpw`
Register admin identity
2. `fabric-ca-client enroll -u http://admin:adminpw@localhost:7054`
First execution will generates `fabric-ca-client-config.yaml` in CA Client HOME folder
3. Sets up MSP directory in CA Client HOME folder

- Re-Enroll
`fabric-ca-client rennroll`
- Regeneration of the certificate & keyfile, it changes the content of the certificate
- Number of times re-enroll can be invoked in the `fabric-ca-client-config.yaml`(Max Enrollments=-1 unlimited use secret)

:::info
### Enroll the bootstrap identity
- `fabric-ca-server start` (terminal 1)
- `export FABRIC_CA_CLIENT_HOME='pwd'`(terminal 2)
- `fabric-ca-client enroll -u http://admin:adminpw@localhost:7054` (terminal 2)

### Exercise: Explore the CA Client setup
- Pre work & solution
- `ca` >_ `./clean.sh all`
Cleanup the previous run
- Copy server config file to `ca/server`
1. Add an additional bootstrap identity (user)
- Update the CA Server Configuration (`fabric-ca-server-config.yaml`)
- registry:
Not a Registrar and should not be able to generate CRL.
- Type=user
- Credentials=user:userpw
- Maxenrollment=2
- `fabric-ca-server start`

3. Enroll the bootstrap identity (admin & user)
Execute commands in ca folder
- Enroll admin
- `setclient.sh admin`
- `fabric-ca-client enroll -u http://admin:adminpw@localhost:7054`
- Enroll user
- `setclient.sh user`
- `fabric-ca-client enroll -u http://user:userpw@localhost:7054`

5. Call enroll command multiple times for user
- Execute once
- `setclient.sh user`
- Exucute more than 2 times
- `fabric-ca-client enroll -u http://user:userpw@localhost:7054`
- It should fail(Error Code: 20 - Authorization failure)

7. Examine the `ca-cert.pem` for the user
Copy user's cert.pem to the Decoder
:::
## Attribute Based Access Control (ABAC) & Identity Commands

- Standard attributes
- Fabric Runtime Access control
- Specification elements added as attributes (default)

- Custom attributes
Registrar can add custom attributes as well
- Application Level Access control
- Accessible from Chain code

- Defaults for the bootstrap admin identity
`fabric-ca-server start -b admin:adminpw`
The Ecert set to false means that these attributes are not added to the enrollment certificate

- By default only 3 attributes added to the certificate
Standard | custom attributes by default are NOT included in the certificate
need explicitly requested for attribute to be added to certificate
that is how the chain code will get access to the attributes for decision making process.
- hf.EnrollmentID Value:user ECert:true
- hf.Type Value:user ECert:true
- hf.Affiliation Value:org2 ECert:ture
That means these attributes will be available in the chain code.
- commands
Registrar use `identity` command for managing identities on the CA Server
- `fabric-ca-client identity list`
List the identities
- `fabric-ca-client identity remove <enrollment ID>`
By default identity removal is DISABLED
To ENABLE identity removal start the CA server with`--cfg.identities.allowremove`
- `fabric-ca-client identity add <enrollment-ID> --flags`
Add an identity
OR use a JSON String `--json JSON String`
- `fabric-ca-client identity modify <enrollment-ID> --flags`
Modify an identity
- e.g.`fabric-ca-client identity modify user --attrs myAttr true:ecert`
To add the attribute to ECert suffix the value with :ecert
:::info
### Exercise: Manage User Identities
1. Launch the CA server & Enroll admin identity

3. List the identities using `identity list` command
`fabric-ca-client identity list`
4. Add 2 new identities of `type = user` and default attributes
User - Use the specification flags
User1 - Use the JSON string
`fabric-ca-client identity add user --type user --affiliation org1 --maxenrollments 2`
`fabric-ca-client identity add user1 --json '{"type":"user", "affiliation":"org1","maxenrollments":2}'`
4. Modify affiliation of the user to `org2` & add a custom attribute
`fabric-ca-client identity modify user --affiliation org2 --attrs maAttr=ture`
6. `Remove` the user1 and then use `list` command to confirm
Server restart will be needed
`fabric-ca-client identity start --cfg.identities.allowremove`
(change terminal)
`fabric-ca-client identity remove user1`
6. `Modify` custom attribute such that its added to the `ECert`
`fabric-ca-client identity modify user --affiliation org2 --attrs myAttr-ture:ecert`
:::
## Identity Management Rules
`fabric-ca-client register --flags` similar to `fabric-ca-client identity add --flags` except that `--flags` are different

- Runtime applies ABAC (Affiliation & Attributes) to check

- Registrar's identity MUST be enrolled

- Identity Registration Checks:
1. Can create an identity of Requested Type?
Registrar's identity MUST have Roles attribute
`hf.Registrar.Roles`
- Comma separated list of identity types
- Governs type of user Registrar can create

Example:
- hf.Registrar.Roles="peer,app,user"
- hf.Registrar.Roles="orderer"
- hf.Registrar.Roles="*" (all)


3. Can assign the Requested Affiliation?
Registrar's Affiliation MUST be equal or above
- New identity Affiliation = Registrar's Affiliation
- Registrar's Affiliation is a Prefix of new identity

5. Can add/change the Requested Standard Attribute?
Multiple Rules applied for Standard attributes

7. Can add/change the Requested Custom Attribute?
Multiple Rules applied for Custom attributes
- Specifies patterns for `attrs` that Registrar is allowed to manage

9. Can add/change the value of hf.Registrar.Attributes?
Setting | Adding the hf.Registrar.Attributes
- Value may be equal to or subset of hf.Registrar.Attributes
- May be specified as patterns

## Fabric CA client YAML Configuration
`fabric-ca-client enroll` will use the configuration information from `fabric-ca-client-config.yaml`, so it will read URL for server

- `url`
URL of the CA Server

- `caname`
Name of the CA Server if multiple CA hosted in server
- `msp`
Folder path to msp directory
- `csr`
Certificate Singing Request
User generate a CSR by` fabric-ca-client generate`
1. CA Client prepares the CSR and sends it to the fabric CA Server
2. CA Server reads the CSR to sign the certificate and sends certificate to CA Client
3. CA client on receiving the signed certificate observe to the MSP
4. CA client can set up the parameters in the CSR to ensure that the certificate reflects the information about their organization
- `tls`
Transport Layer Security
- `certfiles`
List of trusted Root Certificate file
- `client`
Needed if client auth enabled on server
- `cerfile`
Client Cert/Pem file
- `keyfile`
Client Key/Pem file
- `id`
Used by Register commands
- `name`
Override this with `--id.name` flag
- `type`
Override this with `--id.type` flag
- `affiliation`
Override this with `--id.affiliation` flag
- `maxenrollment`
Override this with `--id.maxenrollment` flag
- `attributes`
Override this with `--id.attributes` flag. List of name-value