ChangePassword

ChangePassword changes the password of the encrypted wallet. This will automatically unlock the wallet database if successful.

Source: walletunlocker.proto

gRPC

rpc ChangePassword (ChangePasswordRequest) returns (ChangePasswordResponse);

REST

HTTP Method	Path
POST	/v1/changepassword

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'walletunlocker.proto'], loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
let client = new lnrpc.WalletUnlocker(GRPC_HOST, sslCreds);
let request = {
  current_password: <bytes>,
  new_password: <bytes>,
  stateless_init: <bool>,
  new_macaroon_root_key: <bool>,
};
client.changePassword(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "admin_macaroon": <bytes>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the walletunlocker.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import walletunlocker_pb2 as lnrpc, walletunlocker_pb2_grpc as walletunlockerstub

GRPC_HOST = 'localhost:10009'
TLS_PATH = 'LND_DIR/tls.cert'

# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# make the request
channel = grpc.secure_channel(GRPC_HOST, ssl_creds)
stub = walletunlockerstub.WalletUnlockerStub(channel)
request = lnrpc.ChangePasswordRequest(
  current_password=<bytes>,
  new_password=<bytes>,
  stateless_init=<bool>,
  new_macaroon_root_key=<bool>,
)
response = stub.ChangePassword(request)
print(response)
# {
#    "admin_macaroon": <bytes>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'

let requestBody = {
  current_password: <string>, // <bytes> (base64 encoded)
  new_password: <string>, // <bytes> (base64 encoded)
  stateless_init: <boolean>, // <bool> 
  new_macaroon_root_key: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/changepassword`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "admin_macaroon": <string>, // <bytes> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/changepassword'
data = {
  'current_password': base64.b64encode(<bytes>),
  'new_password': base64.b64encode(<bytes>),
  'stateless_init': <bool>,
  'new_macaroon_root_key': <bool>,
}
r = requests.post(url, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "admin_macaroon": <bytes>,
# }

Shell

$ lncli changepassword --help

NAME:
   lncli changepassword - Change an encrypted wallet's password at startup.

USAGE:
   lncli changepassword [command options] [arguments...]

CATEGORY:
   Startup

DESCRIPTION:
   
  The changepassword command is used to Change lnd's encrypted wallet's
  password. It will automatically unlock the daemon if the password change
  is successful.

  If one did not specify a password for their wallet (running lnd with
  --noseedbackup), one must restart their daemon without
  --noseedbackup and use this command. The "current password" field
  should be left empty.

  If the daemon was originally initialized stateless, then the
  --stateless_init flag needs to be set for the change password request
  as well! Otherwise the daemon will generate unencrypted macaroon files
  in its file system again and possibly leak sensitive information.
  Changing the password will by default not change the macaroon root key
  (just re-encrypt the macaroon database with the new password). So all
  macaroons will still be valid.
  If one wants to make sure that all previously created macaroons are
  invalidated, a new macaroon root key can be generated by using the
  --new_mac_root_key flag.

  After a successful password change with the --stateless_init flag set,
  the current or new admin macaroon is returned binary serialized in the
  answer. This answer MUST then be stored somewhere, otherwise
  all access to the RPC server will be lost and the wallet must be re-
  created to re-gain access. If the --save_to parameter is set, the
  macaroon is saved to this file, otherwise it is printed to standard out.
  

OPTIONS:
   --stateless_init    do not create any macaroon files in the file system of the daemon
   --save_to value     save returned admin macaroon to this file
   --new_mac_root_key  rotate the macaroon root key resulting in all previously created macaroons to be invalidated
   

Messages

lnrpc.ChangePasswordRequest

Source: walletunlocker.proto

Field	gRPC Type	REST Type	REST Placement
current_password current_password should be the current valid passphrase used to unlock the daemon. When using REST, this field must be encoded as base64.	bytes	string	body
new_password new_password should be the new passphrase that will be needed to unlock the daemon. When using REST, this field must be encoded as base64.	bytes	string	body
stateless_init stateless_init is an optional argument instructing the daemon NOT to create any *.macaroon files in its filesystem. If this parameter is set, then the admin macaroon returned in the response MUST be stored by the caller of the RPC as otherwise all access to the daemon will be lost!	bool	boolean	body
new_macaroon_root_key new_macaroon_root_key is an optional argument instructing the daemon to rotate the macaroon root key when set to true. This will invalidate all previously generated macaroons.	bool	boolean	body

lnrpc.ChangePasswordResponse

Source: walletunlocker.proto

Field	gRPC Type	REST Type
admin_macaroon The binary serialized admin macaroon that can be used to access the daemon after rotating the macaroon root key. If both the stateless_init and new_macaroon_root_key parameter were set to true, this is the ONLY copy of the macaroon that was created from the new root key and MUST be stored safely by the caller. Otherwise a copy of this macaroon is also persisted on disk by the daemon, together with other macaroon files.	bytes	string