mirrors/lnd
1
0
Fork 0
mirror of https://github.com/lightningnetwork/lnd.git synced 2025-02-20 13:34:32 +01:00
Code Issues Projects Releases Wiki Activity

lnrpc+rpcperms: add middleware handler

Browse source 
With this commit we introduce the concept of RPC middleware: A mechanism
similar to the existing channel or HTLC interceptors but this time for
gRPC messages themselves.
An RPC middleware can register itself to the main RPC server to get
notified each time a new gRPC request comes in, a gRPC response is sent
back or a streaming RPC is connected. The middleware can
validate/inspect incoming requests and modify/overwrite outgoing
responses.

Since this also opens the door for malicious software to interfere with
lnd in a negative way, we bind everything to macaroons with custom
caveat conditions: A middleware declares upon registration which custom
caveat name it can handle. Only client requests that send a macaroon
with that custom caveat will then be given to the middleware for
inspection. The only exception is if the middleware instead registers
to use the read-only mode. In that mode it will be able to intercept
all requests/responses, even those not made with a special encumbered
macaroon. But the middleware won't be able to alter responses in the
read-only mode. Therefore requests with the default, unencumbered macaroons
can never be modified by any middleware.
This commit is contained in:
Oliver Gugger 2021-08-12 16:07:23 +02:00
parent 918e021177
commit 75ca574790
No known key found for this signature in database
GPG key ID: 8E4256593F177720
3 changed files with 2013 additions and 587 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1889
lnrpc/lightning.pb.go
View file

File diff suppressed because it is too large Load diff

185
lnrpc/lightning.proto
View file

@ -4051,3 +4051,188 @@ message CheckMacPermRequest {
message CheckMacPermResponse {
bool valid = 1;
}
message RPCMiddlewareRequest {
/*
The unique ID of the intercepted request. Useful for mapping request to
response when implementing full duplex message interception.
*/
uint64 request_id = 1;
/*
The raw bytes of the complete macaroon as sent by the gRPC client in the
original request. This might be empty for a request that doesn't require
macaroons such as the wallet unlocker RPCs.
*/
bytes raw_macaroon = 2;
/*
The parsed condition of the macaroon's custom caveat for convenient access.
This field only contains the value of the custom caveat that the handling
middleware has registered itself for. The condition _must_ be validated for
messages of intercept_type stream_auth and request!
*/
string custom_caveat_condition = 3;
/*
There are three types of messages that will be sent to the middleware for
inspection and approval: Stream authentication, request and response
interception. The first two can only be accepted (=forward to main RPC
server) or denied (=return error to client). Intercepted responses can also
be replaced/overwritten.
*/
oneof intercept_type {
/*
Intercept stream authentication: each new streaming RPC call that is
initiated against lnd and contains the middleware's custom macaroon
caveat can be approved or denied based upon the macaroon in the stream
header. This message will only be sent for streaming RPCs, unary RPCs
must handle the macaroon authentication in the request interception to
avoid an additional message round trip between lnd and the middleware.
*/
StreamAuth stream_auth = 4;
/*
Intercept incoming gRPC client request message: all incoming messages,
both on streaming and unary RPCs, are forwarded to the middleware for
inspection. For unary RPC messages the middleware is also expected to
validate the custom macaroon caveat of the request.
*/
RPCMessage request = 5;
/*
Intercept outgoing gRPC response message: all outgoing messages, both on
streaming and unary RPCs, are forwarded to the middleware for inspection
and amendment. The response in this message is the original response as
it was generated by the main RPC server. It can either be accepted
(=forwarded to the client), replaced/overwritten with a new message of
the same type, or replaced by an error message.
*/
RPCMessage response = 6;
}
}
message StreamAuth {
/*
The full URI (in the format /<rpcpackage>.<ServiceName>/MethodName, for
example /lnrpc.Lightning/GetInfo) of the streaming RPC method that was just
established.
*/
string method_full_uri = 1;
}
message RPCMessage {
/*
The full URI (in the format /<rpcpackage>.<ServiceName>/MethodName, for
example /lnrpc.Lightning/GetInfo) of the RPC method the message was sent
to/from.
*/
string method_full_uri = 1;
/*
Indicates whether the message was sent over a streaming RPC method or not.
*/
bool stream_rpc = 2;
/*
The full canonical gRPC name of the message type (in the format
<rpcpackage>.TypeName, for example lnrpc.GetInfoRequest).
*/
string type_name = 3;
/*
The full content of the gRPC message, serialized in the binary protobuf
format.
*/
bytes serialized = 4;
}
message RPCMiddlewareResponse {
/*
The unique ID of the intercepted request that this response refers to. Must
always be set when giving feedback to an intercept but is ignored for the
initial registration message.
*/
uint64 request_id = 1;
/*
The middleware can only send two types of messages to lnd: The initial
registration message that identifies the middleware and after that only
feedback messages to requests sent to the middleware.
*/
oneof middleware_message {
/*
The registration message identifies the middleware that's being
registered in lnd. The registration message must be sent immediately
after initiating the RegisterRpcMiddleware stream, otherwise lnd will
time out the attempt and terminate the request. NOTE: The middleware
will only receive interception messages for requests that contain a
macaroon with the custom caveat that the middleware declares it is
responsible for handling in the registration message! As a security
measure, _no_ middleware can intercept requests made with _unencumbered_
macaroons!
*/
MiddlewareRegistration register = 2;
/*
The middleware received an interception request and gives feedback to
it. The request_id indicates what message the feedback refers to.
*/
InterceptFeedback feedback = 3;
}
}
message MiddlewareRegistration {
/*
The name of the middleware to register. The name should be as informative
as possible and is logged on registration.
*/
string middleware_name = 1;
/*
The name of the custom macaroon caveat that this middleware is responsible
for. Only requests/responses that contain a macaroon with the registered
custom caveat are forwarded for interception to the middleware. The
exception being the read-only mode: All requests/responses are forwarded to
a middleware that requests read-only access but such a middleware won't be
allowed to _alter_ responses. As a security measure, _no_ middleware can
change responses to requests made with _unencumbered_ macaroons!
NOTE: Cannot be used at the same time as read_only_mode.
*/
string custom_macaroon_caveat_name = 2;
/*
Instead of defining a custom macaroon caveat name a middleware can register
itself for read-only access only. In that mode all requests/responses are
forwarded to the middleware but the middleware isn't allowed to alter any of
the responses.
NOTE: Cannot be used at the same time as custom_macaroon_caveat_name.
*/
bool read_only_mode = 3;
}
message InterceptFeedback {
/*
The error to return to the user. If this is non-empty, the incoming gRPC
stream/request is aborted and the error is returned to the gRPC client. If
this value is empty, it means the middleware accepts the stream/request/
response and the processing of it can continue.
*/
string error = 1;
/*
A boolean indicating that the gRPC response should be replaced/overwritten.
As its name suggests, this can only be used as a feedback to an intercepted
response RPC message and is ignored for feedback on any other message. This
boolean is needed because in protobuf an empty message is serialized as a
0-length or nil byte slice and we wouldn't be able to distinguish between
an empty replacement message and the "don't replace anything" case.
*/
bool replace_response = 2;
/*
If the replace_response field is set to true, this field must contain the
binary serialized gRPC response message in the protobuf format.
*/
bytes replacement_serialized = 3;
}

526
rpcperms/middleware_handler.go Normal file
View file

@ -0,0 +1,526 @@
package rpcperms
import (
"context"
"encoding/hex"
"errors"
"fmt"
"sync"
"sync/atomic"
"time"
"github.com/btcsuite/btcd/chaincfg"
"github.com/lightningnetwork/lnd/lnrpc"
"github.com/lightningnetwork/lnd/macaroons"
"google.golang.org/protobuf/proto"
"google.golang.org/protobuf/reflect/protoreflect"
"google.golang.org/protobuf/reflect/protoregistry"
"gopkg.in/macaroon.v2"
)
var (
// ErrShuttingDown is the error that's returned when the server is
// shutting down and a request cannot be served anymore.
ErrShuttingDown = errors.New("server shutting down")
// ErrTimeoutReached is the error that's returned if any of the
// middleware's tasks is not completed in the given time.
ErrTimeoutReached = errors.New("intercept timeout reached")
// errClientQuit is the error that's returned if the client closes the
// middleware communication stream before a request was fully handled.
errClientQuit = errors.New("interceptor RPC client quit")
)
// MiddlewareHandler is a type that communicates with a middleware over the
// established bi-directional RPC stream. It sends messages to the middleware
// whenever the custom business logic implemented there should give feedback to
// a request or response that's happening on the main gRPC server.
type MiddlewareHandler struct {
// lastRequestID is the ID of the last request that was forwarded to the
// middleware.
//
// NOTE: Must be used atomically!
lastRequestID uint64
middlewareName string
readOnly bool
customCaveatName string
receive func() (*lnrpc.RPCMiddlewareResponse, error)
send func(request *lnrpc.RPCMiddlewareRequest) error
interceptRequests chan *interceptRequest
timeout time.Duration
// params are our current chain params.
params *chaincfg.Params
// done is closed when the rpc client terminates.
done chan struct{}
// quit is closed when lnd is shutting down.
quit chan struct{}
wg sync.WaitGroup
}
// NewMiddlewareHandler creates a new handler for the middleware with the given
// name and custom caveat name.
func NewMiddlewareHandler(name, customCaveatName string, readOnly bool,
receive func() (*lnrpc.RPCMiddlewareResponse, error),
send func(request *lnrpc.RPCMiddlewareRequest) error,
timeout time.Duration, params *chaincfg.Params,
quit chan struct{}) *MiddlewareHandler {
// We explicitly want to log this as a warning since intercepting any
// gRPC messages can also be used for malicious purposes and the user
// should be made aware of the risks.
log.Warnf("A new gRPC middleware with the name '%s' was registered "+
" with custom_macaroon_caveat='%s', read_only=%v. Make sure "+
"you trust the middleware author since that code will be able "+
"to intercept and possibly modify and gRPC messages sent/"+
"received to/from a client that has a macaroon with that "+
"custom caveat.", name, customCaveatName, readOnly)
return &MiddlewareHandler{
middlewareName: name,
customCaveatName: customCaveatName,
readOnly: readOnly,
receive: receive,
send: send,
interceptRequests: make(chan *interceptRequest),
timeout: timeout,
params: params,
done: make(chan struct{}),
quit: quit,
}
}
// intercept handles the full interception lifecycle of a single middleware
// event (stream authentication, request interception or response interception).
// The lifecycle consists of sending a message to the middleware, receiving a
// feedback on it and sending the feedback to the appropriate channel. All steps
// are guarded by the configured timeout to make sure a middleware cannot slow
// down requests too much.
func (h *MiddlewareHandler) intercept(
req *InterceptionRequest) (*interceptResponse, error) {
respChan := make(chan *interceptResponse, 1)
newRequest := &interceptRequest{
request: req,
response: respChan,
}
// timeout is the time after which intercept requests expire.
timeout := time.After(h.timeout)
// Send the request to the interceptRequests channel for the main
// goroutine to be picked up.
select {
case h.interceptRequests <- newRequest:
case <-timeout:
log.Errorf("MiddlewareHandler returned error - reached "+
"timeout of %v for request interception", h.timeout)
return nil, ErrTimeoutReached
case <-h.done:
return nil, errClientQuit
case <-h.quit:
return nil, ErrShuttingDown
}
// Receive the response and return it. If no response has been received
// in AcceptorTimeout, then return false.
select {
case resp := <-respChan:
return resp, nil
case <-timeout:
log.Errorf("MiddlewareHandler returned error - reached "+
"timeout of %v for response interception", h.timeout)
return nil, ErrTimeoutReached
case <-h.done:
return nil, errClientQuit
case <-h.quit:
return nil, ErrShuttingDown
}
}
// Run is the main loop for the middleware handler. This function will block
// until it receives the signal that lnd is shutting down, or the rpc stream is
// cancelled by the client.
func (h *MiddlewareHandler) Run() error {
// Wait for our goroutines to exit before we return.
defer h.wg.Wait()
defer log.Debugf("Exiting middleware run loop for %s", h.middlewareName)
// Create a channel that responses from middlewares are sent into.
responses := make(chan *lnrpc.RPCMiddlewareResponse)
// errChan is used by the receive loop to signal any errors that occur
// during reading from the stream. This is primarily used to shutdown
// the send loop in the case of an RPC client disconnecting.
errChan := make(chan error, 1)
// Start a goroutine to receive responses from the interceptor. We
// expect the receive function to block, so it must be run in a
// goroutine (otherwise we could not send more than one intercept
// request to the client).
h.wg.Add(1)
go func() {
h.receiveResponses(errChan, responses)
h.wg.Done()
}()
return h.sendInterceptRequests(errChan, responses)
}
// receiveResponses receives responses for our intercept requests and dispatches
// them into the responses channel provided, sending any errors that occur into
// the error channel provided.
func (h *MiddlewareHandler) receiveResponses(errChan chan error,
responses chan *lnrpc.RPCMiddlewareResponse) {
for {
resp, err := h.receive()
if err != nil {
errChan <- err
return
}
select {
case responses <- resp:
case <-h.done:
return
case <-h.quit:
return
}
}
}
// sendInterceptRequests handles intercept requests sent to us by our Accept()
// function, dispatching them to our acceptor stream and coordinating return of
// responses to their callers.
func (h *MiddlewareHandler) sendInterceptRequests(errChan chan error,
responses chan *lnrpc.RPCMiddlewareResponse) error {
// Close the done channel to indicate that the interceptor is no longer
// listening and any in-progress requests should be terminated.
defer close(h.done)
interceptRequests := make(map[uint64]*interceptRequest)
for {
select {
// Consume requests passed to us from our Accept() function and
// send them into our stream.
case newRequest := <-h.interceptRequests:
id := atomic.AddUint64(&h.lastRequestID, 1)
req := newRequest.request
interceptRequests[id] = newRequest
interceptReq, err := req.ToRPC(id)
if err != nil {
return err
}
if err := h.send(interceptReq); err != nil {
return err
}
// Process newly received responses from our interceptor,
// looking the original request up in our map of requests and
// dispatching the response.
case resp := <-responses:
requestInfo, ok := interceptRequests[resp.RequestId]
if !ok {
continue
}
response := &interceptResponse{}
switch msg := resp.GetMiddlewareMessage().(type) {
case *lnrpc.RPCMiddlewareResponse_Feedback:
t := msg.Feedback
if t.Error != "" {
response.err = fmt.Errorf("%s", t.Error)
break
}
// For intercepted responses we also allow the
// content itself to be overwritten.
if requestInfo.request.Type == TypeResponse &&
t.ReplaceResponse {
response.replace = true
protoMsg, err := parseProto(
requestInfo.request.ProtoTypeName,
t.ReplacementSerialized,
)
if err != nil {
response.err = err
break
}
response.replacement = protoMsg
}
default:
return fmt.Errorf("unknown middleware "+
"message: %v", msg)
}
select {
case requestInfo.response <- response:
case <-h.quit:
}
delete(interceptRequests, resp.RequestId)
// If we failed to receive from our middleware, we exit.
case err := <-errChan:
log.Errorf("Received an error: %v, shutting down", err)
return err
// Exit if we are shutting down.
case <-h.quit:
return ErrShuttingDown
}
}
}
// InterceptType defines the different types of intercept messages a middleware
// can receive.
type InterceptType uint8
const (
// TypeStreamAuth is the type of intercept message that is sent when a
// client or streaming RPC is initialized. A message with this type will
// be sent out during stream initialization so a middleware can
// accept/deny the whole stream instead of only single messages on the
// stream.
TypeStreamAuth InterceptType = 1
// TypeRequest is the type of intercept message that is sent when an RPC
// request message is sent to lnd. For client-streaming RPCs a new
// message of this type is sent for each individual RPC request sent to
// the stream.
TypeRequest InterceptType = 2
// TypeResponse is the type of intercept message that is sent when an
// RPC response message is sent from lnd to a client. For
// server-streaming RPCs a new message of this type is sent for each
// individual RPC response sent to the stream. Middleware has the option
// to modify a response message before it is sent out to the client.
TypeResponse InterceptType = 3
)
// InterceptionRequest is a struct holding all information that is sent to a
// middleware whenever there is something to intercept (auth, request,
// response).
type InterceptionRequest struct {
// Type is the type of the interception message.
Type InterceptType
// StreamRPC is set to true if the invoked RPC method is client or
// server streaming.
StreamRPC bool
// Macaroon holds the macaroon that the client sent to lnd.
Macaroon *macaroon.Macaroon
// RawMacaroon holds the raw binary serialized macaroon that the client
// sent to lnd.
RawMacaroon []byte
// CustomCaveatName is the name of the custom caveat that the middleware
// was intercepting for.
CustomCaveatName string
// CustomCaveatCondition is the condition of the custom caveat that the
// middleware was intercepting for. This can be empty for custom caveats
// that only have a name (marker caveats).
CustomCaveatCondition string
// FullURI is the full RPC method URI that was invoked.
FullURI string
// ProtoSerialized is the full request or response object in the
// protobuf binary serialization format.
ProtoSerialized []byte
// ProtoTypeName is the fully qualified name of the protobuf type of the
// request or response message that is serialized in the field above.
ProtoTypeName string
}
// NewMessageInterceptionRequest creates a new interception request for either
// a request or response message.
func NewMessageInterceptionRequest(ctx context.Context,
authType InterceptType, isStream bool, fullMethod string,
m interface{}) (*InterceptionRequest, error) {
mac, rawMacaroon, err := macaroonFromContext(ctx)
if err != nil {
return nil, err
}
rpcReq, ok := m.(proto.Message)
if !ok {
return nil, fmt.Errorf("msg is not proto message: %v", m)
}
rawRequest, err := proto.Marshal(rpcReq)
if err != nil {
return nil, fmt.Errorf("cannot marshal proto msg: %v", err)
}
return &InterceptionRequest{
Type: authType,
StreamRPC: isStream,
Macaroon: mac,
RawMacaroon: rawMacaroon,
FullURI: fullMethod,
ProtoSerialized: rawRequest,
ProtoTypeName: string(proto.MessageName(rpcReq)),
}, nil
}
// NewStreamAuthInterceptionRequest creates a new interception request for a
// stream authentication message.
func NewStreamAuthInterceptionRequest(ctx context.Context,
fullMethod string) (*InterceptionRequest, error) {
mac, rawMacaroon, err := macaroonFromContext(ctx)
if err != nil {
return nil, err
}
return &InterceptionRequest{
Type: TypeStreamAuth,
StreamRPC: true,
Macaroon: mac,
RawMacaroon: rawMacaroon,
FullURI: fullMethod,
}, nil
}
// macaroonFromContext tries to extract the macaroon from the incoming context.
// If there is no macaroon, a nil error is returned since some RPCs might not
// require a macaroon. But in case there is something in the macaroon header
// field that cannot be parsed, a non-nil error is returned.
func macaroonFromContext(ctx context.Context) (*macaroon.Macaroon, []byte,
error) {
macHex, err := macaroons.RawMacaroonFromContext(ctx)
if err != nil {
// If there is no macaroon, we continue anyway as it might be an
// RPC that doesn't require a macaroon.
return nil, nil, nil
}
macBytes, err := hex.DecodeString(macHex)
if err != nil {
return nil, nil, err
}
mac := &macaroon.Macaroon{}
if err := mac.UnmarshalBinary(macBytes); err != nil {
return nil, nil, err
}
return mac, macBytes, nil
}
// ToRPC converts the interception request to its RPC counterpart.
func (r *InterceptionRequest) ToRPC(id uint64) (*lnrpc.RPCMiddlewareRequest,
error) {
rpcRequest := &lnrpc.RPCMiddlewareRequest{
RequestId: id,
RawMacaroon: r.RawMacaroon,
CustomCaveatCondition: r.CustomCaveatCondition,
}
switch r.Type {
case TypeStreamAuth:
rpcRequest.InterceptType = &lnrpc.RPCMiddlewareRequest_StreamAuth{
StreamAuth: &lnrpc.StreamAuth{
MethodFullUri: r.FullURI,
},
}
case TypeRequest:
rpcRequest.InterceptType = &lnrpc.RPCMiddlewareRequest_Request{
Request: &lnrpc.RPCMessage{
MethodFullUri: r.FullURI,
StreamRpc: r.StreamRPC,
TypeName: r.ProtoTypeName,
Serialized: r.ProtoSerialized,
},
}
case TypeResponse:
rpcRequest.InterceptType = &lnrpc.RPCMiddlewareRequest_Response{
Response: &lnrpc.RPCMessage{
MethodFullUri: r.FullURI,
StreamRpc: r.StreamRPC,
TypeName: r.ProtoTypeName,
Serialized: r.ProtoSerialized,
},
}
default:
return nil, fmt.Errorf("unknown intercept type %v", r.Type)
}
return rpcRequest, nil
}
// interceptRequest is a struct that keeps track of an interception request sent
// out to a middleware and the response that is eventually sent back by the
// middleware.
type interceptRequest struct {
request *InterceptionRequest
response chan *interceptResponse
}
// interceptResponse is the response a middleware sends back for each
// intercepted message.
type interceptResponse struct {
err error
replace bool
replacement interface{}
}
// parseProto parses a proto serialized message of the given type into its
// native version.
func parseProto(typeName string, serialized []byte) (proto.Message, error) {
messageType, err := protoregistry.GlobalTypes.FindMessageByName(
protoreflect.FullName(typeName),
)
if err != nil {
return nil, err
}
msg := messageType.New()
err = proto.Unmarshal(serialized, msg.Interface())
if err != nil {
return nil, err
}
return msg.Interface(), nil
}