Numbers Produce Meaning

    ethersjs-azure-keyvault-signer
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • Public • Published

    npm Build and Test Publish

    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

    Install

    npm i ethersjs-azure-keyvault-signer

    DownloadsWeekly Downloads

    12

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    47.2 kB

    Total Files

    16

    Last publish

    Collaborators

    • impactility