mirror of
https://github.com/lightningnetwork/lnd.git
synced 2025-09-13 18:10:25 +02:00
lnrpc+rpcperms: add middleware handler
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
@@ -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;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user