Skip to content

Latest commit

 

History

History
1275 lines (904 loc) · 45.4 KB

api.md

File metadata and controls

1275 lines (904 loc) · 45.4 KB

Classes

Authentication

Class for decrypting and verifying, or signing and encrypting content in an End to End DID Authentication format

Constants

Class containing constants used in Authentication.

AesCryptoSuite

Encrypter plugin for Advanced Encryption Standard symmetric keys

EcPrivateKey ⇐ PrivateKey

Represents an Elliptic Curve private key

EcPublicKey ⇐ PublicKey

Represents an Elliptic Curve public key

Secp256k1CryptoSuite

Encrypter plugin for Elliptic Curve P-256K1

RsaCryptoSuite

Encrypter plugin for RsaSignature2018

RsaPrivateKey ⇐ PrivateKey

Represents an Rsa private key

RsaPublicKey ⇐ PublicKey

Represents an Rsa public key

CryptoFactory

Utility class to handle all CryptoSuite dependency injection

KeyStoreMem

Class defining methods and properties for a light KeyStore

Protect

Class to model protection mechanisms

JoseToken

Base class for containing common operations for JWE and JWS tokens. Not intended for creating instances of this class directly.

JweToken

Class for performing JWE encryption operations. This class hides the JOSE and crypto library dependencies to allow support for additional crypto algorithms.

JwsToken

Class for containing JWS token operations. This class hides the JOSE and crypto library dependencies to allow support for additional crypto algorithms.

PrivateKey

Represents a Private Key in JWK format.

KeyOperation
Base64Url

Class for performing various Base64 URL operations.

Members

ProtectionFormat

Enum to define different protection formats

RecommendedKeyType

JWA recommended KeyTypes to be implemented

RecommendedKeyType

JWK key operations

iss

DID of the issuer of the request. This should match the signature

response_type

MUST be set as 'id_token' in order to match OIDC self-issued protocol

client_id

The redirect url as specified in the OIDC self-issued protocol

scope

MUST be set to 'openid'

state

Opaque value used by issuer for state

nonce

Request Nonce

claims

Claims that are requested

Authentication

Class for decrypting and verifying, or signing and encrypting content in an End to End DID Authentication format

Kind: global class

new Authentication(options)

Authentication constructor

Param Description
options

Arguments to a constructor in a named object

authentication.signAuthenticationRequest(request) ⇒

Signs the AuthenticationRequest with the private key of the Requester and returns the signed JWT.

Kind: instance method of Authentication
Returns:

the signed compact JWT.

Param Description
request

well-formed AuthenticationRequest object

authentication.verifyAuthenticationRequest(request)

Verifies signature on request and returns AuthenticationRequest.

Kind: instance method of Authentication

Param Description
request

Authentiation Request as a buffer or string.

authentication.formAuthenticationResponse(authRequest, responseDid, claims, expiration, keyReference)

Given a challenge, forms a signed response using a given DID that expires at expiration, or a default expiration.

Kind: instance method of Authentication

Param Description
authRequest

Challenge to respond to
responseDid

The DID to respond with
claims

Claims that the requester asked for
expiration

optional expiration datetime of the response
keyReference

pointing to the signing key

authentication.getKeyReference(iss)

Return a reference to the private key that was passed by caller. If the key was passed in by value, it will be stored in the store and a reference is returned

Kind: instance method of Authentication

Param Description
iss

Issuer identifier

authentication.getKey(did) ⇒

Private method that gets the private key of the DID from the key mapping.

Kind: instance method of Authentication
Returns:

private key of the DID.

Param Description
did

the DID whose private key is used to sign JWT.

authentication.verifySignature(jwsToken) ⇒

helper method that verifies the signature on jws and returns the payload if signature is verified.

Kind: instance method of Authentication
Returns:

the payload if jws signature is verified.

Param Description
jwsToken

signed jws token whose signature will be verified.

authentication.verifyAuthenticationResponse(authResponse) ⇒

Verifies the signature on a AuthenticationResponse and returns a AuthenticationResponse object

Kind: instance method of Authentication
Returns:

the authenticationResponse as a AuthenticationResponse Object

Param Description
authResponse

AuthenticationResponse to verify as a string or buffer

authentication.getVerifiedRequest(request, accessTokenCheck) ⇒

Given a JOSE Authenticated Request, will decrypt the request, resolve the requester's did, and validate the signature.

Kind: instance method of Authentication
Returns:

The content of the request as a VerifiedRequest, or a response containing an access token

Param Default Description
request

The JOSE Authenticated Request to decrypt and validate
accessTokenCheck true

Check the validity of the access token

authentication.getAuthenticatedResponse(request, response) ⇒

Given the verified request, uses the same keys and metadata to sign and encrypt the response

Kind: instance method of Authentication
Returns:

An encrypted and signed form of the response

Param Description
request

The original JOSE Verified Request request
response

The plaintext response to be signed and encrypted

authentication.getAuthenticatedRequest(content, privateKey, recipient, accessToken)

Creates an encrypted and authenticated JOSE request

Kind: instance method of Authentication

Param Description
content

the content of the request
privateKey

the private key to sign with
recipient

the DID the request is indended for
accessToken

an access token to be used with the other party

authentication.getPrivateKeyForJwe(jweToken) ⇒

Given a JWE, retrieves the PrivateKey to be used for decryption

Kind: instance method of Authentication
Returns:

The PrivateKey corresponding to the JWE's encryption

Param Description
jweToken

The JWE to inspect

authentication.getPublicKey(request) ⇒

Retrieves the PublicKey used to sign a JWS

Kind: instance method of Authentication
Returns:

The PublicKey the JWS used for signing

Param Description
request

the JWE string

authentication.getRequesterNonce(jwsToken) ⇒

Retrieves the nonce from the JWS

Kind: instance method of Authentication
Returns:

The nonce

Param Description
jwsToken

The JWS containing the nonce

authentication.signThenEncryptInternal(nonce, requesterkey, content) ⇒

Forms a JWS using the local private key and content, then wraps in JWE using the requesterKey and nonce.

Kind: instance method of Authentication
Returns:

An encrypted and signed form of the content

Param Description
nonce

Nonce to be included in the response
requesterkey

PublicKey in which to encrypt the response
content

The content to be signed and encrypted

authentication.issueNewAccessToken(subjectDid, nonce, issuerKeyReference, requesterKey) ⇒

Creates a new access token and wrap it in a JWE/JWS pair.

Kind: instance method of Authentication
Returns:

A new access token

Param Description
subjectDid

the DID this access token is issue to
nonce

the nonce used in the original request
issuerKeyReference

A reference to the key used in the original request
requesterKey

the requesters key to encrypt the response with

authentication.createAccessToken(subjectDid, privateKeyReference, validDurationInMinutes) ⇒

Creates an access token for the subjectDid using the privateKey for the validDurationInMinutes

Kind: instance method of Authentication
Returns:

Signed JWT in compact serialized format.

Param Description
subjectDid

The did this access token is issued to
privateKeyReference

The private key used to generate this access token
validDurationInMinutes

The duration this token is valid for, in minutes

authentication.verifyJwt(publicKey, signedJwtString, expectedRequesterDid) ⇒

Verifies:

  1. JWT signature.
  2. Token's subject matches the given requeter DID.
  3. Token is not expired.

Kind: instance method of Authentication
Returns:

true if token passes all validation, false otherwise.

Param Description
publicKey

Public key used to verify the given JWT in JWK JSON object format.
signedJwtString

The signed-JWT string.
expectedRequesterDid

Expected requester ID in the 'sub' field of the JWT payload.

Constants

Class containing constants used in Authentication.

Kind: global class

AesCryptoSuite

Encrypter plugin for Advanced Encryption Standard symmetric keys

Kind: global class

aesCryptoSuite.getEncrypters()

Encryption algorithms

Kind: instance method of AesCryptoSuite

aesCryptoSuite.getSigners()

Signing algorithms

Kind: instance method of AesCryptoSuite

aesCryptoSuite.encryptAesCbcHmacSha2(keySize, hashSize) ⇒

Given the encryption parameters, returns the AES CBC HMAC SHA2 encryption function

Kind: instance method of AesCryptoSuite
Returns:

a SymmetricEncrypter encrypt function

Param Description
keySize

Size of the keys
hashSize

Size of the SHA2 hash

aesCryptoSuite.decryptAesCbcHmacSha2(keySize, hashSize) ⇒

Given the decryption parameters, returns an AES CBC HMAC SHA2 decryption function

Kind: instance method of AesCryptoSuite
Returns:

a SymmetricEncrypter decrypt function

Param Description
keySize

Size of the keys
hashSize

Size of the SHA2 hash

aesCryptoSuite.encryptAesGcm(keySize) ⇒

Given the encryption parameters, returns the AES GCM encryption function

Kind: instance method of AesCryptoSuite
Returns:

a SymmetricEncrypter encrypt function

Param Description
keySize

Size of the keys

aesCryptoSuite.decryptAesGcm(keySize) ⇒

Given the decryption parameters, returns an AES GCM decryption function

Kind: instance method of AesCryptoSuite
Returns:

a SymmetricEncrypter decrypt function

Param Description
keySize

Size of the keys

aesCryptoSuite.generateHmacTag(hashSize, keySize, mackey, additionalAuthenticatedData, initializationVector, ciphertext) ⇒

Generates the HMAC Tag

Kind: instance method of AesCryptoSuite
Returns:

HMAC Tag

Param Description
hashSize

HMAC hash size
keySize

HMAC tag size
mackey

MAC key
additionalAuthenticatedData

Additional authenticated data
initializationVector

initialization vector
ciphertext

encrypted data

aesCryptoSuite.generateHmac(hashSize, mackey, additionalAuthenticatedData, initializationVector, ciphertext) ⇒

Generates the full HMac

Kind: instance method of AesCryptoSuite
Returns:

HMAC in full

Param Description
hashSize

HMAC hash size
mackey

MAC key
additionalAuthenticatedData

Additional authenticated data
initializationVector

initialization vector
ciphertext

encrypted data

aesCryptoSuite.getAdditionalAuthenticatedDataLength(additionalAuthenticatedData) ⇒

Gets the Additional Authenticated Data length in Big Endian notation

Kind: instance method of AesCryptoSuite
Returns:

Additional Authenticated Data returned as a base64 big endian unsigned integer

Param Description
additionalAuthenticatedData

Additional authenticated data

aesCryptoSuite.generateSymmetricKey(bits)

Generates a symmetric key

Kind: instance method of AesCryptoSuite

Param Description
bits

Size in bits of the key

aesCryptoSuite.generateInitializationVector(bits)

Generates an initialization vector

Kind: instance method of AesCryptoSuite

Param Description
bits

Size in bits of the initialization vector

EcPrivateKey ⇐ PrivateKey

Represents an Elliptic Curve private key

Kind: global class
Extends: PrivateKey

new EcPrivateKey(key)

Constructs a private key given a DID Document public key descriptor containing additional private key information.

TODO: This feels odd, should define a separate type.

Param Description
key

public key object with additional private key information

EcPrivateKey.wrapJwk(kid, jwk)

Wraps a EC private key in jwk format into a Did Document public key object with additonal information

Kind: static method of EcPrivateKey

Param Description
kid

Key ID
jwk

JWK of the private key

EcPrivateKey.generatePrivateKey(kid)

Generates a new private key

Kind: static method of EcPrivateKey

Param Description
kid

Key ID

EcPublicKey ⇐ PublicKey

Represents an Elliptic Curve public key

Kind: global class
Extends: PublicKey

new EcPublicKey(keyData)

An Elliptic Curve JWK

Param Description
keyData

The IDidDocumentPublicKey containing the elliptic curve public key parameters.

Secp256k1CryptoSuite

Encrypter plugin for Elliptic Curve P-256K1

Kind: global class

secp256k1CryptoSuite.getEncrypters()

Encryption with Secp256k1 keys not supported

Kind: instance method of Secp256k1CryptoSuite

secp256k1CryptoSuite.getSigners()

Signing algorithms

Kind: instance method of Secp256k1CryptoSuite

secp256k1CryptoSuite.getKeyConstructors()

Defines constructors for the identifiers proposed in Linked Data Cryptographic Suite Registry https://w3c-ccg.github.io/ld-cryptosuite-registry/#eddsasasignaturesecp256k1 plus the additional ones spotted in the wild.

Kind: instance method of Secp256k1CryptoSuite

Secp256k1CryptoSuite.verify() ⇒

Verifies the given signed content using SHA256 algorithm.

Kind: static method of Secp256k1CryptoSuite
Returns:

true if passed signature verification, false otherwise.


Secp256k1CryptoSuite.sign(jwsHeaderParameters) ⇒

Sign the given content using the given private key in JWK format using algorithm SHA256.

Kind: static method of Secp256k1CryptoSuite
Returns:

Signed payload in compact JWS format.

Param Description
jwsHeaderParameters

Header parameters in addition to 'alg' and 'kid' to be included in the JWS.

RsaCryptoSuite

Encrypter plugin for RsaSignature2018

Kind: global class

rsaCryptoSuite.getEncrypters()

Encryption algorithms

Kind: instance method of RsaCryptoSuite

rsaCryptoSuite.getSigners()

Signing algorithms

Kind: instance method of RsaCryptoSuite

RsaCryptoSuite.verifySignatureRs256() ⇒

Verifies the given signed content using RS256 algorithm.

Kind: static method of RsaCryptoSuite
Returns:

true if passed signature verification, false otherwise.


RsaCryptoSuite.signRs256(jwsHeaderParameters) ⇒

Sign the given content using the given private key in JWK format using algorithm RS256. TODO: rewrite to get rid of node-jose dependency.

Kind: static method of RsaCryptoSuite
Returns:

Signed payload in compact JWS format.

Param Description
jwsHeaderParameters

Header parameters in addition to 'alg' and 'kid' to be included in the JWS.

RsaCryptoSuite.verifySignatureRs512() ⇒

Verifies the given signed content using RS512 algorithm.

Kind: static method of RsaCryptoSuite
Returns:

true if passed signature verification, false otherwise.


RsaCryptoSuite.signRs512(jwsHeaderParameters) ⇒

Sign the given content using the given private key in JWK format using algorithm RS512. TODO: rewrite to get rid of node-jose dependency.

Kind: static method of RsaCryptoSuite
Returns:

Signed payload in compact JWS format.

Param Description
jwsHeaderParameters

Header parameters in addition to 'alg' and 'kid' to be included in the JWS.

RsaCryptoSuite.encryptRsaOaep()

Rsa-OAEP encrypts the given data using the given public key in JWK format.

Kind: static method of RsaCryptoSuite

RsaCryptoSuite.decryptRsaOaep()

Rsa-OAEP decrypts the given data using the given private key in JWK format. TODO: correctly implement this after getting rid of node-jose dependency.

Kind: static method of RsaCryptoSuite

RsaPrivateKey ⇐ PrivateKey

Represents an Rsa private key

Kind: global class
Extends: PrivateKey

new RsaPrivateKey(key)

Constructs a private key given a Did Document public key object containing additional private key information

Param Description
key

public key object with additional private key information

RsaPrivateKey.wrapJwk(kid, jwk)

Wraps a rsa private key in jwk format into a Did Document public key object with additonal information

Kind: static method of RsaPrivateKey

Param Description
kid

Key ID
jwk

JWK of the private key

RsaPrivateKey.generatePrivateKey(kid)

Generates a new private key

Kind: static method of RsaPrivateKey

Param Description
kid

Key ID

RsaPublicKey ⇐ PublicKey

Represents an Rsa public key

Kind: global class
Extends: PublicKey

new RsaPublicKey(n, e)

A Rsa JWK

Param Description
n

The Rsa modulus in Base64urlUInt encoding as specified by RFC7518 6.3.1.1
e

The Rsa public exponent in Base64urlUInt encoding as specified by RFC7518 6.3.1.2

CryptoFactory

Utility class to handle all CryptoSuite dependency injection

Kind: global class

new CryptoFactory(suites)

Constructs a new CryptoRegistry

Param Description
suites

The suites to use for dependency injeciton

cryptoFactory.constructJwe(content)

constructs the jwe to be encrypted or decrypted

Kind: instance method of CryptoFactory

Param Description
content

content for the JWE

cryptoFactory.constructJws(content)

constructs the jws to be signed or verified

Kind: instance method of CryptoFactory

Param Description
content

content for the JWS

cryptoFactory.constructPublicKey(key) ⇒

Given a public key definition from a DID Document, constructs a JWK public key. Throws an error if the key definition cannot be converted.

Kind: instance method of CryptoFactory
Returns:

The same key as a PublicKey

Param Description
key

publicKey object from a DidDocument

cryptoFactory.getEncrypter(name) ⇒

Gets the Encrypter object given the encryption algorithm's name

Kind: instance method of CryptoFactory
Returns:

The corresponding Encrypter, if any

Param Description
name

The name of the algorithm

cryptoFactory.getSigner(name) ⇒

Gets the Signer object given the signing algorithm's name

Kind: instance method of CryptoFactory
Returns:

The corresponding Signer, if any

Param Description
name

The name of the algorithm

cryptoFactory.getSymmetricEncrypter(name) ⇒

Gets the SymmetricEncrypter object given the symmetric encryption algorithm's name

Kind: instance method of CryptoFactory
Returns:

The corresponding SymmetricEncrypter, if any

Param Description
name

The name of the algorithm

cryptoFactory.getDefaultSymmetricEncryptionAlgorithm()

Gets the default symmetric encryption algorithm to use

Kind: instance method of CryptoFactory

KeyStoreMem

Class defining methods and properties for a light KeyStore

Kind: global class

keyStoreMem.get(keyReference, publicKeyOnly)

Returns the key associated with the specified key identifier.

Kind: instance method of KeyStoreMem

Param Description
keyReference

for which to return the key.
publicKeyOnly

True if only the public key is needed.

keyStoreMem.list()

Lists all keys with their corresponding key ids

Kind: instance method of KeyStoreMem

keyStoreMem.save(keyIdentifier, key)

Saves the specified key to the key store using the key identifier.

Kind: instance method of KeyStoreMem

Param Description
keyIdentifier

for the key being saved.
key

being saved to the key store.

keyStoreMem.sign(keyReference, payload, format, cryptoFactory, tokenHeaderParameters) ⇒

Sign the data with the key referenced by keyIdentifier.

Kind: instance method of KeyStoreMem
Returns:

The protected message

Param Description
keyReference

for the key used for signature.
payload

Data to sign
format

used to protect the content
cryptoFactory

used to specify the algorithms to use
tokenHeaderParameters

Header parameters in addition to 'alg' and 'kid' to be included in the header of the token.

keyStoreMem.decrypt(keyReference, cipher, format, cryptoFactory) ⇒

Decrypt the data with the key referenced by keyReference.

Kind: instance method of KeyStoreMem
Returns:

The plain text message

Param Description
keyReference

Reference to the key used for signature.
cipher

Data to decrypt
format

Protection format used to decrypt the data
cryptoFactory

used to specify the algorithms to use

Protect

Class to model protection mechanisms

Kind: global class

Protect.sign(keyStorageReference, payload, format, keyStore, cryptoFactory, tokenHeaderParameters)

Sign the payload

Kind: static method of Protect

Param Description
keyStorageReference

used to reference the signing key
payload

to sign
format

Signature format
keyStore

where to retrieve the signing key
cryptoFactory

used to specify the algorithms to use
tokenHeaderParameters

Header parameters in addition to 'alg' and 'kid' to be included in the header of the token.

Protect.decrypt(keyStorageReference, cipher, format, keyStore, cryptoFactory) ⇒

Decrypt the data with the key referenced by keyReference.

Kind: static method of Protect
Returns:

The plain text message

Param Description
keyStorageReference

Reference to the key used for signature.
cipher

Data to decrypt
format

Protection format used to decrypt the data
keyStore

where to retrieve the signing key
cryptoFactory

used to specify the algorithms to use

JoseToken

Base class for containing common operations for JWE and JWS tokens. Not intended for creating instances of this class directly.

Kind: global class

new JoseToken()

Constructor for JoseToken that takes in a compact-serialized token string.

joseToken.getHeader()

Gets the header as a JS object.

Kind: instance method of JoseToken

joseToken.getProtectedHeader()

Gets the protected headers as a JS object.

Kind: instance method of JoseToken

joseToken.isContentWellFormedToken()

Returns true if and only if the content was parsed as a token

Kind: instance method of JoseToken

JweToken

Class for performing JWE encryption operations. This class hides the JOSE and crypto library dependencies to allow support for additional crypto algorithms.

Kind: global class

jweToken.encrypt() ⇒

Encrypts the original content from construction into a JWE compact serialized format using the given key in JWK JSON object format.Content encryption algorithm is hardcoded to 'A128GCM'.

Kind: instance method of JweToken
Returns:

Buffer of the original content encrypted in JWE compact serialized format.


jweToken.encryptAsFlattenedJson() ⇒

Encrypts the original content from construction into a JWE JSON serialized format using the given key in JWK JSON object format. Content encryption algorithm is hardcoded to 'A128GCM'.

Kind: instance method of JweToken
Returns:

Buffer of the original content encrytped in JWE flattened JSON serialized format.


jweToken.encryptContentEncryptionKey(keyEncryptionAlgorithm, keyBuffer, jwk)

Encrypts the given content encryption key using the specified algorithm and asymmetric public key.

Kind: instance method of JweToken

Param Description
keyEncryptionAlgorithm

Asymmetric encryption algorithm to be used.
keyBuffer

The content encryption key to be encrypted.
jwk

The asymmetric public key used to encrypt the content encryption key.

jweToken.decrypt() ⇒

Decrypts the original JWE using the given key in JWK JSON object format.

Kind: instance method of JweToken
Returns:

Decrypted plaintext of the JWE


jweToken.toCompactJwe()

Converts the JWE from the constructed type into a Compact JWE

Kind: instance method of JweToken

jweToken.toFlattenedJsonJwe(headers)

Converts the JWE from the constructed type into a Flat JSON JWE

Kind: instance method of JweToken

Param Description
headers

unprotected headers to use

JwsToken

Class for containing JWS token operations. This class hides the JOSE and crypto library dependencies to allow support for additional crypto algorithms.

Kind: global class

jwsToken.sign(jwsHeaderParameters) ⇒

Signs contents given at construction using the given private key in JWK format.

Kind: instance method of JwsToken
Returns:

Signed payload in compact JWS format.

Param Description
jwsHeaderParameters

Header parameters in addition to 'alg' and 'kid' to be included in the JWS.

jwsToken.signAsFlattenedJson(jwk, options)

Signs contents given at construction using the given private key in JWK format with additional optional header fields

Kind: instance method of JwsToken

Param Description
jwk

Private key used in the signature
options

Additional protected and header fields to include in the JWS

jwsToken.verifySignature() ⇒

Verifies the JWS using the given key in JWK object format.

Kind: instance method of JwsToken
Returns:

The payload if signature is verified. Throws exception otherwise.


jwsToken.getPayload()

Gets the base64 URL decrypted payload.

Kind: instance method of JwsToken

jwsToken.toCompactJws()

Converts the JWS from the constructed type into a Compact JWS

Kind: instance method of JwsToken

jwsToken.toFlattenedJsonJws(headers)

Converts the JWS from the constructed type into a Flat JSON JWS

Kind: instance method of JwsToken

Param Description
headers

unprotected headers to use

PrivateKey

Represents a Private Key in JWK format.

Kind: global abstract class

KeyOperation

Kind: global abstract class

new exports.KeyOperation()

Represents a Public Key in JWK format.

Base64Url

Class for performing various Base64 URL operations.

Kind: global class

Base64Url.encode()

Encodes the input string or Buffer into a Base64URL string.

Kind: static method of Base64Url

Base64Url.decode()

Decodes a Base64URL string.

Kind: static method of Base64Url

Base64Url.decodeToBuffer()

Decodes a Base64URL string

Kind: static method of Base64Url

Base64Url.toBase64()

Converts a Base64URL string to a Base64 string. TODO: Improve implementation perf.

Kind: static method of Base64Url

Base64Url.fromBase64()

Converts a Base64 string to a Base64URL string. TODO: Improve implementation perf.

Kind: static method of Base64Url

ProtectionFormat

Enum to define different protection formats

Kind: global variable

RecommendedKeyType

JWA recommended KeyTypes to be implemented

Kind: global variable

RecommendedKeyType

JWK key operations

Kind: global variable

iss

DID of the issuer of the request. This should match the signature

Kind: global variable

response_type

MUST be set as 'id_token' in order to match OIDC self-issued protocol

Kind: global variable

client_id

The redirect url as specified in the OIDC self-issued protocol

Kind: global variable

scope

MUST be set to 'openid'

Kind: global variable

state

Opaque value used by issuer for state

Kind: global variable

nonce

Request Nonce

Kind: global variable

claims

Claims that are requested

Kind: global variable