ethersjs-azure-keyvault-signer
v2.1.0
Published
An Ethers.js compatible signer that connects to Azure Key Vault
Downloads
105
Maintainers
Readme
ethersjs-azure-keyvault-signer
An Ethers.js compatible signer that connects to Azure Key Vault
Installation
Install the azure keyvault signer library using npm
npm install ethersjs-azure-keyvault-signer
Background
- Current web3 signers only support keys managed by the users directly in the form of browser wallets like Metamask, WalletConnect, Hardware wallets or self managed keys.
- Enterprises prefer to maintain the private keys in a secured key store like Azure Key Vault rather than letting their employees handle their private keys.
- Private keys generated and stored in key stores like Azure Key Vault/HSM are never exposed directly to the users. Interaction with such keys is done via SDKs developed by the respective key stores.
- Our library allows enterprise users to interact with dapps without having to deal with browser wallets or the hassle of managing keys
- It enables the user to perform cryptographic operations like signing messages and transactions stored in their enterprises' Azure Key Vault or Managed HSM
Azure Key Vault Credentials Interface
Authentication to Azure Key Vault can be done either using client secret, client certificate or access token(with the Key Vault scope).
interface AzureKeyVaultCredentials {
keyName: string;
vaultName: string;
clientId?: string;
tenantId?: string;
clientSecret?: string;
clientCertificatePath?: string;
accessToken?: AccessToken;
keyVersion?: string
}
Sample AzureKeyVaultCredentials objects
- Client Secret
const keyVaultCredentials : AzureKeyVaultCredentials = { keyName: 'my-key', vaultUrl: 'https://my-vault.vault.azure.net', clientId: 'ACIXXXXXXXXXXXX', clientSecret: 'XXXXXXXXXXXXXXXXX', tenantId: 'ATIXXXXXXXXXXXXXXXX', keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched };
Client Certificate
const keyVaultCredentials : AzureKeyVaultCredentials = { keyName: 'my-key', vaultUrl: 'https://my-vault.vault.azure.net', clientId: 'ACIXXXXXXXXXXXX', clientCertificatePath: './directory/cert.pem', tenantId: 'ATIXXXXXXXXXXXXXXXX', keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched };
Note: The client certificate should be a .pem encoded file with unencrypted private key included.
Access Token
import { AccessToken } from "@azure/core-auth"; const accessTokenObject : AccessToken = { token: '<JWT-Access-Token>', expiresOnTimestamp: '<expiration-time-of-token>', // can be obtained from the accessToken object in the application }; const keyVaultCredentials : AzureKeyVaultCredentials = { keyName: 'my-key', vaultUrl: 'https://my-vault.vault.azure.net', accessToken: accessTokenObject, keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched };
Sample Usage
You need to provide the Azure Key Vault credentials to instantiate an instance of AzureKeyVaultSigner
shown below.
All examples below use client secret based authentication.
import {AzureKeyVaultCredentials, AzureKeyVaultSigner} from 'ethersjs-azure-keyvault-signer';
import {ethers} from 'ethers';
const keyVaultCredentials : AzureKeyVaultCredentials = {
keyName: 'my-key',
vaultUrl: 'https://my-vault.vault.azure.net',
clientId: 'ACIXXXXXXXXXXXX',
clientSecret: 'XXXXXXXXXXXXXXXXX',
tenantId: 'ATIXXXXXXXXXXXXXXXX',
keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched
};
let azureKeyVaultSigner = new AzureKeyVaultSigner(keyVaultCredentials);
const provider = ethers.providers.getDefaultProvider('rinkeby');
azureKeyVaultSigner = azureKeyVaultSigner.connect(provider);
const tx = await azureKeyVaultSigner.sendTransaction({ to: '0x19De7137aEba698D5970d0B2d41eB03e0F97fA56', value: 2 });
console.log(tx);
Examples
The following section provides code snippets that cover functionalities offered by ethersjs-azure-keyvault-signer package.
- Connect to a web3 provider
- Get Ethereum Address
- Sign a message
- Sign a transaction
Connect to a web3 provider
connect function helps the Azure Key Vault signer connect to an ethers provider.
import {AzureKeyVaultCredentials, AzureKeyVaultSigner} from 'ethersjs-azure-keyvault-signer';
import {ethers} from 'ethers';
const keyVaultCredentials : AzureKeyVaultCredentials = {
keyName: 'my-key',
vaultUrl: 'https://my-vault.vault.azure.net',
clientId: 'ACIXXXXXXXXXXXX',
clientSecret: 'XXXXXXXXXXXXXXXXX',
tenantId: 'ATIXXXXXXXXXXXXXXXX',
keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched
};
let azureKeyVaultSigner = new AzureKeyVaultSigner(keyVaultCredentials);
const provider = ethers.providers.getDefaultProvider('rinkeby');
azureKeyVaultSigner = azureKeyVaultSigner.connect(provider);
console.log(azureKeyVaultSigner);
Get Ethereum Address
getAddress returns the Ethereum address for a SECP-256K1 key
import {AzureKeyVaultCredentials, AzureKeyVaultSigner} from 'ethersjs-azure-keyvault-signer';
import {ethers} from 'ethers';
const keyVaultCredentials : AzureKeyVaultCredentials = {
keyName: 'my-key',
vaultUrl: 'https://my-vault.vault.azure.net',
clientId: 'ACIXXXXXXXXXXXX',
clientSecret: 'XXXXXXXXXXXXXXXXX',
tenantId: 'ATIXXXXXXXXXXXXXXXX',
keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched
};
let azureKeyVaultSigner = new AzureKeyVaultSigner(keyVaultCredentials);
const ethereumAddress = await azureKeyVaultSigner.getAddress();
console.log(ethereumAddress);
Sign a message
signMessage signs a digest string with an Azure Key Vault SECP-256K1 private key using ES256K1 signing algorithm.
import {AzureKeyVaultCredentials, AzureKeyVaultSigner} from 'ethersjs-azure-keyvault-signer';
import {ethers} from 'ethers';
const keyVaultCredentials : AzureKeyVaultCredentials = {
keyName: 'my-key',
vaultUrl: 'https://my-vault.vault.azure.net',
clientId: 'ACIXXXXXXXXXXXX',
clientSecret: 'XXXXXXXXXXXXXXXXX',
tenantId: 'ATIXXXXXXXXXXXXXXXX',
keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched
};
let azureKeyVaultSigner = new AzureKeyVaultSigner(keyVaultCredentials);
const message = 'Hello World!';
const signedMessage = await azureKeyVaultSigner.signMessage(message);
console.log(signedMessage);
Sign a transaction
signTransaction will sign a raw Ethereum transaction using an Azure Key Vault SECP-256K1 private key.
import {AzureKeyVaultCredentials, AzureKeyVaultSigner} from 'ethersjs-azure-keyvault-signer';
import {ethers} from 'ethers';
const keyVaultCredentials : AzureKeyVaultCredentials = {
keyName: 'my-key',
vaultUrl: 'https://my-vault.vault.azure.net',
clientId: 'ACIXXXXXXXXXXXX',
clientSecret: 'XXXXXXXXXXXXXXXXX',
tenantId: 'ATIXXXXXXXXXXXXXXXX',
keyVersion: '610f2XXXXXXXXXXX' //optional; if not included, latest version of the key is fetched
};
let azureKeyVaultSigner = new AzureKeyVaultSigner(keyVaultCredentials);
const transaction : ethers.providers.TransactionRequest = {
to: '0x19De7137aEba698D5970d0B2d41eB03e0F97fA56',
value: 2
};
const signedTransaction = await azureKeyVaultSigner.signTransaction(transaction);
console.log(signedTransaction);
LICENSE
MIT © Impactility