NewCipherBox

NewCipherBox creates a new cipher box pipe/stream given a valid authentication mechanism. If the authentication mechanism has been revoked, or needs to be changed, then a CipherChallenge message is returned. Otherwise the method will either be accepted or rejected.

Source: auctioneerrpc/hashmail.proto

gRPC

rpc NewCipherBox (CipherBoxAuth) returns (CipherInitResp);

Code Samples

gRPC

Javascript

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

const GRPC_HOST = 'localhost:12010'
const MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
const TLS_PATH = 'POOL_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new poolrpc.HashMail(GRPC_HOST, creds);
let request = {
  desc: <CipherBoxDesc>,
  acct_auth: <PoolAccountAuth>,
  sidecar_auth: <SidecarAuth>,
};
client.newCipherBox(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "success": <CipherSuccess>,
//    "challenge": <CipherChallenge>,
//    "error": <CipherError>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the auctioneerrpc/hashmail.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import hashmail_pb2 as poolrpc, hashmail_pb2_grpc as hashmailstub

GRPC_HOST = 'localhost:12010'
MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
TLS_PATH = 'POOL_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = hashmailstub.HashMailStub(channel)
request = poolrpc.CipherBoxAuth(
  desc=<CipherBoxDesc>,
  acct_auth=<PoolAccountAuth>,
  sidecar_auth=<SidecarAuth>,
)
response = stub.NewCipherBox(request)
print(response)
# {
#    "success": <CipherSuccess>,
#    "challenge": <CipherChallenge>,
#    "error": <CipherError>,
# }

Shell

# There is no CLI command for this RPC

Messages

poolrpc.CipherBoxAuth

Source: auctioneerrpc/hashmail.proto

Field	gRPC Type	REST Type	REST Placement
desc A description of the stream one is attempting to initialize.	CipherBoxDesc	unknown	unknown
acct_auth	PoolAccountAuth	unknown	unknown
sidecar_auth	SidecarAuth	unknown	unknown

poolrpc.CipherInitResp

Source: auctioneerrpc/hashmail.proto

Field	gRPC Type	REST Type
success CipherSuccess is returned if the initialization of the cipher box was successful.	CipherSuccess	unknown
challenge CipherChallenge is returned if the authentication mechanism was revoked or needs to be refreshed.	CipherChallenge	unknown
error CipherError is returned if the authentication mechanism failed to validate.	CipherError	unknown

Nested Messages

poolrpc.CipherBoxDesc

Field	gRPC Type	REST Type
stream_id	bytes	unknown

poolrpc.CipherChallenge

note

This response has no parameters.

poolrpc.CipherError

note

This response has no parameters.

poolrpc.CipherSuccess

Field	gRPC Type	REST Type
desc	CipherBoxDesc	unknown

poolrpc.PoolAccountAuth

Field	gRPC Type	REST Type
acct_key The account key being used to authenticate.	bytes	unknown
stream_sig A valid signature over the stream ID being used.	bytes	unknown

poolrpc.SidecarAuth

Field	gRPC Type	REST Type
ticket A valid sidecar ticket that has been signed (offered) by a Pool account in the active state.	string	unknown