Skip to content

Latest commit

 

History

History
724 lines (536 loc) · 34.4 KB

ca.md

File metadata and controls

724 lines (536 loc) · 34.4 KB
Raw

Modules

fabric-ca-client

This is the main module for the "fabric-ca-client" package. It communicates with the "fabric-ca" server to manage user certificates lifecycle including register, enroll, renew and revoke, so that the application can use the properly signed certificates to authenticate with the fabric

api

This module defines the API for the pluggable components of the node.js SDK. The APIs are defined according to the Hyperledger Fabric's common SDK specification

Classes

FabricCAServices

This is an implementation of the member service client which communicates with the Fabric CA server.

FabricCAClient

Client for communciating with the Fabric CA APIs

User

The User class represents users that have been enrolled and represented by an enrollment certificate (ECert) and a signing key. The ECert must have been signed by one of the CAs the blockchain network has been configured to trust. An enrolled user (having a signing key and ECert) can conduct chaincode instantiate, transactions and queries with the Chain.

User ECerts can be obtained from a CA beforehand as part of installing and instantiating the application, or it can be obtained from the optional Fabric CA service via its enrollment process.

Sometimes User identities are confused with Peer identities. User identities represent signing capability because it has access to the private key, while Peer identities in the context of the application/SDK only has the certificate for verifying signatures. An application cannot use the Peer identity to sign things because the application doesn’t have access to the Peer identity’s private key.

Typedefs

TLSOptions : Object
HTTPEndpoint : Object
KeyValueAttribute : Object
EnrollmentResponse : Object

fabric-ca-client

This is the main module for the "fabric-ca-client" package. It communicates with the "fabric-ca" server to manage user certificates lifecycle including register, enroll, renew and revoke, so that the application can use the properly signed certificates to authenticate with the fabric

api

This module defines the API for the pluggable components of the node.js SDK. The APIs are defined according to the Hyperledger Fabric's common SDK specification

api.KeyValueStore

Abstract class for a Key-Value store. The Chain class uses this store to save sensitive information such as authenticated user's private keys, certificates, etc.

The SDK provides a default implementation based on files. An alternative implementation can be specified using the "KEY_VALUE_STORE" environment variable pointing to a full path to the require() package for the module.

Kind: static class of api

keyValueStore.getValue(name) ⇒

Get the value associated with name.

Kind: instance method of KeyValueStore
Returns: Promise for the value corresponding to the key. If the value does not exist in the store, returns null without rejecting the promise

Param Type Description
name string of the key

keyValueStore.setValue(name, value) ⇒ Promise

Set the value associated with name.

Kind: instance method of KeyValueStore
Returns: Promise - Promise for the 'value' object upon successful write operation

Param Type Description
name string of the key to save
value string to save

api.CryptoSuite

Abstract class for a suite of crypto algorithms used by the SDK to perform encryption, decryption and secure hashing. A complete suite includes libraries for asymmetric keys (such as ECDSA or RSA), symmetric keys (such as AES) and secure hash (such as SHA2/3).

The SDK provides a default implementation based on ECDSA + AES + SHA2/3. An alternative implementation can be specified using the "CRYPTO_SUITE" environment variable, pointing to a full path to the require() package for the module.

Kind: static class of api

cryptoSuite.generateKey(opts) ⇒ Key

Generate a key using the opts

Kind: instance method of CryptoSuite
Returns: Key - Promise of an instance of the Key class

Param Type Description
opts Object algorithm: an identifier for the algorithm to be used, such as "ECDSA" ephemeral: true if the key to generate has to be ephemeral

cryptoSuite.deriveKey(key, opts) ⇒ Key

Derives a key from k using opts.

Kind: instance method of CryptoSuite
Returns: Key - derived key

Param Type Description
key Key the source key
opts Object algorithm: an identifier for the algorithm to be used ephemeral: true if the key to generate has to be ephemeral

cryptoSuite.importKey(raw, opts) ⇒ Key

Imports a key from its raw representation using opts. If the opts.ephemeral parameter is false, the method, in addition to returning the imported Key instance, also saves the imported key in the key store as PEM files that can be retrieved using the 'getKey()' method

Kind: instance method of CryptoSuite
Returns: Key - Promise of an instance of the Key class wrapping the raw key bytes

Param Type Description
raw Array.<byte> Raw bytes of the key to import
opts Object
type: type of information that 'raw' represents: x509 certificate,
algorithm: an identifier for the algorithm to be used
ephemeral: true if the key to generate has to be ephemeral

cryptoSuite.getKey(ski) ⇒ Key

Returns the key this CSP associates to the Subject Key Identifier ski.

Kind: instance method of CryptoSuite
Returns: Key - Promise of an instance of the Key class corresponding to the ski

Param Type Description
ski Array.<byte> Subject Key Identifier specific to a Crypto Suite implementation

cryptoSuite.hash(msg, opts) ⇒ string

Hashes messages msg using options opts.

Kind: instance method of CryptoSuite
Returns: string - The hashed digest in hexidecimal string encoding

Param Type Description
msg Array.<byte> Source message to be hashed
opts Object algorithm: an identifier for the algorithm to be used, such as "SHA3"

cryptoSuite.sign(key, digest, opts) ⇒ Array.<byte>

Signs digest using key k. The opts argument should be appropriate for the algorithm used.

Kind: instance method of CryptoSuite
Returns: Array.<byte> - the resulting signature

Param Type Description
key Key Signing key (private key)
digest Array.<byte> The message digest to be signed. Note that when a signature of a hash of a larger message is needed, the caller is responsible for hashing the larger message and passing the hash (as digest) and the hash function (as opts) to sign.
opts Object hashingFunction: the function to use to hash

cryptoSuite.verify(key, signature, digest) ⇒ boolean

Verifies signature against key k and digest The opts argument should be appropriate for the algorithm used.

Kind: instance method of CryptoSuite
Returns: boolean - true if the signature verifies successfully

Param Type Description
key Key Signing verification key (public key)
signature Array.<byte> The signature to verify
digest Array.<byte> The digest that the signature was created for

cryptoSuite.encrypt(key, plainText, opts) ⇒ Array.<byte>

Encrypts plaintext using key k. The opts argument should be appropriate for the algorithm used.

Kind: instance method of CryptoSuite
Returns: Array.<byte> - Cipher text after encryption

Param Type Description
key Key Encryption key (public key)
plainText Array.<byte> Plain text to encrypt
opts Object Encryption options

cryptoSuite.decrypt(key, cipherText, opts) ⇒ Array.<byte>

Decrypts ciphertext using key k. The opts argument should be appropriate for the algorithm used.

Kind: instance method of CryptoSuite
Returns: Array.<byte> - Plain text after decryption

Param Type Description
key Key Decryption key (private key)
cipherText Array.<byte> Cipher text to decrypt
opts Object Decrypt options

api.Key

Key represents a cryptographic key. It can be symmetric or asymmetric. In the case of an asymmetric key, the key can be public or private. In the case of a private asymmetric key, the getPublicKey() method allows to retrieve the corresponding public-key. A key can be referenced via the Subject Key Identifier in DER or PEM encoding

Kind: static class of api

key.getSKI() ⇒ Array.<byte>

Returns the subject key identifier of this key in DER encoding for private keys or PEM encoding for public keys.

Kind: instance method of Key
Returns: Array.<byte> - the subject key identifier of this key

key.isSymmetric() ⇒ boolean

Returns true if this key is a symmetric key, false is this key is asymmetric

Kind: instance method of Key
Returns: boolean - if this key is a symmetric key

key.isPrivate() ⇒ boolean

Returns true if this key is an asymmetric private key, false otherwise.

Kind: instance method of Key
Returns: boolean - if this key is an asymmetric private key

key.getPublicKey() ⇒ Key

Returns the corresponding public key if this key is an asymmetric private key. If this key is already public, PublicKey returns this key itself.

Kind: instance method of Key
Returns: Key - the corresponding public key if this key is an asymmetric private key. If this key is already public, PublicKey returns this key itself.

key.toBytes() ⇒ Array.<byte>

Converts this key to its byte representation, if this operation is allowed.

Kind: instance method of Key
Returns: Array.<byte> - the byte representation of the key

FabricCAServices

This is an implementation of the member service client which communicates with the Fabric CA server.

Kind: global class

new FabricCAServices(url, tlsOptions, cryptoSetting, KVSImplClass, opts)

constructor

Param Type Description
url string The endpoint URL for Fabric CA services of the form: "http://host:port" or "https://host:port"
tlsOptions TLSOptions The TLS settings to use when the Fabric CA services endpoint uses "https"
cryptoSetting object This optional parameter is an object with the following optional properties: - software {boolean}: Whether to load a software-based implementation (true) or HSM implementation (false) default is true (for software based implementation), specific implementation module is specified in the setting 'crypto-suite-software' - keysize {number}: The key size to use for the crypto suite instance. default is value of the setting 'crypto-keysize' - algorithm {string}: Digital signature algorithm, currently supporting ECDSA only with value "EC"
KVSImplClass function Optional. The built-in key store saves private keys. The key store may be backed by different KeyValueStore implementations. If specified, the value of the argument must point to a module implementing the KeyValueStore interface.
opts object Implementation-specific options object for the KeyValueStore class to instantiate an instance

fabricCAServices.register(req, registrar) ⇒ Promise

Register the member and return an enrollment secret.

Kind: instance method of FabricCAServices
Returns: Promise - The enrollment secret to use when this user enrolls

Param Type Description
req Object Registration request with the following fields:
- enrollmentID {string}. ID which will be used for enrollment
- role {string}. An arbitrary string representing a role value for the user
- affiliation {string}. Affiliation with which this user will be associated, like a company or an organization
- maxEnrollments {number}. The maximum number of times this user will be permitted to enroll
- attrs {KeyValueAttribute[]}. Array of key/value attributes to assign to the user.
registrar User . The identity of the registrar (i.e. who is performing the registration)

fabricCAServices.enroll(req) ⇒

Enroll the member and return an opaque member object.

Kind: instance method of FabricCAServices
Returns: Promise for an object with "key" for private key and "certificate" for the signed certificate

Param Type Description
req Enrollment request
req.enrollmentID string The registered ID to use for enrollment
req.enrollmentSecret string The secret associated with the enrollment ID

fabricCAServices.revoke(request, registrar) ⇒ Promise

Revoke an existing certificate (enrollment certificate or transaction certificate), or revoke all certificates issued to an enrollment id. If revoking a particular certificate, then both the Authority Key Identifier and serial number are required. If revoking by enrollment id, then all future requests to enroll this id will be rejected.

Kind: instance method of FabricCAServices
Returns: Promise - The revocation results

Param Type Description
request Object Request object with the following fields:
- enrollmentID {string}. ID to revoke
- aki {string}. Authority Key Identifier string, hex encoded, for the specific certificate to revoke
- serial {string}. Serial number string, hex encoded, for the specific certificate to revoke
- reason {string}. The reason for revocation. See https://godoc.org/golang.org/x/crypto/ocsp for valid values. The default value is 0 (ocsp.Unspecified).
registrar User The identity of the registrar (i.e. who is performing the revocation)

fabricCAServices.toString()

return a printable representation of this object

Kind: instance method of FabricCAServices

FabricCAClient

Client for communciating with the Fabric CA APIs

Kind: global class

new FabricCAClient(connect_opts)

constructor

Throws:

  • Will throw an error if connection options are missing or invalid
Param Type Description
connect_opts object Connection options for communciating with the Fabric CA server
connect_opts.protocol string The protocol to use (either HTTP or HTTPS)
connect_opts.hostname string The hostname of the Fabric CA server endpoint
connect_opts.port number The port of the Fabric CA server endpoint
connect_opts.tlsOptions TLSOptions The TLS settings to use when the Fabric CA endpoint uses "https"

fabricCAClient.register(enrollmentID, role, affiliation, maxEnrollments, attrs, signingIdentity) ⇒ Promise

Register a new user and return the enrollment secret

Kind: instance method of FabricCAClient
Returns: Promise - The enrollment secret to use when this user enrolls

Param Type Description
enrollmentID string ID which will be used for enrollment
role string Type of role for this user
affiliation string Affiliation with which this user will be associated
maxEnrollments number The maximum number of times the user is permitted to enroll
attrs Array.<KeyValueAttribute> Array of key/value attributes to assign to the user
signingIdentity SigningIdentity The instance of a SigningIdentity encapsulating the signing certificate, hash algorithm and signature algorithm

fabricCAClient.revoke(enrollmentID, aki, serial, reason, signingIdentity) ⇒ Promise

Revoke an existing certificate (enrollment certificate or transaction certificate), or revoke all certificates issued to an enrollment id. If revoking a particular certificate, then both the Authority Key Identifier and serial number are required. If revoking by enrollment id, then all future requests to enroll this id will be rejected.

Kind: instance method of FabricCAClient
Returns: Promise - The revocation results

Param Type Description
enrollmentID string ID to revoke
aki string Authority Key Identifier string, hex encoded, for the specific certificate to revoke
serial string Serial number string, hex encoded, for the specific certificate to revoke
reason string The reason for revocation. See https://godoc.org/golang.org/x/crypto/ocsp for valid values
signingIdentity SigningIdentity The instance of a SigningIdentity encapsulating the signing certificate, hash algorithm and signature algorithm

fabricCAClient.enroll(enrollmentID, enrollmentSecret, csr) ⇒ Promise

Enroll a registered user in order to receive a signed X509 certificate

Kind: instance method of FabricCAClient
Returns: Promise - EnrollmentResponse
Throws:

  • Will throw an error if all parameters are not provided
  • Will throw an error if calling the enroll API fails for any reason
Param Type Description
enrollmentID string The registered ID to use for enrollment
enrollmentSecret string The secret associated with the enrollment ID
csr string PEM-encoded PKCS#10 certificate signing request

FabricCAClient.pemToDER({string)) ⇒ string

Convert a PEM encoded certificate to DER format

Kind: static method of FabricCAClient
Returns: string - hex Hex-encoded DER bytes
Throws:

  • Will throw an error if the conversation fails
Param Description
{string) pem PEM encoded public or private key

User

The User class represents users that have been enrolled and represented by an enrollment certificate (ECert) and a signing key. The ECert must have been signed by one of the CAs the blockchain network has been configured to trust. An enrolled user (having a signing key and ECert) can conduct chaincode instantiate, transactions and queries with the Chain.

User ECerts can be obtained from a CA beforehand as part of installing and instantiating the application, or it can be obtained from the optional Fabric CA service via its enrollment process.

Sometimes User identities are confused with Peer identities. User identities represent signing capability because it has access to the private key, while Peer identities in the context of the application/SDK only has the certificate for verifying signatures. An application cannot use the Peer identity to sign things because the application doesn’t have access to the Peer identity’s private key.

Kind: global class

new User(cfg)

Constructor for a member.

Param Type Description
cfg string The member name or an object with the following attributes: - enrollmentID {string}: user name - name {string}: user name, if "enrollmentID" is also specified, the "name" is ignored - roles {string[]}: optional. array of roles - affiliation {string}: optional. affiliation with a group or organization

user.getName() ⇒ string

Get the member name.

Kind: instance method of User
Returns: string - The member name.

user.getRoles() ⇒ Array.<string>

Get the roles.

Kind: instance method of User
Returns: Array.<string> - The roles.

user.setRoles(roles)

Set the roles.

Kind: instance method of User

Param Type Description
roles Array.<string> The roles.

user.getAffiliation() ⇒ string

Get the affiliation.

Kind: instance method of User
Returns: string - The affiliation.

user.setAffiliation(affiliation)

Set the affiliation.

Kind: instance method of User

Param Type Description
affiliation string The affiliation.

user.getIdentity() ⇒ Identity

Get the Identity object for this User instance, used to verify signatures

Kind: instance method of User
Returns: Identity - the identity object that encapsulates the user's enrollment certificate

user.getSigningIdentity() ⇒ SigningIdentity

Get the SigningIdentity object for this User instance, used to generate signatures

Kind: instance method of User
Returns: SigningIdentity - the identity object that encapsulates the user's private key for signing

user.setEnrollment(privateKey, certificate, mspId, opts) ⇒ Promise

Set the enrollment object for this User instance

Kind: instance method of User
Returns: Promise - Promise for successful completion of creating the user's signing Identity

Param Type Description
privateKey Key the private key object
certificate string the PEM-encoded string of certificate
mspId string The Member Service Provider id for the local signing identity
opts object optional. an object with the following attributes, all optional: - cryptoSettings: {object} an object with the following attributes: - software {boolean}: Whether to load a software-based implementation (true) or HSM implementation (false) default is true (for software based implementation), specific implementation module is specified in the setting 'crypto-suite-software' - keysize {number}: The key size to use for the crypto suite instance. default is value of the setting 'crypto-keysize' - algorithm {string}: Digital signature algorithm, currently supporting ECDSA only with value "EC" - hash {string}: 'SHA2' or 'SHA3' - KVSImplClass: {function} the User class persists crypto keys in a CryptoKeyStore, there is a file-based implementation that is provided as the default. Application can use this parameter to override the default, such as saving the keys in a key store backed by database. If present, the value must be the class for the alternative implementation. - kvsOpts: {object}: an options object specific to the implementation in KVSImplClass

user.getTCertBatchSize() ⇒ int

Get the transaction certificate (tcert) batch size, which is the number of tcerts retrieved from member services each time (i.e. in a single batch).

Kind: instance method of User
Returns: int - The tcert batch size.

user.setTCertBatchSize(batchSize)

Set the transaction certificate (tcert) batch size.

Kind: instance method of User

Param Type
batchSize int

user.isEnrolled() ⇒ boolean

Determine if this name has been enrolled.

Kind: instance method of User
Returns: boolean - True if enrolled; otherwise, false.

user.fromString() ⇒ Member

Set the current state of this member from a string based JSON object

Kind: instance method of User
Returns: Member - Promise of the unmarshalled Member object represented by the serialized string

user.toString() ⇒ string

Save the current state of this member as a string

Kind: instance method of User
Returns: string - The state of this member as a string

TLSOptions : Object

Kind: global typedef
Properties

Name Type Default Description
trustedRoots Array.<string> Array of PEM-encoded trusted root certificates
verify boolean true Determines whether or not to verify the server certificate when using TLS

HTTPEndpoint : Object

Kind: global typedef
Properties

Name Type
hostname string
port number
protocol string

KeyValueAttribute : Object

Kind: global typedef
Properties

Name Type Description
name string The key used to reference the attribute
value string The value of the attribute

EnrollmentResponse : Object

Kind: global typedef
Properties

Name Type Description
enrollmentCert string PEM-encoded X509 enrollment certificate
caCertChain string PEM-encoded X509 certificate chain for the issuing certificate authority