From 8c8292d88ff78a1e63543bd37d0e263b50f87bf6 Mon Sep 17 00:00:00 2001 From: Yarmo Mackenbach Date: Wed, 18 Nov 2020 21:51:39 +0100 Subject: [PATCH] Update docs --- docs/_coverpage.md | 2 +- docs/api.md | 153 ++++++++++++++++++++++++++++++++++++++++++- docs/installation.md | 2 +- 3 files changed, 152 insertions(+), 5 deletions(-) diff --git a/docs/_coverpage.md b/docs/_coverpage.md index 1cabc5d..d9d32ee 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -1,4 +1,4 @@ -# doip.js 0.4.2 +# doip.js 0.5.0 diff --git a/docs/api.md b/docs/api.md index 83ae394..ccea21d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,8 +1,8 @@ # API -## verify +## claims.verify(uri, [fingerprint], [opts]) -_(async)_ doip.verify(uri, [fingerprint], [opts]) +_(async)_ doip.claims.verify(uri, [fingerprint], [opts]) Verifies the identity behind the provided **uri** using the **fingerprint**. @@ -28,7 +28,8 @@ the one suggested by the service provider. **Returns** An object with the results of the identity claim verification containing a -boolean named `isVerified` and a [serviceproviderData](serviceproviderdataobject.md#service-provider-data-object) +boolean named `isVerified` and a +[serviceproviderData](serviceproviderdataobject.md#service-provider-data-object) object. ```json @@ -40,3 +41,149 @@ object. If `opts.returnMatchesOnly` is `true`, this function instead returns a list of service providers matched to the provided `uri`. + +## claims.verify(uriArray, [fingerprint], [opts]) + +_(async)_ doip.claims.verify(array, [fingerprint], [opts]) + +Verifies the identity behind the provided **array of uris** using the **fingerprint**. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ------ | --------- | -------------------------------- | +| uriArray | array | true | array of uris | +| fingerprint | string | false | the fingerprint of the claim | +| opts | object | false | options (see below) | + +**Options** + +See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). + +**Returns** + +An array of objects with claim verification results (see +[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)). + +## claims.verify(key, [fingerprint], [opts]) + +_(async)_ doip.claims.verify(key, [fingerprint], [opts]) + +Verifies the identity behind the claims contained within the provided +**key** using the **fingerprint**. This key is outputted by the +[keys.fetch.*()](#keysfetchuriuri) commands. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ------ | --------- | -------------------------------- | +| key | object | true | a public key | +| fingerprint | string | false | the fingerprint of the claim | +| opts | object | false | options (see below) | + +**Options** + +See [claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts). + +**Returns** + +An array of objects with claim verification results (see +[claims.verify(uri, ...)](#claimsverifyuri-fingerprint-opts)). + +## keys.fetch.uri(uri) + +_(async)_ keys.fetch.uri(uri) + +Fetches a key based on the provided `uri`. This simply serves as a shortcut to +other `keys.fetch.*` commands. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ------ | --------- | -------------------------------- | +| uri | string | true | public key identifier | + +Possible formats for `uri`: + +`hkp:FINGERPRINT` ⇒ `keys.fetch.hkp(FINGERPRINT)` +`hkp:FINGERPRINT:KEYSERVER` ⇒ `keys.fetch.hkp(FINGERPRINT, KEYSERVER)` +`hkp:EMAIL` ⇒ `keys.fetch.hkp(EMAIL)` +`hkp:EMAIL:KEYSERVER` ⇒ `keys.fetch.hkp(EMAIL, KEYSERVER)` +`wkd:EMAIL` ⇒ `keys.fetch.wkd(EMAIL)` +`kb:USERNAME:FINGERPRINT` ⇒ `keys.fetch.keybase(USERNAME, FINGERPRINT)` + +**Returns** + +A public key object. + +## keys.fetch.hkp(fingerprint, [keyserverBaseUrl]) + +_(async)_ keys.fetch.hkp(fingerprint, [keyserverBaseUrl]) + +Fetches a key using HKP-compatible key servers. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---------------- | ------ | --------- | -------------------------------- | +| fingerprint | string | true | public key identifier | +| keyserverBaseUrl | string | false | base URL of keyserver | + +`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`. + +**Returns** + +A public key object. + +## keys.fetch.hkp(email, [keyserverBaseUrl]) + +_(async)_ keys.fetch.hkp(email, [keyserverBaseUrl]) + +Fetches a key using HKP-compatible key servers. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---------------- | ------ | --------- | -------------------------------- | +| email | string | true | public key identifier | +| keyserverBaseUrl | string | false | base URL of keyserver | + +`keyserverBaseUrl` defaults to `https://keys.openpgp.org/`. + +**Returns** + +A public key object. + +## keys.fetch.wkd(wkdId) + +_(async)_ keys.fetch.wkd(wkdId) + +Fetches a key using the WKD protocol. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----------- | ------ | --------- | -------------------------------- | +| wkdId | string | true | WKD identifier | + +`wkdId` looks like an email address and is formatted as `username@domain.org`. + +**Returns** + +A public key object. + +## keys.fetch.plaintext(keyPlaintext) + +_(async)_ keys.fetch.plaintext(keyPlaintext) + +Parses the `keyPlaintext`. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------------ | ------ | --------- | -------------------------------- | +| keyPlaintext | string | true | ASCII key content | + +**Returns** + +A public key object. diff --git a/docs/installation.md b/docs/installation.md index b2c9f5e..786c977 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -15,7 +15,7 @@ npm install --save doipjs Install on website by including the following HTML snippet: ```html - + ``` Next step: [quick start (Node.js)](quickstart-nodejs.md) and [quick start (browser)](quickstart-browser.md)