indy-sdk
Version:
Native bindings for hyperledger indy
1,102 lines (915 loc) • 142 kB
Markdown
# Indy SDK for Node.js
[](https://nodejs.org/api/documentation.html#documentation_stability_index)
Native bindings for [Hyperledger Indy](https://www.hyperledger.org/projects/hyperledger-indy).
- [Installing](#installing)
- [Usage](#usage)
- [API](#api)
* [IndyError](#indyerror)
* [anoncreds](#anoncreds)
* [blob_storage](#blob_storage)
* [crypto](#crypto)
* [did](#did)
* [ledger](#ledger)
* [non_secrets](#non_secrets)
* [pairwise](#pairwise)
* [payment](#payment)
* [pool](#pool)
* [wallet](#wallet)
* [logger](#logger)
* [cache](#cache)
* [mod](#mod)
- [Advanced](#advanced)
- [Contributing](#contributing)
## Installing
This module has a native compile step. It compiles C++ code and dynamically links to `libindy`.
You will need:
* C++ build tools and Python 3.6+. See [this](https://github.com/nodejs/node-gyp#installation) for platform recommendations.
* `libindy` v1.6+ in your system library path. (i.e. `/usr/lib/libindy.so` for linux)
Then you can install via npm:
```sh
npm install --save indy-sdk
```
#### Troubleshooting
Use environment variable `RUST_LOG={info|debug|trace}` to output logs of Libindy.
##### Linking errors
i.e. `ld: library not found for -llibindy`
First, make sure you have the latest libindy for your platform. Also make sure you have any other libraries it depends on. See [indy-sdk/doc](https://github.com/hyperledger/indy-sdk/tree/master/doc)
Second, make sure it's in the linker search path. The easiest way is to use the system library path.
* ubuntu `/usr/lib/libindy.so`
* osx `/usr/local/lib/libindy.dylib`
* windows use LD_LIBRARY_PATH to indicate the location of dll as specified below
If you want to put the library in a custom folder i.e. `/foo/bar/libindy.so` then you can do this:
```sh
LD_LIBRARY_PATH=/foo/bar npm i --save indy-sdk
```
Then when you run your code, you'll still need the `LD_LIBRARY_PATH` set.
```sh
LD_LIBRARY_PATH=/foo/bar node index.js
```
##### Other build errors
We use [node-gyp](https://github.com/nodejs/node-gyp#installation) to manage the cross-platform build. Their readme is quite helpful.
## Usage
```js
var indy = require('indy-sdk')
var did = '...'
var fullVerkey = '...'
indy.abbreviateVerkey(did, fullVerkey, function(err, verkey){
..
})
// if you do not provide a callback, a Promise is returned
var verkey = await indy.abbreviateVerkey(did, fullVerkey)
```
# API
### IndyError
All the functions may yield an IndyError. The errors are based on libindy error codes defined [here](https://github.com/hyperledger/indy-sdk/blob/master/libindy/include/indy_mod.h).
* `err.indyCode`: Int - code number from libindy
* `err.indyName`: String - name for the error code
* `err.indyMessage`: String - human-readable error description
* `err.indyBacktrace`: String? - if enabled, this is the libindy backtrace string
Collecting of backtrace can be enabled by:
1. Setting environment variable `RUST_BACKTRACE=1`
2. Calling [setRuntimeConfig](#setruntimeconfig--config-)(`{collect_backtrace: true}`)
### anoncreds
These functions wrap the Ursa algorithm as documented in this [paper](https://github.com/hyperledger/ursa/blob/master/libursa/docs/AnonCred.pdf):
And is documented in this [HIPE](https://github.com/hyperledger/indy-hipe/blob/c761c583b1e01c1e9d3ceda2b03b35336fdc8cc1/text/anoncreds-protocol/README.md):
#### issuerCreateSchema \( issuerDid, name, version, attrNames \) -> \[ id, schema \]
Create credential schema entity that describes credential attributes list and allows credentials
interoperability.
Schema is public and intended to be shared with all anoncreds workflow actors usually by publishing SCHEMA transaction
to Indy distributed ledger.
It is IMPORTANT for current version POST Schema in Ledger and after that GET it from Ledger
with correct seq\_no to save compatibility with Ledger.
After that can call issuerCreateAndStoreCredentialDef to build corresponding Credential Definition.
* `issuerDid`: String - DID of schema issuer
* `name`: String - a name the schema
* `version`: String - a version of the schema
* `attrNames`: Json - a list of schema attributes descriptions (the number of attributes should be less or equal than 125)
* __->__ [ `id`: String, `schema`: Json ] - schema\_id: identifier of created schema
schema\_json: schema as json
Errors: `Common*`, `Anoncreds*`
#### issuerCreateAndStoreCredentialDef \( wh, issuerDid, schema, tag, signatureType, config \) -> \[ credDefId, credDef \]
Create credential definition entity that encapsulates credentials issuer DID, credential schema, secrets used for signing credentials
and secrets used for credentials revocation.
Credential definition entity contains private and public parts. Private part will be stored in the wallet. Public part
will be returned as json intended to be shared with all anoncreds workflow actors usually by publishing CRED\_DEF transaction
to Indy distributed ledger.
It is IMPORTANT for current version GET Schema from Ledger with correct seq\_no to save compatibility with Ledger.
Note: Use combination of `issuerRotateCredentialDefStart` and `indy_issuer_rotate_credential_def_apply` functions
to generate new keys for an existing credential definition.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `issuerDid`: String - a DID of the issuer signing cred\_def transaction to the Ledger
* `schema`: Json - credential schema as a json
* `tag`: String - allows to distinct between credential definitions for the same issuer and schema
* `signatureType`: String - credential definition type \(optional, 'CL' by default\) that defines credentials signature and revocation math. Supported types are:
* 'CL': Camenisch-Lysyanskaya credential signature type that is implemented according to the algorithm in this paper:
https://github.com/hyperledger/ursa/blob/master/libursa/docs/AnonCred.pdf
And is documented in this HIPE:
https://github.com/hyperledger/indy-hipe/blob/c761c583b1e01c1e9d3ceda2b03b35336fdc8cc1/text/anoncreds-protocol/README.md
* `config`: Json - \(optional\) type-specific configuration of credential definition as json:
* 'CL':
* support\_revocation: whether to request non-revocation credential \(optional, default false\)
* __->__ [ `credDefId`: String, `credDef`: Json ] - cred\_def\_id: identifier of created credential definition
cred\_def\_json: public part of created credential definition
Errors: `Common*`, `Wallet*`, `Anoncreds*`
#### issuerRotateCredentialDefStart \( wh, credDefId, config \) -> credDef
Generate temporary credential definitional keys for an existing one (owned by the caller of the library).
Use `issuerRotateCredentialDefApply` function to set temporary keys as the main.
**WARNING**: Rotating the credential definitional keys will result in making all credentials issued under the previous keys unverifiable.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `credDefId`: String - an identifier of created credential definition stored in the wallet
* `config`: Json - \(optional\) type-specific configuration of credential definition as json:
* 'CL':
* support\_revocation: whether to request non-revocation credential \(optional, default false\)
* __->__ `credDef`: Json - public part of temporary created credential definition
Errors: `Common*`, `Wallet*`, `Anoncreds*`
#### issuerRotateCredentialDefApply \( wh, credDefId \) -> void
Apply temporary keys as main for an existing Credential Definition (owned by the caller of the library).
**WARNING**: Rotating the credential definitional keys will result in making all credentials issued under the previous keys unverifiable.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `credDefId`: String - an identifier of created credential definition stored in the wallet
* __->__ void
Errors: `Common*`, `Wallet*`, `Anoncreds*`
#### issuerCreateAndStoreRevocReg \( wh, issuerDid, revocDefType, tag, credDefId, config, tailsWriterHandle \) -> \[ revocRegId, revocRegDef, revocRegEntry \]
Create a new revocation registry for the given credential definition as tuple of entities
- Revocation registry definition that encapsulates credentials definition reference, revocation type specific configuration and
secrets used for credentials revocation
- Revocation registry state that stores the information about revoked entities in a non-disclosing way. The state can be
represented as ordered list of revocation registry entries were each entry represents the list of revocation or issuance operations.
Revocation registry definition entity contains private and public parts. Private part will be stored in the wallet. Public part
will be returned as json intended to be shared with all anoncreds workflow actors usually by publishing REVOC\_REG\_DEF transaction
to Indy distributed ledger.
Revocation registry state is stored on the wallet and also intended to be shared as the ordered list of REVOC\_REG\_ENTRY transactions.
This call initializes the state in the wallet and returns the initial entry.
Some revocation registry types \(for example, 'CL\_ACCUM'\) can require generation of binary blob called tails used to hide information about revoked credentials in public
revocation registry and intended to be distributed out of leger \(REVOC\_REG\_DEF transaction will still contain uri and hash of tails\).
This call requires access to pre-configured blob storage writer instance handle that will allow to write generated tails.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `issuerDid`: String - a DID of the issuer signing transaction to the Ledger
* `revocDefType`: String - revocation registry type \(optional, default value depends on credential definition type\). Supported types are:
* 'CL\_ACCUM': Type-3 pairing based accumulator implemented according to the algorithm in this paper:
https://github.com/hyperledger/ursa/blob/master/libursa/docs/AnonCred.pdf
This type is default for 'CL' credential definition type.
* `tag`: String - allows to distinct between revocation registries for the same issuer and credential definition
* `credDefId`: String - id of stored in ledger credential definition
* `config`: Json - type-specific configuration of revocation registry as json:
* 'CL\_ACCUM':
```
{
"issuance_type": (optional) type of issuance. Currently supported:
1) ISSUANCE_BY_DEFAULT: all indices are assumed to be issued and initial accumulator is calculated over all indices;
Revocation Registry is updated only during revocation.
2) ISSUANCE_ON_DEMAND: nothing is issued initially accumulator is 1 (used by default);
"max_cred_num": maximum number of credentials the new registry can process (optional, default 100000)
}
````
* `tailsWriterHandle`: Handle (Number) - handle of blob storage to store tails
NOTE:
Recursive creation of folder for Default Tails Writer (correspondent to `tailsWriterHandle`)
in the system-wide temporary directory may fail in some setup due to permissions: `IO error: Permission denied`.
In this case use `TMPDIR` environment variable to define temporary directory specific for an application.
* __->__ [ `revocRegId`: String, `revocRegDef`: Json, `revocRegEntry`: Json ] - revoc\_reg\_id: identifier of created revocation registry definition
revoc\_reg\_def\_json: public part of revocation registry definition
revoc\_reg\_entry\_json: revocation registry entry that defines initial state of revocation registry
Errors: `Common*`, `Wallet*`, `Anoncreds*`
#### issuerCreateCredentialOffer \( wh, credDefId \) -> credOffer
Create credential offer that will be used by Prover for
credential request creation. Offer includes nonce and key correctness proof
for authentication between protocol steps and integrity checking.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `credDefId`: String - id of credential definition stored in the wallet
* __->__ `credOffer`: Json - credential offer json:
```
{
"schema_id": string,
"cred_def_id": string,
// Fields below can depend on Cred Def type
"nonce": string,
"key_correctness_proof" : key correctness proof for credential definition correspondent to cred_def_id
(opaque type that contains data structures internal to Ursa.
It should not be parsed and are likely to change in future versions).
}
````
Errors: `Common*`, `Wallet*`, `Anoncreds*`
#### issuerCreateCredential \( wh, credOffer, credReq, credValues, revRegId, blobStorageReaderHandle \) -> \[ cred, credRevocId, revocRegDelta \]
Check Cred Request for the given Cred Offer and issue Credential for the given Cred Request.
Cred Request must match Cred Offer. The credential definition and revocation registry definition
referenced in Cred Offer and Cred Request must be already created and stored into the wallet.
Information for this credential revocation will be store in the wallet as part of revocation registry under
generated cred\_revoc\_id local for this wallet.
This call returns revoc registry delta as json file intended to be shared as REVOC\_REG\_ENTRY transaction.
Note that it is possible to accumulate deltas to reduce ledger load.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `credOffer`: Json - a cred offer created by issuerCreateCredentialOffer
* `credReq`: Json - a credential request created by proverCreateCredentialReq
* `credValues`: Json - a credential containing attribute values for each of requested attribute names.
Example:
```
{
"attr1" : {"raw": "value1", "encoded": "value1_as_int" },
"attr2" : {"raw": "value1", "encoded": "value1_as_int" }
}
````
If you want to use empty value for some credential field, you should set "raw" to "" and "encoded" should not be empty
* `revRegId`: String - id of revocation registry stored in the wallet
* `blobStorageReaderHandle`: Handle (Number) - configuration of blob storage reader handle that will allow to read revocation tails
* __->__ [ `cred`: Json, `credRevocId`: String, `revocRegDelta`: Json ] - cred\_json: Credential json containing signed credential values
```
{
"schema_id": string,
"cred_def_id": string,
"rev_reg_def_id", Optional<string>,
"values": <see cred_values_json above>,
// Fields below can depend on Cred Def type
"signature": <credential signature>,
(opaque type that contains data structures internal to Ursa.
It should not be parsed and are likely to change in future versions).
"signature_correctness_proof": <signature_correctness_proof>
(opaque type that contains data structures internal to Ursa.
It should not be parsed and are likely to change in future versions).
}
cred_revoc_id: local id for revocation info (Can be used for revocation of this credential)
revoc_reg_delta_json: Revocation registry delta json with a newly issued credential
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### issuerRevokeCredential \( wh, blobStorageReaderHandle, revRegId, credRevocId \) -> revocRegDelta
Revoke a credential identified by a cred\_revoc\_id \(returned by issuerCreateCredential\).
The corresponding credential definition and revocation registry must be already
created an stored into the wallet.
This call returns revoc registry delta as json file intended to be shared as REVOC\_REG\_ENTRY transaction.
Note that it is possible to accumulate deltas to reduce ledger load.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `blobStorageReaderHandle`: Handle (Number)
* `revRegId`: String - id of revocation registry stored in wallet
* `credRevocId`: String - local id for revocation info
* __->__ `revocRegDelta`: Json - revoc\_reg\_delta\_json: Revocation registry delta json with a revoked credential
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### issuerMergeRevocationRegistryDeltas \( revRegDelta, otherRevRegDelta \) -> mergedRevRegDelta
Merge two revocation registry deltas \(returned by issuerCreateCredential or issuerRevokeCredential\) to accumulate common delta.
Send common delta to ledger to reduce the load.
* `revRegDelta`: Json - revocation registry delta.
* `otherRevRegDelta`: Json - revocation registry delta for which PrevAccum value is equal to current accum value of rev\_reg\_delta\_json.
* __->__ `mergedRevRegDelta`: Json - merged\_rev\_reg\_delta: Merged revocation registry delta
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverCreateMasterSecret \( wh, masterSecretId \) -> outMasterSecretId
Creates a master secret with a given id and stores it in the wallet.
The id must be unique.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `masterSecretId`: String - \(optional, if not present random one will be generated\) new master id
* __->__ `outMasterSecretId`: String - out\_master\_secret\_id: Id of generated master secret
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverCreateCredentialReq \( wh, proverDid, credOffer, credDef, masterSecretId \) -> \[ credReq, credReqMetadata \]
Creates a credential request for the given credential offer.
The method creates a blinded master secret for a master secret identified by a provided name.
The master secret identified by the name must be already stored in the secure wallet \(see prover\_create\_master\_secret\)
The blinded master secret is a part of the credential request.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `proverDid`: String - a DID of the prover
* `credOffer`: Json - credential offer as a json containing information about the issuer and a credential
* `credDef`: Json - credential definition json related to <cred\_def\_id> in <cred\_offer\_json>
* `masterSecretId`: String - the id of the master secret stored in the wallet
* __->__ [ `credReq`: Json, `credReqMetadata`: Json ] - cred\_req\_json: Credential request json for creation of credential by Issuer
```
{
"prover_did" : string,
"cred_def_id" : string,
// Fields below can depend on Cred Def type
"blinded_ms" : <blinded_master_secret>,
(opaque type that contains data structures internal to Ursa.
It should not be parsed and are likely to change in future versions).
"blinded_ms_correctness_proof" : <blinded_ms_correctness_proof>,
(opaque type that contains data structures internal to Ursa.
It should not be parsed and are likely to change in future versions).
"nonce": string
}
cred_req_metadata_json: Credential request metadata json for further processing of received form Issuer credential.
Note: cred_req_metadata_json mustn't be shared with Issuer.
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverStoreCredential \( wh, credId, credReqMetadata, cred, credDef, revRegDef \) -> outCredId
Check credential provided by Issuer for the given credential request,
updates the credential by a master secret and stores in a secure wallet.
To support efficient and flexible search the following tags will be created for stored credential:
```
{
"schema_id": <credential schema id>,
"schema_issuer_did": <credential schema issuer did>,
"schema_name": <credential schema name>,
"schema_version": <credential schema version>,
"issuer_did": <credential issuer did>,
"cred_def_id": <credential definition id>,
"rev_reg_id": <credential revocation registry id>, // "None" as string if not present
// for every attribute in <credential values>
"attr::<attribute name>::marker": "1",
"attr::<attribute name>::value": <attribute raw value>,
}
````
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `credId`: String - \(optional, default is a random one\) identifier by which credential will be stored in the wallet
* `credReqMetadata`: Json - a credential request metadata created by proverCreateCredentialReq
* `cred`: Json - credential json received from issuer
* `credDef`: Json - credential definition json related to <cred\_def\_id> in <cred\_json>
* `revRegDef`: Json - revocation registry definition json related to <rev\_reg\_def\_id> in <cred\_json>
* __->__ `outCredId`: String - out\_cred\_id: identifier by which credential is stored in the wallet
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverGetCredentials \( wh, filter \) -> credentials
Gets human readable credentials according to the filter.
If filter is NULL, then all credentials are returned.
Credentials can be filtered by Issuer, credential\_def and\/or Schema.
NOTE: This method is deprecated because immediately returns all fetched credentials.
Use <proverSearchCredentials> to fetch records by small batches.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `filter`: Json - filter for credentials
```
{
"schema_id": string, (Optional)
"schema_issuer_did": string, (Optional)
"schema_name": string, (Optional)
"schema_version": string, (Optional)
"issuer_did": string, (Optional)
"cred_def_id": string, (Optional)
}
````
* __->__ `credentials`: Json - credentials json
```
[{
"referent": string, // cred_id in the wallet
"attrs": {"key1":"raw_value1", "key2":"raw_value2"},
"schema_id": string,
"cred_def_id": string,
"rev_reg_id": Optional<string>,
"cred_rev_id": Optional<string>
}]
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverGetCredential \( wh, credId \) -> credential
Gets human readable credential by the given id.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `credId`: String - Identifier by which requested credential is stored in the wallet
* __->__ `credential`: Json - credential json:
```
{
"referent": string, // cred_id in the wallet
"attrs": {"key1":"raw_value1", "key2":"raw_value2"},
"schema_id": string,
"cred_def_id": string,
"rev_reg_id": Optional<string>,
"cred_rev_id": Optional<string>
}
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverSearchCredentials \( wh, query \) -> \[ sh, totalCount \]
Search for credentials stored in wallet.
Credentials can be filtered by tags created during saving of credential.
Instead of immediately returning of fetched credentials
this call returns search\_handle that can be used later
to fetch records by small batches \(with proverFetchCredentials\).
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `query`: Json - Wql query filter for credentials searching based on tags.
where query: indy-sdk\/doc\/design\/011-wallet-query-language\/README.md
* __->__ [ `sh`: Handle (Number), `totalCount`: Number ] - search\_handle: Search handle that can be used later to fetch records by small batches \(with proverFetchCredentials\)
total\_count: Total count of records
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverFetchCredentials \( sh, count \) -> credentials
Fetch next credentials for search.
* `sh`: Handle (Number) - Search handle \(created by proverSearchCredentials\)
* `count`: Number - Count of credentials to fetch
* __->__ `credentials`: Json - credentials\_json: List of human readable credentials:
```
[{
"referent": string, // cred_id in the wallet
"attrs": {"key1":"raw_value1", "key2":"raw_value2"},
"schema_id": string,
"cred_def_id": string,
"rev_reg_id": Optional<string>,
"cred_rev_id": Optional<string>
}]
NOTE: The list of length less than the requested count means credentials search iterator is completed.
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverCloseCredentialsSearch \( sh \) -> void
Close credentials search \(make search handle invalid\)
* `sh`: Handle (Number) - Search handle \(created by proverSearchCredentials\)
* __->__ void
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverGetCredentialsForProofReq \( wh, proofRequest \) -> credentials
Gets human readable credentials matching the given proof request.
NOTE: This method is deprecated because immediately returns all fetched credentials.
Use <proverSearchCredentialsForProofReq> to fetch records by small batches.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `proofRequest`: Json - proof request json
```
{
"name": string,
"version": string,
"nonce": string, - a decimal number represented as a string (use `generateNonce` function to generate 80-bit number)
"requested_attributes": { // set of requested attributes
"<attr_referent>": <attr_info>, // see below
...,
},
"requested_predicates": { // set of requested predicates
"<predicate_referent>": <predicate_info>, // see below
...,
},
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval for each attribute
// (can be overridden on attribute level)
"ver": Optional<str> - proof request version:
- omit to use unqualified identifiers for restrictions
- "1.0" to use unqualified identifiers for restrictions
- "2.0" to use fully qualified identifiers for restrictions
}
where:
attr_info: Describes requested attribute
{
"name": Optional<string>, // attribute name, (case insensitive and ignore spaces)
"names": Optional<[string, string]>, // attribute names, (case insensitive and ignore spaces)
// NOTE: should either be "name" or "names", not both and not none of them.
// Use "names" to specify several attributes that have to match a single credential.
"restrictions": Optional<wql query>, // see below
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval this attribute
// (overrides proof level interval)
}
predicate_referent: Proof-request local identifier of requested attribute predicate
predicate_info: Describes requested attribute predicate
{
"name": attribute name, (case insensitive and ignore spaces)
"p_type": predicate type (">=", ">", "<=", "<")
"p_value": predicate value
"restrictions": Optional<wql query>, // see below
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval this attribute
// (overrides proof level interval)
}
non_revoc_interval: Defines non-revocation interval
{
"from": Optional<int>, // timestamp of interval beginning
"to": Optional<int>, // timestamp of interval ending
}
````
* __->__ `credentials`: Json - credentials\_json: json with credentials for the given proof request.
```
{
"requested_attrs": {
"<attr_referent>": [{ cred_info: <credential_info>, interval: Optional<non_revoc_interval> }],
...,
},
"requested_predicates": {
"requested_predicates": [{ cred_info: <credential_info>, timestamp: Optional<integer> }, { cred_info: <credential_2_info>, timestamp: Optional<integer> }],
"requested_predicate_2_referent": [{ cred_info: <credential_2_info>, timestamp: Optional<integer> }]
}
}, where credential is
{
"referent": <string>,
"attrs": {"attr_name" : "attr_raw_value"},
"schema_id": string,
"cred_def_id": string,
"rev_reg_id": Optional<int>,
"cred_rev_id": Optional<int>,
}
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverSearchCredentialsForProofReq \( wh, proofRequest, extraQuery \) -> sh
Search for credentials matching the given proof request.
Instead of immediately returning of fetched credentials
this call returns search\_handle that can be used later
to fetch records by small batches \(with proverFetchCredentialsForProofReq\).
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `proofRequest`: Json - proof request json
```
{
"name": string,
"version": string,
"nonce": string, - a decimal number represented as a string (use `generateNonce` function to generate 80-bit number)
"requested_attributes": { // set of requested attributes
"<attr_referent>": <attr_info>, // see below
...,
},
"requested_predicates": { // set of requested predicates
"<predicate_referent>": <predicate_info>, // see below
...,
},
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval for each attribute
// (can be overridden on attribute level)
"ver": Optional<str> - proof request version:
- omit to use unqualified identifiers for restrictions
- "1.0" to use unqualified identifiers for restrictions
- "2.0" to use fully qualified identifiers for restrictions
}
where:
attr_info: Describes requested attribute
{
"name": Optional<string>, // attribute name, (case insensitive and ignore spaces)
"names": Optional<[string, string]>, // attribute names, (case insensitive and ignore spaces)
// NOTE: should either be "name" or "names", not both and not none of them.
// Use "names" to specify several attributes that have to match a single credential.
"restrictions": Optional<wql query>, // see below
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval this attribute
// (overrides proof level interval)
}
predicate_referent: Proof-request local identifier of requested attribute predicate
predicate_info: Describes requested attribute predicate
{
"name": attribute name, (case insensitive and ignore spaces)
"p_type": predicate type (">=", ">", "<=", "<")
"p_value": predicate value
"restrictions": Optional<wql query>, // see below
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval this attribute
// (overrides proof level interval)
}
non_revoc_interval: Defines non-revocation interval
{
"from": Optional<int>, // timestamp of interval beginning
"to": Optional<int>, // timestamp of interval ending
}
````
* `extraQuery`: Json - \(Optional\) List of extra queries that will be applied to correspondent attribute\/predicate:
```
{
"<attr_referent>": <wql query>,
"<predicate_referent>": <wql query>,
}
where wql query: indy-sdk/docs/design/011-wallet-query-language/README.md
````
* __->__ `sh`: Handle (Number) - search\_handle: Search handle that can be used later to fetch records by small batches \(with proverFetchCredentialsForProofReq\)
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverFetchCredentialsForProofReq \( sh, itemReferent, count \) -> credentials
Fetch next credentials for the requested item using proof request search
handle \(created by proverSearchCredentialsForProofReq\).
* `sh`: Handle (Number) - Search handle \(created by proverSearchCredentialsForProofReq\)
* `itemReferent`: String - Referent of attribute\/predicate in the proof request
* `count`: Number - Count of credentials to fetch
* __->__ `credentials`: Json - credentials\_json: List of credentials for the given proof request.
```
[{
cred_info: <credential_info>,
interval: Optional<non_revoc_interval>
}]
where
credential_info:
{
"referent": <string>,
"attrs": {"attr_name" : "attr_raw_value"},
"schema_id": string,
"cred_def_id": string,
"rev_reg_id": Optional<int>,
"cred_rev_id": Optional<int>,
}
non_revoc_interval:
{
"from": Optional<int>, // timestamp of interval beginning
"to": Optional<int>, // timestamp of interval ending
}
NOTE: The list of length less than the requested count means that search iterator
correspondent to the requested <item_referent> is completed.
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverCloseCredentialsSearchForProofReq \( sh \) -> void
Close credentials search for proof request \(make search handle invalid\)
* `sh`: Handle (Number) - Search handle \(created by proverSearchCredentialsForProofReq\)
* __->__ void
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### proverCreateProof \( wh, proofReq, requestedCredentials, masterSecretName, schemas, credentialDefs, revStates \) -> proof
Creates a proof according to the given proof request
Either a corresponding credential with optionally revealed attributes or self-attested attribute must be provided
for each requested attribute \(see proverGetCredentials\_for\_pool\_req\).
A proof request may request multiple credentials from different schemas and different issuers.
All required schemas, public keys and revocation registries must be provided.
The proof request also contains nonce.
The proof contains either proof or self-attested attribute value for each requested attribute.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `proofReq`: Json - proof request json
```
{
"name": string,
"version": string,
"nonce": string, - a decimal number represented as a string (use `generateNonce` function to generate 80-bit number)
"requested_attributes": { // set of requested attributes
"<attr_referent>": <attr_info>, // see below
...,
},
"requested_predicates": { // set of requested predicates
"<predicate_referent>": <predicate_info>, // see below
...,
},
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval for each attribute
// (can be overridden on attribute level)
"ver": Optional<str> - proof request version:
- omit to use unqualified identifiers for restrictions
- "1.0" to use unqualified identifiers for restrictions
- "2.0" to use fully qualified identifiers for restrictions
}
where:
attr_info: Describes requested attribute
{
"name": Optional<string>, // attribute name, (case insensitive and ignore spaces)
"names": Optional<[string, string]>, // attribute names, (case insensitive and ignore spaces)
// NOTE: should either be "name" or "names", not both and not none of them.
// Use "names" to specify several attributes that have to match a single credential.
"restrictions": Optional<wql query>, // see below
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval this attribute
// (overrides proof level interval)
}
predicate_referent: Proof-request local identifier of requested attribute predicate
predicate_info: Describes requested attribute predicate
{
"name": attribute name, (case insensitive and ignore spaces)
"p_type": predicate type (">=", ">", "<=", "<")
"p_value": predicate value
"restrictions": Optional<wql query>, // see below
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval this attribute
// (overrides proof level interval)
}
non_revoc_interval: Defines non-revocation interval
{
"from": Optional<int>, // timestamp of interval beginning
"to": Optional<int>, // timestamp of interval ending
}
````
* `requestedCredentials`: Json - either a credential or self-attested attribute for each requested attribute
```
{
"self_attested_attributes": {
"self_attested_attribute_referent": string
},
"requested_attributes": {
"requested_attribute_referent_1": {"cred_id": string, "timestamp": Optional<number>, revealed: <bool> }},
"requested_attribute_referent_2": {"cred_id": string, "timestamp": Optional<number>, revealed: <bool> }}
},
"requested_predicates": {
"requested_predicates_referent_1": {"cred_id": string, "timestamp": Optional<number> }},
}
}
````
* `masterSecretName`: String
* `schemas`: Json - all schemas json participating in the proof request
```
{
<schema1_id>: <schema1_json>,
<schema2_id>: <schema2_json>,
<schema3_id>: <schema3_json>,
}
````
* `credentialDefs`: Json - all credential definitions json participating in the proof request
```
{
"cred_def1_id": <credential_def1_json>,
"cred_def2_id": <credential_def2_json>,
"cred_def3_id": <credential_def3_json>,
}
````
* `revStates`: Json - all revocation states json participating in the proof request
```
{
"rev_reg_def1_id or credential_1_id"": {
"timestamp1": <rev_state1>,
"timestamp2": <rev_state2>,
},
"rev_reg_def2_id or credential_2_id"": {
"timestamp3": <rev_state3>
},
"rev_reg_def3_id or credential_3_id"": {
"timestamp4": <rev_state4>
},
} - Note: use credential_id instead rev_reg_id in case proving several credentials from the same revocation registry.
where
where wql query: indy-sdk/docs/design/011-wallet-query-language/README.md
````
* __->__ `proof`: Json - Proof json
For each requested attribute either a proof \(with optionally revealed attribute value\) or
self-attested attribute value is provided.
Each proof is associated with a credential and corresponding schema\_id, cred\_def\_id, rev\_reg\_id and timestamp.
There is also aggregated proof part common for all credential proofs.
```
{
"requested_proof": {
"revealed_attrs": {
"requested_attr1_id": {sub_proof_index: number, raw: string, encoded: string},
"requested_attr4_id": {sub_proof_index: number: string, encoded: string},
},
"revealed_attr_groups": {
"requested_attr5_id": {
"sub_proof_index": number,
"values": {
"attribute_name": {
"raw": string,
"encoded": string
}
},
}
},
"unrevealed_attrs": {
"requested_attr3_id": {sub_proof_index: number}
},
"self_attested_attrs": {
"requested_attr2_id": self_attested_value,
},
"requested_predicates": {
"requested_predicate_1_referent": {sub_proof_index: int},
"requested_predicate_2_referent": {sub_proof_index: int},
}
}
"proof": {
"proofs": [ <credential_proof>, <credential_proof>, <credential_proof> ],
"aggregated_proof": <aggregated_proof>
} (opaque type that contains data structures internal to Ursa.
It should not be parsed and are likely to change in future versions).
"identifiers": [{schema_id, cred_def_id, Optional<rev_reg_id>, Optional<timestamp>}]
}
````
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### verifierVerifyProof \( proofRequest, proof, schemas, credentialDefsJsons, revRegDefs, revRegs \) -> valid
Verifies a proof \(of multiple credential\).
All required schemas, public keys and revocation registries must be provided.
IMPORTANT: You must use *_id's (`schema_id`, `cred_def_id`, `rev_reg_id`) listed in `proof[identifiers]`
as the keys for corresponding `schemas`, `credentialDefsJsons`, `revRegDefs`, `revRegs` objects.
* `proofRequest`: Json - proof request json
```
{
"name": string,
"version": string,
"nonce": string, - a decimal number represented as a string (use `generateNonce` function to generate 80-bit number)
"requested_attributes": { // set of requested attributes
"<attr_referent>": <attr_info>, // see below
...,
},
"requested_predicates": { // set of requested predicates
"<predicate_referent>": <predicate_info>, // see below
...,
},
"non_revoked": Optional<<non_revoc_interval>>, // see below,
// If specified prover must proof non-revocation
// for date in this interval for each attribute
// (can be overridden on attribute level)
"ver": Optional<str> - proof request version:
- omit to use unqualified identifiers for restrictions
- "1.0" to use unqualified identifiers for restrictions
- "2.0" to use fully qualified identifiers for restrictions
}
````
* `proof`: Json - created for request proof json
```
{
"requested_proof": {
"revealed_attrs": {
"requested_attr1_id": {sub_proof_index: number, raw: string, encoded: string}, // NOTE: check that `encoded` value match to `raw` value on application level
"requested_attr4_id": {sub_proof_index: number: string, encoded: string}, // NOTE: check that `encoded` value match to `raw` value on application level
},
"revealed_attr_groups": {
"requested_attr5_id": {
"sub_proof_index": number,
"values": {
"attribute_name": {
"raw": string,
"encoded": string
}
}, // NOTE: check that `encoded` value match to `raw` value on application level
}
},
"unrevealed_attrs": {
"requested_attr3_id": {sub_proof_index: number}
},
"self_attested_attrs": {
"requested_attr2_id": self_attested_value,
},
"requested_predicates": {
"requested_predicate_1_referent": {sub_proof_index: int},
"requested_predicate_2_referent": {sub_proof_index: int},
}
}
"proof": {
"proofs": [ <credential_proof>, <credential_proof>, <credential_proof> ],
"aggregated_proof": <aggregated_proof>
}
"identifiers": [{schema_id, cred_def_id, Optional<rev_reg_id>, Optional<timestamp>}]
}
````
* `schemas`: Json - all schema jsons participating in the proof
```
{
<schema1_id>: <schema1_json>,
<schema2_id>: <schema2_json>,
<schema3_id>: <schema3_json>,
}
````
* `credentialDefsJsons`: Json
* `revRegDefs`: Json - all revocation registry definitions json participating in the proof
```
{
"rev_reg_def1_id": <rev_reg_def1_json>,
"rev_reg_def2_id": <rev_reg_def2_json>,
"rev_reg_def3_id": <rev_reg_def3_json>,
}
````
* `revRegs`: Json - all revocation registries json participating in the proof
```
{
"rev_reg_def1_id": {
"timestamp1": <rev_reg1>,
"timestamp2": <rev_reg2>,
},
"rev_reg_def2_id": {
"timestamp3": <rev_reg3>
},
"rev_reg_def3_id": {
"timestamp4": <rev_reg4>
},
}
````
* __->__ `valid`: Boolean - valid: true - if signature is valid, false - otherwise
Errors: `Annoncreds*`, `Common*`, `Wallet*`
#### createRevocationState \( blobStorageReaderHandle, revRegDef, revRegDelta, timestamp, credRevId \) -> revState
Create revocation state for a credential that corresponds to a particular time.
Note that revocation delta must cover the whole registry existence time.
You can use `from`: `0` and `to`: `needed_time` as parameters for building request to get correct revocation delta.
The resulting revocation state and provided timestamp can be saved and reused later with applying a new
revocation delta with `updateRevocationState` function.
This new delta should be received with parameters: `from`: `timestamp` and `to`: `needed_time`.
* `blobStorageReaderHandle`: Handle (Number) - configuration of blob storage reader handle that will allow to read revocation tails
* `revRegDef`: Json - revocation registry definition json
* `revRegDelta`: Json - revocation registry delta which covers the whole registry existence time
* `timestamp`: Timestamp (Number) - time represented as a total number of seconds from Unix Epoch
* `credRevId`: String - user credential revocation id in revocation registry
* __->__ `revState`: Json - revocation state json:
```
{
"rev_reg": <revocation registry>,
"witness": <witness>,
"timestamp" : integer
}
````
Errors: `Common*`, `Wallet*`, `Anoncreds*`
#### updateRevocationState \( blobStorageReaderHandle, revState, revRegDef, revRegDelta, timestamp, credRevId \) -> updatedRevState
Create a new revocation state for a credential based on a revocation state created before.
Note that provided revocation delta must cover the registry gap from based state creation until the specified time
(this new delta should be received with parameters: `from`: `state_timestamp` and `to`: `needed_time`).
This function reduces the calculation time.
The resulting revocation state and provided timestamp can be saved and reused later by applying a new revocation delta again.
* `blobStorageReaderHandle`: Handle (Number) - configuration of blob storage reader handle that will allow to read revocation tails
* `revState`: Json - revocation registry state json
* `revRegDef`: Json - revocation registry definition json
* `revRegDelta`: Json - revocation registry definition delta which covers the gap form original `rev_state_json` creation till the requested timestamp
* `timestamp`: Timestamp (Number) - time represented as a total number of seconds from Unix Epoch
* `credRevId`: String - user credential revocation id in revocation registry
* __->__ `updatedRevState`: Json - revocation state json:
```
{
"rev_reg": <revocation registry>,
"witness": <witness>,
"timestamp" : integer
}
````
Errors: `Common*`, `Wallet*`, `Anoncreds*`
#### generateNonce \( \) -> nonce
Generates 80-bit numbers that can be used as a nonce for proof request.
* __->__ `nonce`: Json - generated number as a string
Errors: `Common*`
#### toUnqualified \( entity \) -> res
Get unqualified form (short form without method) of a fully qualified entity like DID.
This function should be used to the proper casting of fully qualified entity to unqualified form in the following cases:
1) Issuer, which works with fully qualified identifiers, creates a Credential Offer for Prover, which doesn't support fully qualified identifiers.
2) Verifier prepares a Proof Request based on fully qualified identifiers or Prover, which doesn't support fully qualified identifiers.
3) another case when casting to unqualified form needed
* `entity`: String - target entity to disqualify. Can be one of: Did, SchemaId, CredentialDefinitionId, RevocationRegistryId, Schema, CredentialDefinition, RevocationRegistryDefinition, CredentialOffer, CredentialRequest, ProofRequest.
* __->__ `res`: Json - entity either in unqualified form or original if casting isn't possible
### blob_storage
#### openBlobStorageReader \( type, config \) -> handle
* `type`: String
* `config`: Json
* __->__ `handle`: Handle (Number)
#### openBlobStorageWriter \( type, config \) -> handle
* `type`: String
* `config`: Json
* __->__ `handle`: Handle (Number)
### crypto
#### createKey \( wh, key \) -> vk
Creates keys pair and stores in the wallet.
* `wh`: Handle (Number) - wallet handle (created by openWallet)
* `key`: Json - Key information as json. Example:
```
{
"seed": string, (optional) Seed that allows deterministic key creation (if not set random one will be created).
Can be UTF-8, base64 or hex string.
"crypto_type": string, // Optional (if not set then ed25519 curve is used); Currently only 'ed25519' value is supported for this field.
}
````
* __->__ `vk`: String - Ver key of generated key pair, also used as key identifier
Errors: `Common*`, `Wallet*`, `Crypto*`
#### setKeyMetadata \( wh, verkey, metadata \) -> void
Saves\/rep