HyperLeger Fabric SDK开发（八）——msp

HyperLeger Fabric SDK开发（八）——msp

一、msp简介

1、msp简介

msp支持在Fabric网络上创建和更新用户。MSP客户端支持以下操作：Enroll，Reenroll，Register，Revoke和GetSigningIdentity。
官方文档：
https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/msp

2、msp使用流程

msp使用的基本流程如下：
A、准备客户端上下文
B、创建msp客户端
C、注册用户
D、注册用户
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

username := randomUsername()

enrollmentSecret, err := c.Register(&RegistrationRequest{Name: username})
if err != nil {
    fmt.Printf("Register return error %s\n", err)
    return
}

err = c.Enroll(username, WithSecret(enrollmentSecret))
if err != nil {
    fmt.Printf("failed to enroll user: %s\n", err)
    return
}
fmt.Println("enroll user is completed")
// output:
// enroll user is completed

二、msp常用接口

1、类型定义

var (
   // ErrUserNotFound indicates the user was not found
   ErrUserNotFound = errors.New("user not found")
)

type AffiliationInfo struct {
   Name         string
   Affiliations []AffiliationInfo
   Identities   []IdentityInfo
}

AffiliationInfo包含附属信息名称，子附属信息，以及本附属相关的身份标识

type AffiliationRequest struct {
   // 附属名称
   Name string
   // Creates parent affiliations if they do not exist
   Force bool
   // CA名称
   CAName string
}

AffiliationRequest表示要增加或删除附属信息到CA服务器的请求

type AffiliationResponse struct {
   AffiliationInfo
   CAName string
}

AffiliationResponse包含获取、增加、修改、删除一个附属信息的响应

type Attribute struct {
   Name  string
   Value string
   ECert bool
}

Attribute定义了要传递给注册对象的附加属性

type AttributeRequest struct {
   Name     string
   Optional bool
}

AttributeRequest定义一个属性的请求

// IdentityManager provides management of identities in a Fabric network
type IdentityManager interface {
   GetSigningIdentity(name string) (msp.SigningIdentity, error)
   CreateSigningIdentity(ops ...msp.SigningIdentityOption) (msp.SigningIdentity, error)
}
// RegistrationRequest defines the attributes required to register a user with the CA
type RegistrationRequest struct {
   // Name is the unique name of the identity
   Name string
   // Type of identity being registered (e.g. "peer, app, user")
   Type string
   // MaxEnrollments is the number of times the secret can  be reused to enroll.
   // if omitted, this defaults to max_enrollments configured on the server
   MaxEnrollments int
   // The identity's affiliation e.g. org1.department1
   Affiliation string
   // Optional attributes associated with this identity
   Attributes []Attribute
   // CAName is the name of the CA to connect to
   CAName string
   // Secret is an optional password.  If not specified,
   // a random secret is generated.  In both cases, the secret
   // is returned from registration.
   Secret string
}
// IdentityRequest represents the request to add/update identity to the fabric-ca-server
type IdentityRequest struct {
   // The enrollment ID which uniquely identifies an identity (required)
   ID string
   // The identity's affiliation (required)
   Affiliation string
   // Array of attributes to assign to the user
   Attributes []Attribute
   // Type of identity being registered (e.g. 'peer, app, user'). Default is 'user'.
   Type string
   // The maximum number of times the secret can be reused to enroll (default CA's Max Enrollment)
   MaxEnrollments int
   // The enrollment secret. If not provided, a random secret is generated.
   Secret string
   // Name of the CA to send the request to within the Fabric CA server (optional)
   CAName string
}

// IdentityResponse is the response from the any read/add/modify/remove identity call
type IdentityResponse struct {
   // The enrollment ID which uniquely identifies an identity
   ID string
   // The identity's affiliation
   Affiliation string
   // Array of attributes assigned to the user
   Attributes []Attribute
   // Type of identity (e.g. 'peer, app, user')
   Type string
   // The maximum number of times the secret can be reused to enroll
   MaxEnrollments int
   // The enrollment secret
   Secret string
   // Name of the CA
   CAName string
}

type RemoveIdentityRequest struct {
   // The enrollment ID which uniquely identifies an identity
   ID string
   // Force delete
   Force bool
   // Name of the CA
   CAName string
}

// RevocationRequest defines the attributes required to revoke credentials with the CA
type RevocationRequest struct {
   // Name of the identity whose certificates should be revoked
   // If this field is omitted, then Serial and AKI must be specified.
   Name string
   // Serial number of the certificate to be revoked
   // If this is omitted, then Name must be specified
   Serial string
   // AKI (Authority Key Identifier) of the certificate to be revoked
   AKI string
   // Reason is the reason for revocation. See https://godoc.org/golang.org/x/crypto/ocsp
   // for valid values. The default value is 0 (ocsp.Unspecified).
   Reason string
   // CAName is the name of the CA to connect to
   CAName string
}

// RevocationResponse represents response from the server for a revocation request
type RevocationResponse struct {
   // RevokedCerts is an array of certificates that were revoked
   RevokedCerts []RevokedCert
   // CRL is PEM-encoded certificate revocation list (CRL) that contains all unexpired revoked certificates
   CRL []byte
}

// RevokedCert represents a revoked certificate
type RevokedCert struct {
   // Serial number of the revoked certificate
   Serial string
   // AKI of the revoked certificate
   AKI string
}

2、获取客户端实例

type Client struct {
   orgName string
   caName  string
   ctx     context.Client
}
func New(clientProvider context.ClientProvider, opts ...ClientOption) (*Client, error)

New创建一个新的Client实例
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

if c != nil {
    fmt.Println("msp client created")
}
// output:
// msp client created  

3、创建身份标识

func (c *Client) CreateIdentity(request *IdentityRequest) (*IdentityResponse, error)
CreateIdentity使用Fabric CA服务器创建一个新身份标识。 返回的登记secret与登记ID一起使用可以登记新身份。
参数:
请求包含身份相关信息
返回包含secret的身份信息
使用示例：

// Create msp client
c, err := New(mockClientProvider())
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

identity, err := c.CreateIdentity(&IdentityRequest{ID: "123", Affiliation: "org2",
    Attributes: []Attribute{{Name: "attName1", Value: "attValue1"}}})
if err != nil {
    fmt.Printf("Create identity return error %s\n", err)
    return
}
fmt.Printf("identity '%s' created\n", identity.ID)
// output:
// identity '123' created

4、创建签名的身份标识

func (c *Client) CreateSigningIdentity(opts ...mspctx.SigningIdentityOption) (mspctx.SigningIdentity, error)
CreateSigningIdentity使用给定选项创建一个签名标识。
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

testPrivKey := `-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgp4qKKB0WCEfx7XiB
5Ul+GpjM1P5rqc6RhjD5OkTgl5OhRANCAATyFT0voXX7cA4PPtNstWleaTpwjvbS
J3+tMGTG67f+TdCfDxWYMpQYxLlE8VkbEzKWDwCYvDZRMKCQfv2ErNvb
-----END PRIVATE KEY-----`

testCert := `-----BEGIN CERTIFICATE-----
MIICGTCCAcCgAwIBAgIRALR/1GXtEud5GQL2CZykkOkwCgYIKoZIzj0EAwIwczEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBG
cmFuY2lzY28xGTAXBgNVBAoTEG9yZzEuZXhhbXBsZS5jb20xHDAaBgNVBAMTE2Nh
Lm9yZzEuZXhhbXBsZS5jb20wHhcNMTcwNzI4MTQyNzIwWhcNMjcwNzI2MTQyNzIw
WjBbMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEWMBQGA1UEBxMN
U2FuIEZyYW5jaXNjbzEfMB0GA1UEAwwWVXNlcjFAb3JnMS5leGFtcGxlLmNvbTBZ
MBMGByqGSM49AgEGCCqGSM49AwEHA0IABPIVPS+hdftwDg8+02y1aV5pOnCO9tIn
f60wZMbrt/5N0J8PFZgylBjEuUTxWRsTMpYPAJi8NlEwoJB+/YSs29ujTTBLMA4G
A1UdDwEB/wQEAwIHgDAMBgNVHRMBAf8EAjAAMCsGA1UdIwQkMCKAIIeR0TY+iVFf
mvoEKwaToscEu43ZXSj5fTVJornjxDUtMAoGCCqGSM49BAMCA0cAMEQCID+dZ7H5
AiaiI2BjxnL3/TetJ8iFJYZyWvK//an13WV/AiARBJd/pI5A7KZgQxJhXmmR8bie
XdsmTcdRvJ3TS/6HCA==
-----END CERTIFICATE-----`

// Create signing identity based on certificate and private key
id, err := c.CreateSigningIdentity(msp.WithCert([]byte(testCert)), msp.WithPrivateKey([]byte(testPrivKey)))
if err != nil {
    fmt.Printf("failed when creating identity based on certificate and private key: %s\n", err)
    return
}
if string(id.EnrollmentCertificate()) != testCert {
    fmt.Printf("certificate mismatch\n")
    return
}

// In this user case client might want to import keys directly into keystore
// out of band instead of enrolling the user via SDK. User enrolment creates a cert
// and stores it into local SDK user store, while user might not want SDK to manage certs.
err = importPrivateKeyOutOfBand([]byte(testPrivKey), c)
if err != nil {
    fmt.Printf("failed to import key: %s\n", err)
    return
}

// Create signing identity using certificate. SDK will lookup the private key based on the certificate.
id, err = c.CreateSigningIdentity(msp.WithCert([]byte(testCert)))
if err != nil {
    fmt.Printf("failed when creating identity using certificate: %s\n", err)
    return
}
if string(id.EnrollmentCertificate()) != testCert {
    fmt.Printf("certificate mismatch\n")
    return
}

fmt.Println("create signing identity is completed")
// output:
// create signing identity is completed   

5、登记用户

func (c *Client) Enroll(enrollmentID string, opts ...EnrollmentOption) error
登记用户以便接收签名的X509证书。为用户生成新的密钥对。私钥和登记证书由CA颁发，存储在SDK数据库中。可以通过调用IdentityManager.GetSigningIdentity()来检索它们。
参数:
enrollmentID登记用户的登记ID
opts是可选的登记选项
如果登记失败，则返回出错信息
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

err = c.Enroll(randomUsername(), WithSecret("enrollmentSecret"))
if err != nil {
    fmt.Printf("failed to enroll user: %s\n", err)
    return
}
fmt.Println("enroll user is completed")
// output:
// enroll user is completed

6、查看身份

func (c *Client) GetAllIdentities(options ...RequestOption) ([]*IdentityResponse, error)
GetAllIdentities返回调用者有权查看的所有身份
参数:
options包含可选的请求选项
返回包含身份的响应
使用示例：

// Create msp client
c, err := New(mockClientProvider())
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

results, err := c.GetAllIdentities()
if err != nil {
    fmt.Printf("Get identities return error %s\n", err)
    return
}
fmt.Printf("%d identities retrieved\n", len(results))
// output:
// 2 identities retrieved

7、查看身份信息

func (c *Client) GetIdentity(ID string, options ...RequestOption) (*IdentityResponse, error)
GetIdentity检索身份信息
参数：
ID是必需的身份ID
options包含可选的请求选项
返回包含身份信息的响应
使用示例：

// Create msp client
c, err := New(mockClientProvider())
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

identity, err := c.GetIdentity("123")
if err != nil {
    fmt.Printf("Get identity return error %s\n", err)
    return
}
fmt.Printf("identity '%s' retrieved\n", identity.ID)
// output:
// identity '123' retrieved

8、获取签名身份

func (c *Client) GetSigningIdentity(id string) (mspctx.SigningIdentity, error)
GetSigningIdentity返回身份id的签名身份
参数:
id是用户ID
返回签名身份
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

username := randomUsername()

err = c.Enroll(username, WithSecret("enrollmentSecret"))
if err != nil {
    fmt.Printf("failed to enroll user: %s\n", err)
    return
}
enrolledUser, err := c.GetSigningIdentity(username)
if err != nil {
    fmt.Printf("user not found %s\n", err)
    return
}

if enrolledUser.Identifier().ID != username {
    fmt.Println("Enrolled user name doesn't match")
    return
}

fmt.Println("enroll user is completed")
// output:
// enroll user is completed    

9、修改身份

func (c *Client) ModifyIdentity(request *IdentityRequest) (*IdentityResponse, error)
ModifyIdentity使用Fabric CA服务器修改身份
参数:
request包含有关身份的信息
返回更新的身份信息
使用示例：

// Create msp client
c, err := New(mockClientProvider())
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

identity, err := c.ModifyIdentity(&IdentityRequest{ID: "123", Affiliation: "org2", Secret: "top-secret"})
if err != nil {
    fmt.Printf("Modify identity return error %s\n", err)
    return
}
fmt.Printf("identity '%s' modified\n", identity.ID)
// output:
// identity '123' modified

10、重新登记用户

func (c *Client) Reenroll(enrollmentID string, opts ...EnrollmentOption) error
重新登记一个已登记用户，以便获得一个新的签名X509证书
参数:
enrollmentID是注册用户的登记ID
如果重新登记失败，返回出错信息。

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

username := randomUsername()

err = c.Enroll(username, WithSecret("enrollmentSecret"))
if err != nil {
    fmt.Printf("failed to enroll user: %s\n", err)
    return
}

err = c.Reenroll(username)
if err != nil {
    fmt.Printf("failed to reenroll user: %s\n", err)
    return
}

fmt.Println("reenroll user is completed")
// output:
// reenroll user is completed        

11、注册用户

func (c *Client) Register(request *RegistrationRequest) (string, error)
使用Fabric CA注册一个用户
参数:
request是注册请求
返回登记secret
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

_, err = c.Register(&RegistrationRequest{Name: randomUsername()})
if err != nil {
    fmt.Printf("Register return error %s\n", err)
    return
}
fmt.Println("register user is completed")
// output:
// register user is completed       

12、删除身份标识

func (c *Client) RemoveIdentity(request *RemoveIdentityRequest) (*IdentityResponse, error)
RemoveIdentity使用Fabric CA服务器删除身份标识。
参数:
request是包含要删除的身份的信息
返回已删除的身份信息
使用示例：

// Create msp client
c, err := New(mockClientProvider())
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

identity, err := c.RemoveIdentity(&RemoveIdentityRequest{ID: "123"})
if err != nil {
    fmt.Printf("Remove identity return error %s\n", err)
    return
}
fmt.Printf("identity '%s' removed\n", identity.ID)
// output:
// identity '123' removed

13、撤销用户

func (c *Client) Revoke(request *RevocationRequest) (*RevocationResponse, error)
使用Fabric CA的撤销一个用户
参数:
request是撤销请求
返回撤销响应
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

_, err = c.Revoke(&RevocationRequest{Name: "testuser"})
if err != nil {
    fmt.Printf("revoke return error %s\n", err)
}
fmt.Println("revoke user is completed")
// output:
// revoke user is completed  

14、选项构建

type ClientOption func(*Client) error

// WithOrg option
func WithOrg(orgName string) ClientOption

返回包含组织的ClientOption，作为参数
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx, WithOrg("org1"))
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

if c != nil {
    fmt.Println("msp client created with org")
}
// output:
// msp client created with org 

type enrollmentOptions struct {
   secret   string
   profile  string
   label    string
   typ      string
   attrReqs []*AttributeRequest
}

// EnrollmentOption describes a functional parameter for Enroll
type EnrollmentOption func(*enrollmentOptions) error
// WithSecret enrollment option
func WithSecret(secret string) EnrollmentOption

使用secret参数，返回EnrollmentOption，作为登记的选项
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

err = c.Enroll(randomUsername(), WithSecret("enrollmentSecret"))
if err != nil {
    fmt.Printf("failed to enroll user: %s\n", err)
    return
}
fmt.Println("enroll user is completed")
// output:
// enroll user is completed     

type requestOptions struct {
   CA string
}
// RequestOption func for each Opts argument
type RequestOption func(ctx context.Client, opts *requestOptions) error

// WithCA allows for specifying optional CA name
func WithCA(caname string) RequestOption

根据CA名称返回RequestOption
使用示例：

// Create msp client
c, err := New(mockClientProvider())
if err != nil {
    fmt.Println("failed to create msp client")
    return
}

results, err := c.GetAllIdentities(WithCA("CA"))
if err != nil {
    fmt.Printf("Get identities return error %s\n", err)
    return
}
fmt.Printf("%d identities retrieved\n", len(results))
// output:
// 2 identities retrieved

func WithType(typ string) EnrollmentOption
根据证书类型typ参数返回EnrollmentOption
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
fmt.Println("failed to create msp client")
return
}

err = c.Enroll(randomUsername(), WithSecret("enrollmentSecret"), WithType("x509") /*or idemix, which is not support now*/)
if err != nil {
fmt.Printf("failed to enroll user: %s\n", err)
return
}
fmt.Println("enroll user is completed")
// output:
// enroll user is completed

func WithProfile(profile string) EnrollmentOption
使用profile返回一个EnrollmentOption
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
fmt.Println("failed to create msp client")
return
}

err = c.Enroll(randomUsername(), WithSecret("enrollmentSecret"), WithProfile("tls"))
if err != nil {
fmt.Printf("failed to enroll user: %s\n", err)
return
}
fmt.Println("enroll user is completed")
// output:
// enroll user is completed

func WithLabel(label string) EnrollmentOption
使用label参数返回EnrollmentOption
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
fmt.Println("failed to create msp client")
return
}

err = c.Enroll(randomUsername(), WithSecret("enrollmentSecret"), WithLabel("ForFabric"))
if err != nil {
fmt.Printf("failed to enroll user: %s\n", err)
return
}
fmt.Println("enroll user is completed")
// output:
// enroll user is completed

func WithAttributeRequests(attrReqs []*AttributeRequest) EnrollmentOption
使用属性请求参数attrReqs返回EnrollmentOption
使用示例：

ctx := mockClientProvider()

// Create msp client
c, err := New(ctx)
if err != nil {
fmt.Println("failed to create msp client")
return
}

attrs := []*AttributeRequest{{Name: "name1", Optional: true}, {Name: "name2", Optional: true}}
err = c.Enroll(randomUsername(), WithSecret("enrollmentSecret"), WithAttributeRequests(attrs))
if err != nil {
fmt.Printf("failed to enroll user: %s\n", err)
return
}
fmt.Println("enroll user is completed")
// output:
// enroll user is completed