Skip to content

Commit

Permalink
[FAB-9244] 1. API for getting idemix credential
Browse files Browse the repository at this point in the history 
This change set contains API definition for getting credential
and associated doc changes.

Change-Id: Idb15f94c2108ab7c4f6a74e4c422e8ca0e699fc5
Signed-off-by: Anil Ambati <aambati@us.ibm.com>
  • Loading branch information
Anil Ambati committed May 11, 2018
1 parent f718bb5 commit f3bd5b9
Show file tree
Hide file tree
Showing 6 changed files with 225 additions and 17 deletions.
15 changes: 9 additions & 6 deletions api/client.go
View file
Expand Up @@ -63,17 +63,20 @@ type EnrollmentRequest struct {
Name string `json:"name" skip:"true"`
// The secret returned via Register
Secret string `json:"secret,omitempty" skip:"true" mask:"password"`
// Profile is the name of the signing profile to use in issuing the certificate
Profile string `json:"profile,omitempty" help:"Name of the signing profile to use in issuing the certificate"`
// Label is the label to use in HSM operations
Label string `json:"label,omitempty" help:"Label to use in HSM operations"`
// CSR is Certificate Signing Request info
CSR *CSRInfo `json:"csr,omitempty" help:"Certificate Signing Request info"`
// CAName is the name of the CA to connect to
CAName string `json:"caname,omitempty" skip:"true"`
// AttrReqs are requests for attributes to add to the certificate.
// Each attribute is added only if the requestor owns the attribute.
AttrReqs []*AttributeRequest `json:"attr_reqs,omitempty"`
// Profile is the name of the signing profile to use in issuing the X509 certificate
Profile string `json:"profile,omitempty" help:"Name of the signing profile to use in issuing the certificate"`
// Label is the label to use in HSM operations
Label string `json:"label,omitempty" help:"Label to use in HSM operations"`
// CSR is Certificate Signing Request info
CSR *CSRInfo `json:"csr,omitempty" help:"Certificate Signing Request info"`
// The type of the enrollment request: x509 or idemix
// The default is a request for an X509 enrollment certificate
Type string `def:"x509" help:"The type of enrollment request: 'x509' or 'idemix'"`
}

func (er EnrollmentRequest) String() string {
Expand Down
7 changes: 7 additions & 0 deletions api/net.go
View file
Expand Up @@ -18,6 +18,7 @@ package api

import (
"github.com/cloudflare/cfssl/signer"
"github.com/hyperledger/fabric/idemix"
)

/*
Expand All @@ -43,6 +44,12 @@ type EnrollmentRequestNet struct {
AttrReqs []*AttributeRequest `json:"attr_reqs,omitempty"`
}

// IdemixEnrollmentRequestNet is a request to enroll an identity and get idemix credential
type IdemixEnrollmentRequestNet struct {
*idemix.CredRequest `json:"request"`
CAName string `json:"caname"`
}

// ReenrollmentRequestNet is a request to reenroll an identity.
// This is useful to renew a certificate before it has expired.
type ReenrollmentRequestNet struct {
Expand Down
1 change: 1 addition & 0 deletions docs/source/clientcli.rst
View file
Expand Up @@ -31,6 +31,7 @@ Fabric-CA Client's CLI
--enrollment.attrs stringSlice A list of comma-separated attribute requests of the form <name>[:opt] (e.g. foo,bar:opt)
--enrollment.label string Label to use in HSM operations
--enrollment.profile string Name of the signing profile to use in issuing the certificate
--enrollment.type string The type of enrollment request: 'x509' or 'idemix' (default "x509")
-H, --home string Client's home directory (default "$HOME/.fabric-ca-client")
--id.affiliation string The identity's affiliation
--id.attrs stringSlice A list of comma-separated attributes of the form <name>=<value> (e.g. foo=foo1,bar=bar1)
Expand Down
1 change: 1 addition & 0 deletions docs/source/servercli.rst
View file
Expand Up @@ -40,6 +40,7 @@ Fabric-CA Server's CLI
-H, --home string Server's home directory (default "/etc/hyperledger/fabric-ca")
--intermediate.enrollment.label string Label to use in HSM operations
--intermediate.enrollment.profile string Name of the signing profile to use in issuing the certificate
--intermediate.enrollment.type string The type of enrollment request: 'x509' or 'idemix' (default "x509")
--intermediate.parentserver.caname string Name of the CA to connect to on fabric-ca-server
-u, --intermediate.parentserver.url string URL of the parent fabric-ca-server (e.g. http://<username>:<password>@<address>:<port)
--intermediate.tls.certfiles stringSlice A list of comma-separated PEM-encoded trusted certificate files (e.g. root1.pem,root2.pem)
Expand Down
42 changes: 35 additions & 7 deletions docs/source/users-guide.rst
View file
Expand Up @@ -52,13 +52,15 @@ Table of Contents
1. `Enrolling the bootstrap identity`_
2. `Registering a new identity`_
3. `Enrolling a peer identity`_
4. `Reenrolling an identity`_
5. `Revoking a certificate or identity`_
6. `Generating a CRL (Certificate Revocation List)`_
7. `Attribute-Based Access Control`_
8. `Dynamic Server Configuration Update`_
9. `Enabling TLS`_
10. `Contact specific CA instance`_
4. `Getting a CA certificate chain from another Fabric CA server`_
5. `Getting Identity Mixer credential for a user`_
6. `Reenrolling an identity`_
7. `Revoking a certificate or identity`_
8. `Generating a CRL (Certificate Revocation List)`_
9. `Attribute-Based Access Control`_
10. `Dynamic Server Configuration Update`_
11. `Enabling TLS`_
12. `Contact specific CA instance`_

6. `HSM`_

Expand Down Expand Up @@ -1446,6 +1448,32 @@ certificate in the chain is followed by its issuer's CA certificate. If you need
to return the CA chain in the opposite order, then set the environment variable ``CA_CHAIN_PARENT_FIRST``
to ``true`` and restart the Fabric CA server. The Fabric CA client will handle either order appropriately.

Getting Identity Mixer credential for a user
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Identity Mixer (Idemix) is a cryptographic protocol suite for privacy-preserving authentication and transfer of certified attributes.
Idemix allows users to authenticate with verifiers without the involvement of the issuer (CA) and selectively disclose only those attributes
that are required by the verifier and can do so without being linkable across their transactions.

Fabric CA server can issue Idemix credentials in addition to X509 certificates. An Idemix credential can be requested by sending the request to
the ``/api/v1/idemix/credential`` API endpoint. For more information on this and other Fabric CA server API endpoints, please refer to
`swagger-fabric-ca.json <https://github.com/hyperledger/fabric-ca/blob/master/swagger/swagger-fabric-ca.json>`_.

The Idemix credential issuance is a two step process. First, send a request with an empty body to the ``/api/v1/idemix/credential``
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
send another request with the credential request in the body to the ``/api/v1/idemix/credential`` API endpoint to get an Idemix credential,
and attribute names and values. Currently, only three attributes are supported:

- **OU** - organization unit of the user
- **IsAdmin** - if the user is an admin or not
- **EnrollmentID** - enrollment ID of the user

The ``/api/v1/idemix/credential`` API endpoint accepts both OAuth basic and token authorization headers. The basic authorization header should
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.

Note that Hyperledger Fabric will support clients/users to sign transactions with their Idemix credentials, but will only support X509 credentials
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
associated with creating authorization header and request payload, and with processing the response.

Reenrolling an Identity
~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
176 changes: 172 additions & 4 deletions swagger/swagger-fabric-ca.json
View file
Expand Up @@ -375,6 +375,175 @@
}
}
},
"/api/v1/idemix/credential": {
"post": {
"tags": [
"fabric-ca-server"
],
"description": "Get an Identity Mixer credential. Identity Mixer credential issuance is a two step process. First, a request with empty request body is sent to this endpoint. The Fabric CA server will respond back with a nonce. This nonce should be used to create a credential request. Next, a request with the credential request in the request body is sent to this endpoint. The server will respond back with a credential.",
"parameters": [
{
"name": "ca",
"in": "query",
"description": "The name of the CA to direct this request to within the server, or the default CA if not specified",
"type": "string"
},
{
"name": "Authorization",
"in": "header",
"description": "**basic** <base64 encoding of userid:password> (OR) **token** <An enrollment token consisting of two base 64 encoded parts separated by a period: an enrollment certificate; a signature over the certificate and body of request>",
"required": true,
"type": "string"
},
{
"name": "body",
"in": "body",
"description": "The request body",
"required": true,
"schema": {
"type": "object",
"properties": {
"request": {
"type": "string",
"description": "JSON encoding idemix.CredentialRequest struct"
},
"caname": {
"type": "string",
"description": "Name of the CA to direct this request to within the Fabric CA server"
}
},
"required": [
"request"
]
}
}
],
"responses": {
"201": {
"description": "Successfully returned a nonce or Identity Mixer credential",
"schema": {
"type": "object",
"properties": {
"Success": {
"type": "boolean",
"description": "Boolean indicating if the request was successful"
},
"Result": {
"type": "object",
"properties": {
"credential": {
"type": "string",
"description": "The credential in base64 encoding of the bytes of the Credential proto buffer"
},
"nonce": {
"type": "string",
"description": "The nonce in base 64 encoded format"
},
"attrs": {
"type": "object",
"properties": {
"OU": {
"type": "string",
"description": "The Organizational Unit of the identity that requested the credential"
},
"IsAdmin": {
"type": "string",
"description": "'true' if the identity that requested the credential is an admin"
},
"EnrollmentID": {
"type": "string",
"description": "The enrollment ID of the identity that requested the credential"
}
},
"required": [
"OU",
"IsAdmin",
"EnrollmentID"
]
},
"serverinfo": {
"type": "object",
"properties": {
"caname": {
"type": "string",
"description": "The name of the CA that issued the credential"
},
"cachain": {
"type": "string",
"description": "Base 64 encoded PEM-encoded certificate chain of the CA's signing certificate"
},
"issuerpublickey": {
"type": "string",
"description": "Base 64 encoding of the CA's idemix public key"
},
"version": {
"type": "string",
"description": "Version of the server"
}
},
"required": [
"caname",
"cachain",
"issuerpublickey",
"version"
]
}
}
},
"Errors": {
"type": "array",
"description": "A array of error messages (i.e. code and string messages).",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "Integer code denoting the type of error."
},
"message": {
"type": "string",
"description": "An error message"
}
},
"required": [
"code",
"message"
]
}
},
"Messages": {
"type": "array",
"description": "A array of informational messages (i.e. code and string messages).",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "Integer code denoting the type of message."
},
"message": {
"type": "string",
"description": "A more specific message."
}
},
"required": [
"code",
"message"
]
}
}
},
"required": [
"Success",
"Result",
"Errors",
"Messages"
]
}
}
}
}
},
"/api/v1/reenroll": {
"post": {
"tags": [
Expand Down Expand Up @@ -2519,8 +2688,8 @@
"type": "array",
"description": "An array of base64 encoded PEM-encoded certificates",
"items": {
"type": "string",
"description": "base64 encoded PEM-encoded CRL"
"type": "string",
"description": "base64 encoded PEM-encoded CRL"
}
},
"caname": {
Expand Down Expand Up @@ -2774,5 +2943,4 @@
}
}
}
}

}

0 comments on commit f3bd5b9

Please sign in to comment.