From 91b30e8cd3ea61ed7f8f53646bd5da2e748f5ee7 Mon Sep 17 00:00:00 2001 From: Rafal Szczesniak Date: Fri, 10 Mar 2006 16:36:35 +0000 Subject: r14164: More comments. rafal (This used to be commit 8582d6dfc5c8ad59a2eb64cb81a703c13b7eeed4) --- source4/librpc/rpc/dcerpc_connect.c | 100 ++++++++++++++++++++++++++++++++++-- 1 file changed, 95 insertions(+), 5 deletions(-) (limited to 'source4') diff --git a/source4/librpc/rpc/dcerpc_connect.c b/source4/librpc/rpc/dcerpc_connect.c index d8fedd4301..417f3d3e49 100644 --- a/source4/librpc/rpc/dcerpc_connect.c +++ b/source4/librpc/rpc/dcerpc_connect.c @@ -588,6 +588,9 @@ static void continue_pipe_connect(struct composite_context *c, struct pipe_conne static void continue_pipe_auth(struct composite_context *ctx); +/* + Stage 2 of pipe_connect_b: Receive result of endpoint mapping +*/ static void continue_map_binding(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -608,6 +611,9 @@ static void continue_map_binding(struct composite_context *ctx) } +/* + Stage 2 of pipe_connect_b: Continue connection after endpoint is known +*/ static void continue_connect(struct composite_context *c, struct pipe_connect_state *s) { struct dcerpc_pipe_connect pc; @@ -625,6 +631,7 @@ static void continue_connect(struct composite_context *c, struct pipe_connect_st pc.interface = s->table; pc.creds = s->credentials; + /* connect dcerpc pipe depending on required transport */ switch (s->binding->transport) { case NCACN_NP: if (pc.binding->flags & DCERPC_SMB2) { @@ -667,11 +674,16 @@ static void continue_connect(struct composite_context *c, struct pipe_connect_st return; default: + /* looks like a transport we don't support now */ composite_error(c, NT_STATUS_NOT_SUPPORTED); } } +/* + Stage 3 of pipe_connect_b: Receive result of pipe connect request on + named pipe on smb2 +*/ static void continue_pipe_connect_ncacn_np_smb2(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -686,6 +698,10 @@ static void continue_pipe_connect_ncacn_np_smb2(struct composite_context *ctx) } +/* + Stage 3 of pipe_connect_b: Receive result of pipe connect request on + named pipe on smb +*/ static void continue_pipe_connect_ncacn_np_smb(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -700,6 +716,9 @@ static void continue_pipe_connect_ncacn_np_smb(struct composite_context *ctx) } +/* + Stage 3 of pipe_connect_b: Receive result of pipe connect request on tcp/ip +*/ static void continue_pipe_connect_ncacn_ip_tcp(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -714,6 +733,9 @@ static void continue_pipe_connect_ncacn_ip_tcp(struct composite_context *ctx) } +/* + Stage 3 of pipe_connect_b: Receive result of pipe connect request on unix socket +*/ static void continue_pipe_connect_ncacn_unix(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -728,6 +750,9 @@ static void continue_pipe_connect_ncacn_unix(struct composite_context *ctx) } +/* + Stage 3 of pipe_connect_b: Receive result of pipe connect request on local rpc +*/ static void continue_pipe_connect_ncalrpc(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -742,6 +767,10 @@ static void continue_pipe_connect_ncalrpc(struct composite_context *ctx) } +/* + Stage 4 of pipe_connect_b: Start an authentication on connected dcerpc pipe + depending on credentials and binding flags passed. +*/ static void continue_pipe_connect(struct composite_context *c, struct pipe_connect_state *s) { struct composite_context *auth_bind_req; @@ -760,6 +789,10 @@ static void continue_pipe_connect(struct composite_context *c, struct pipe_conne } +/* + Stage 5 of pipe_connect_b: Receive result of pipe authentication request + and say if all went ok +*/ static void continue_pipe_auth(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -772,6 +805,10 @@ static void continue_pipe_auth(struct composite_context *ctx) } +/* + start a request to open a rpc connection to a rpc pipe, using + specified binding structure to determine the endpoint and options +*/ struct composite_context* dcerpc_pipe_connect_b_send(TALLOC_CTX *parent_ctx, struct dcerpc_pipe **pp, struct dcerpc_binding *binding, @@ -800,9 +837,11 @@ struct composite_context* dcerpc_pipe_connect_b_send(TALLOC_CTX *parent_ctx, s->pipe = dcerpc_pipe_init(c, ev); if (composite_nomem(s->pipe, c)) return c; + /* get event context from initialised dcerpc pipe */ c->event_ctx = s->pipe->conn->event_ctx; (*pp) = s->pipe; + /* store parameters in state structure */ s->binding = binding; s->table = table; s->credentials = credentials; @@ -827,6 +866,9 @@ struct composite_context* dcerpc_pipe_connect_b_send(TALLOC_CTX *parent_ctx, } +/* + receive result of a request to open a rpc connection to a rpc pipe +*/ NTSTATUS dcerpc_pipe_connect_b_recv(struct composite_context *c, TALLOC_CTX *mem_ctx, struct dcerpc_pipe **p) { @@ -872,6 +914,12 @@ struct pipe_conn_state { static void continue_pipe_connect_b(struct composite_context *ctx); + +/* + Initiate rpc connection to a rpc pipe, using the specified string + binding to determine the endpoint and options. + The string is to be parsed to a binding structure first. +*/ struct composite_context* dcerpc_pipe_connect_send(TALLOC_CTX *parent_ctx, struct dcerpc_pipe **pp, const char *binding, @@ -885,6 +933,7 @@ struct composite_context* dcerpc_pipe_connect_send(TALLOC_CTX *parent_ctx, struct dcerpc_binding *b; struct composite_context *pipe_conn_req; + /* composite context allocation and setup */ c = talloc_zero(parent_ctx, struct composite_context); if (c == NULL) return NULL; @@ -894,6 +943,7 @@ struct composite_context* dcerpc_pipe_connect_send(TALLOC_CTX *parent_ctx, c->state = COMPOSITE_STATE_IN_PROGRESS; c->private_data = s; + /* parse binding string to the structure */ status = dcerpc_parse_binding(c, binding, &b); if (!NT_STATUS_IS_OK(status)) { DEBUG(0, ("Failed to parse dcerpc binding '%s'\n", binding)); @@ -902,9 +952,15 @@ struct composite_context* dcerpc_pipe_connect_send(TALLOC_CTX *parent_ctx, } DEBUG(3, ("Using binding %s\n", dcerpc_binding_string(c, b))); - + + /* + start connecting to a rpc pipe after binding structure + is established + */ pipe_conn_req = dcerpc_pipe_connect_b_send(c, &s->pipe, b, table, credentials, ev); + + /* event context for created dcerpc_pipe would be useful... */ c->event_ctx = s->pipe->conn->event_ctx; if (composite_nomem(pipe_conn_req, c)) return c; @@ -914,6 +970,10 @@ struct composite_context* dcerpc_pipe_connect_send(TALLOC_CTX *parent_ctx, } +/* + Stage 2 of pipe_connect: Receive result of actual pipe connect request + and say if we're done ok +*/ static void continue_pipe_connect_b(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -928,6 +988,10 @@ static void continue_pipe_connect_b(struct composite_context *ctx) } +/* + Receive result of pipe connect (using binding string) request + and return connected pipe structure. +*/ NTSTATUS dcerpc_pipe_connect_recv(struct composite_context *c, TALLOC_CTX *mem_ctx, struct dcerpc_pipe **pp) @@ -947,7 +1011,7 @@ NTSTATUS dcerpc_pipe_connect_recv(struct composite_context *c, /* - open a rpc connection to a rpc pipe, using the specified string + Open a rpc connection to a rpc pipe, using the specified string binding to determine the endpoint and options - sync version */ NTSTATUS dcerpc_pipe_connect(TALLOC_CTX *parent_ctx, @@ -978,6 +1042,10 @@ static void continue_open_pipe(struct composite_context *ctx); static void continue_pipe_open(struct composite_context *c); +/* + Send request to create a secondary dcerpc connection from a primary + connection +*/ struct composite_context* dcerpc_secondary_connection_send(struct dcerpc_pipe *p, struct dcerpc_binding *b) { @@ -987,6 +1055,7 @@ struct composite_context* dcerpc_secondary_connection_send(struct dcerpc_pipe *p struct composite_context *pipe_tcp_req; struct composite_context *pipe_ncalrpc_req; + /* composite context allocation and setup */ c = talloc_zero(p, struct composite_context); if (c == NULL) return NULL; @@ -1004,11 +1073,14 @@ struct composite_context* dcerpc_secondary_connection_send(struct dcerpc_pipe *p s->pipe = p; s->binding = b; + /* initialise second dcerpc pipe based on primary pipe's event context */ s->pipe2 = dcerpc_pipe_init(c, s->pipe->conn->event_ctx); if (composite_nomem(s->pipe2, c)) return c; + /* open second dcerpc pipe using the same transport as for primary pipe */ switch (s->pipe->conn->transport.transport) { case NCACN_NP: + /* get smb tree of primary dcerpc pipe opened on smb */ s->tree = dcerpc_smb_tree(s->pipe->conn); if (!s->tree) { composite_error(c, NT_STATUS_INVALID_PARAMETER); @@ -1040,6 +1112,7 @@ struct composite_context* dcerpc_secondary_connection_send(struct dcerpc_pipe *p return c; default: + /* looks like a transport we don't support */ composite_error(c, NT_STATUS_NOT_SUPPORTED); } @@ -1047,6 +1120,9 @@ struct composite_context* dcerpc_secondary_connection_send(struct dcerpc_pipe *p } +/* + Stage 2 of secondary_connection: Receive result of pipe open request on smb +*/ static void continue_open_smb(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -1059,6 +1135,9 @@ static void continue_open_smb(struct composite_context *ctx) } +/* + Stage 2 of secondary_connection: Receive result of pipe open request on tcp/ip +*/ static void continue_open_tcp(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -1071,6 +1150,9 @@ static void continue_open_tcp(struct composite_context *ctx) } +/* + Stage 2 of secondary_connection: Receive result of pipe open request on ncalrpc +*/ static void continue_open_pipe(struct composite_context *ctx) { struct composite_context *c = talloc_get_type(ctx->async.private_data, @@ -1083,6 +1165,10 @@ static void continue_open_pipe(struct composite_context *ctx) } +/* + Stage 3 of secondary_connection: Get binding data and flags from primary pipe + and say if we're done ok. +*/ static void continue_pipe_open(struct composite_context *c) { struct sec_conn_state *s; @@ -1100,6 +1186,10 @@ static void continue_pipe_open(struct composite_context *c) } +/* + Receive result of secondary rpc connection request and return + second dcerpc pipe. +*/ NTSTATUS dcerpc_secondary_connection_recv(struct composite_context *c, struct dcerpc_pipe **p2) { @@ -1117,11 +1207,11 @@ NTSTATUS dcerpc_secondary_connection_recv(struct composite_context *c, } /* - create a secondary dcerpc connection from a primary connection + Create a secondary dcerpc connection from a primary connection - sync version - if the primary is a SMB connection then the secondary connection - will be on the same SMB connection, but use a new fnum + If the primary is a SMB connection then the secondary connection + will be on the same SMB connection, but using a new fnum */ NTSTATUS dcerpc_secondary_connection(struct dcerpc_pipe *p, struct dcerpc_pipe **p2, -- cgit