authrite-utils

This package offers essential utility functions used by authrite-js and authrite-express for tasks like mutual authentication. Additionally, it provides a valuable resource for those looking to implement the Authrite specification on a communication channel not yet supported.

API

Table of Contents

• createRequestSignature
  • Parameters
• getCertificatesToInclude
  • Parameters
• getRequestAuthHeaders
  • Parameters
• verifyServerInitialResponse
  • Parameters
• verifyServerResponse
  • Parameters
• getResponseAuthHeaders
  • Parameters
• validateAuthHeaders
  • Parameters
• validateCertificates
  • Parameters
• verifyCertificate
  • Parameters
• verifyCertificateSignature
  • Parameters
• decryptCertificateFields
  • Parameters
• certifierInitialResponse
  • Parameters
• certifierSignCheckArgs
  • Parameters
• certifierCreateSignedCertificate
  • Parameters
• decryptOwnedCertificateField
  • Parameters
• decryptOwnedCertificateFields
  • Parameters
• decryptOwnedCertificates
  • Parameters

createRequestSignature

Creates a valid ECDSA message signature to include in an Authrite request

Parameters

• obj object all params given in an object

  • obj.dataToSign (string | buffer) the data that should be signed with the derived private key
  • obj.requestNonce string random data provided by the client
  • obj.serverInitialNonce string random session data provided by the server
  • obj.clientPrivateKey string? optional private key to use as the signing strategy
  • obj.serverPublicKey string the identity key of the server the request should be sent to

getCertificatesToInclude

Provide a list of certificates with acceptable type and certifier values for the request, based on what the server requested

Parameters

• obj object all params provided in an object

  • obj.signingStrategy string specifies which signing strategy should be used
  • obj.servers object the servers the current Authrite instance is interacting with
  • obj.certificates Array the current available certificates
  • obj.baseUrl

getRequestAuthHeaders

Construct BRC-31 compliant authentication headers to send to the server Note: Currently assumes initial param validation has been done. TODO: Add it here as well Note: Also doesn't currently support the initial request response here. TODO: add it here as well

Parameters

• obj object all params given in an object

  • obj.authriteVersion string the current version of Authrite being used
  • obj.clientPublicKey string of the current client making the request
  • obj.requestNonce string random nonce provided by the client
  • obj.serverInitialNonce string initial session nonce provided by the server
  • obj.requestSignature string message signature provided as a hex string
  • obj.certificatesToInclude Array authrite certificates provided to the server upon request (optional, default '[]')
  • obj.clientInitialNonce

Returns object valid auth headers

verifyServerInitialResponse

Verifies a server's initial response as part of the initial handshake

Parameters

• obj object all params given in an object

  • obj.authriteVersion string the current version of Authrite being used by the server
  • obj.baseUrl string the baseUrl of the server
  • obj.signingStrategy string specifies which signing strategy should be used
  • obj.clientPrivateKey (string | buffer | undefined)? clientPrivateKey to use for key derivation
  • obj.clients object object whose keys are base URLs and whose values are instances of the Client class
  • obj.servers object object whose keys are base URLs and whose values are instances of the Server class
  • obj.serverResponse object contains the server's response including the required authentication data
  • obj.certificates Array the current available certificates

verifyServerResponse

Verifies a server's response after the initial handshake has happened

Parameters

• obj object all params given in an object

  • obj.messageToVerify string the message signed to verify
  • obj.headers object the authentication headers provided by the server
  • obj.baseUrl string the baseUrl of the server
  • obj.signingStrategy string specifies which signing strategy should be used
  • obj.clients object the clients the current Authrite instance is interacting with
  • obj.servers object the servers the current Authrite instance is interacting with
  • obj.clientPrivateKey (string | buffer | undefined)? clientPrivateKey to use for key derivation

getResponseAuthHeaders

Constructs the required server response headers for a given client Supports initial request, and subsequent requests

Parameters

• obj object all params given in an object

  • obj.authrite string the version of authrite being used
  • obj.messageType string type of message to respond to
  • obj.serverPrivateKey string server private key to use to derive the signing private key
  • obj.clientPublicKey string public key of the sender
  • obj.clientNonce string random data provided by the client
  • obj.serverNonce string random data provided by the server
  • obj.messageToSign string expected message to be signed (optional, default 'test')
  • obj.certificates Array provided certificates as requested by the client (optional, default [])
  • obj.requestedCertificates Array a structure indicating which certificates the client should provide

Returns object the required response headers for authentication

validateAuthHeaders

Used to validate client auth headers provided in a request

Parameters

• obj object all params given in an object

  • obj.messageToSign string the message signed when the signature was created
  • obj.authHeaders object provided by the client for authentication
  • obj.serverPrivateKey string server private key to use to derive the signingPublicKey

Returns boolean the validation result

validateCertificates

Validates an array of certificates provided in a request

Parameters

• obj object all params given in an object

  • obj.serverPrivateKey string the server's private key to use in the field decryption process
  • obj.identityKey identityKey of the client initiating the request
  • obj.certificates Array provided to the server by the client

Returns (Array | object) array of the validated certificates, or an Error object to return to the client

verifyCertificate

Verifies a certificate signature, structure, and revocation status

Parameters

• certificate
• chain

verifyCertificateSignature

Verifies that the provided certificate has a valid signature. Also checks the structure of the certificate. Throws errors if the certificate is invalid.

Note: Does not guarantee that additional fields are not provided in this certificate structure!

Parameters

• certificate Object The certificate to verify.

Returns Boolean true if the certificate is valid

decryptCertificateFields

Verifies that the provided certificate has a valid signature

Parameters

• certificate Object The certificate to verify.
• keyring Object The keyring containing the encrypted fieldRevelationKeys.
• verifierPrivateKey string A private key as a base64 string belonging to the certificate verifier. If not provided, the BabbageSDK decrypt function will be used instead.

Returns Object An object containing the decrypted fields.

certifierInitialResponse

Authrite Certifier Helper Function Creates a response object in the standard format for initialRequest.

Parameters

• obj Object All parameters for this function are provided in an object

  • obj.clientNonce string? random data selected by client. Typically 32 bytes in base64 encoding.
  • obj.certifierPrivateKey string? Certifier's private key. 32 random bytes in hex encoding.
  • obj.certificateType string? Certificate type identifier. 32 bytes in base64 encoding.

certifierSignCheckArgs

Authrite Certifier Helper Function Checks the standard inputs to signCertificate for common errors. Returns null on success (no errors). Returns an object like { code: 'ERR_INVALID_REQUEST', description: '...' } on failure.

Parameters

• obj Object All parameters for this function are provided in an object

  • obj.clientNonce string? random data selected by client. Typically 32 bytes in base64 encoding.
  • obj.certifierPrivateKey string? Certifier's private key. 32 random bytes in hex encoding.
  • obj.certificateType string? Certificate type identifier. 32 bytes in base64 encoding.
  • obj.messageType string? Must be the string 'certificateSigningRequest'.
  • obj.type string? The requested certificate type. Must equal certificateType.
  • obj.serverSerialNonce string? The serialNonce value returned by prior initialRequest.
  • obj.serverValidationNonce string? The validationNonce value returned by prior initialRequest.
  • obj.serialNumber string? The serialNumber value returned by prior initialRequest.
  • obj.validationKey string? The validationKey value returned by prior initialRequest.

certifierCreateSignedCertificate

Authrite Certifier Helper Function Checks the standard inputs to signCertificate for common errors. Returns null on success (no errors). Returns an object like { code: 'ERR_INVALID_REQUEST', description: '...' } on failure.

Parameters

• obj Object All parameters for this function are provided in an object

  • obj.validationKey string? The validationKey value returned by prior initialRequest.
  • obj.certifierPrivateKey string? Certifier's private key. 32 random bytes in hex encoding.
  • obj.certificateType string? Certificate type identifier. 32 bytes in base64 encoding.
  • obj.serialNumber string? The serialNumber value returned by prior initialRequest.
  • obj.clientNonce string? random data selected by client. Typically 32 bytes in base64 encoding.
  • obj.messageType string? Must be the string 'certificateSigningRequest'.
  • obj.type string? The requested certificate type. Must equal certificateType.
  • obj.serverSerialNonce string? The serialNonce value returned by prior initialRequest.
  • obj.serverValidationNonce string? The validationNonce value returned by prior initialRequest.
  • obj.subject
  • obj.fields
  • obj.revocationOutpoint

decryptOwnedCertificateField

Decrypts a single certificate field for client-only use.

Parameters

• obj Object All parameters are provided in an object

  • obj.certificate Object The certificate with a field to decrypt
  • obj.fieldName String The name of the field to decrypt
  • obj.callerAgreesToKeepDataClientSide Boolean Whether the caller of this function agrees to keep the data client-side (optional, default false)

Returns Promise<String> The decrypted field value for client-side-only use

decryptOwnedCertificateFields

Decrypts all fields in a certificate for client-only use.

Parameters

• certificate Object The certificate containing fields to decrypt
• callerAgreesToKeepDataClientSide Boolean Whether the caller of this function agrees to keep the data client-side (optional, default false)

Returns Promise<Object> Decrypted fields object for client-side-only use

decryptOwnedCertificates

Searches for user certificates, returning decrypted certificate fields for client-side-only use

Parameters

• $0 Object

  • $0.certifiers
  • $0.types
  • $0.callerAgreesToKeepDataClientSide (optional, default false)

Returns Promise<Array<Object>> The set of decrypted certificates for client-only use

License

The license for the code in this repository is the Open BSV License.