From f6e6c678ad5338264496de43e9e1ab2fe4a28e64 Mon Sep 17 00:00:00 2001 From: Andrew Bartlett Date: Sun, 30 Dec 2001 10:54:58 +0000 Subject: Add a pile of doxygen style comments to various parts of Samba. Many of these probably will never actually be genearted, but I like the style in any case. Also fix a segfault in 'net rpc' when the login failed and a small memory leak on failure in the auth_info.c code. Andrew Bartlett (This used to be commit 2efae7cc522651c22fb120835bc800645559b63e) --- source3/utils/net_rpc.c | 274 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 227 insertions(+), 47 deletions(-) (limited to 'source3/utils/net_rpc.c') diff --git a/source3/utils/net_rpc.c b/source3/utils/net_rpc.c index 97a1a1d342..b98cae37b6 100644 --- a/source3/utils/net_rpc.c +++ b/source3/utils/net_rpc.c @@ -21,9 +21,32 @@ #include "includes.h" #include "../utils/net.h" - +/** + * @file net_rpc.c + * + * @brief RPC based subcommands for the 'net' utility. + * + * This file should contain much of the functionality that used to + * be found in rpcclient, execpt that the commands should change + * less often, and the fucntionality should be sane (the user is not + * expected to know a rid/sid before they conduct an operation etc.) + * + * @todo Perhaps eventually these should be split out into a number + * of files, as this could get quite big. + **/ + + +/* A function of this type is passed to the 'run_rpc_command' wrapper */ typedef NTSTATUS (*rpc_command_fn)(const DOM_SID *, struct cli_state *, TALLOC_CTX *, int, const char **); +/** + * Many of the RPC functions need the domain sid. This function gets + * it at the start of every run + * + * @param cli A cli_state already connected to the remote machine + * + * @return The Domain SID of the remote machine. + */ static DOM_SID *net_get_remote_domain_sid(struct cli_state *cli) { @@ -80,6 +103,17 @@ static DOM_SID *net_get_remote_domain_sid(struct cli_state *cli) exit(1); } +/** + * Run a single RPC command, from start to finish. + * + * @param pipe_name the pipe to connect to (usually a PIPE_ constant) + * @param conn_flag a NET_FLAG_ combination. Passed to + * net_make_ipc_connection. + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * @return A shell status integer (0 for success) + */ static int run_rpc_command(const char *pipe_name, int conn_flags, rpc_command_fn fn, @@ -88,7 +122,14 @@ static int run_rpc_command(const char *pipe_name, int conn_flags, struct cli_state *cli = net_make_ipc_connection(conn_flags); TALLOC_CTX *mem_ctx; NTSTATUS nt_status; - DOM_SID *domain_sid = net_get_remote_domain_sid(cli); + DOM_SID *domain_sid; + + if (!cli) { + return -1; + } + + domain_sid = net_get_remote_domain_sid(cli); + /* Create mem_ctx */ if (!(mem_ctx = talloc_init())) { @@ -113,54 +154,25 @@ static int run_rpc_command(const char *pipe_name, int conn_flags, return (!NT_STATUS_IS_OK(nt_status)); } -static NTSTATUS rpc_user_add_internals(const DOM_SID *domain_sid, struct cli_state *cli, TALLOC_CTX *mem_ctx, - int argc, const char **argv) { - - POLICY_HND connect_pol, domain_pol, user_pol; - NTSTATUS result = NT_STATUS_UNSUCCESSFUL; - const char *acct_name; - uint16 acb_info; - uint32 unknown, user_rid; - - if (argc != 1) { - d_printf("Usage: net rpc user add username\n"); - return NT_STATUS_OK; - } - - acct_name = argv[0]; - - /* Get sam policy handle */ - - result = cli_samr_connect(cli, mem_ctx, MAXIMUM_ALLOWED_ACCESS, - &connect_pol); - if (!NT_STATUS_IS_OK(result)) { - goto done; - } - - /* Get domain policy handle */ - - result = cli_samr_open_domain(cli, mem_ctx, &connect_pol, - MAXIMUM_ALLOWED_ACCESS, - domain_sid, &domain_pol); - if (!NT_STATUS_IS_OK(result)) { - goto done; - } - - /* Create domain user */ - acb_info = ACB_NORMAL; - unknown = 0xe005000b; /* No idea what this is - a permission mask? */ +/****************************************************************************/ - result = cli_samr_create_dom_user(cli, mem_ctx, &domain_pol, - acct_name, acb_info, unknown, - &user_pol, &user_rid); - if (!NT_STATUS_IS_OK(result)) { - goto done; - } - done: - return result; -} +/** + * Force a change of the trust acccount password. + * + * All paramaters are provided by the run_rpc_command funcion, except for + * argc, argv which are passes through. + * + * @param domain_sid The domain sid aquired from the remote server + * @param cli A cli_state connected to the server. + * @param mem_ctx Talloc context, destoyed on compleation of the function. + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * + * @return Normal NTSTATUS return. + **/ static NTSTATUS rpc_changetrustpw_internals(const DOM_SID *domain_sid, struct cli_state *cli, TALLOC_CTX *mem_ctx, int argc, const char **argv) { @@ -168,12 +180,46 @@ static NTSTATUS rpc_changetrustpw_internals(const DOM_SID *domain_sid, struct cl return trust_pw_find_change_and_store_it(cli, mem_ctx, opt_target_workgroup); } +/** + * Force a change of the trust acccount password. + * + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * + * @return A shell status integer (0 for success) + **/ + static int rpc_changetrustpw(int argc, const char **argv) { return run_rpc_command(PIPE_NETLOGON, NET_FLAGS_ANONYMOUS | NET_FLAGS_PDC, rpc_changetrustpw_internals, argc, argv); } + +/****************************************************************************/ + + +/** + * Join a domain, the old way. + * + * This uses 'machinename' as the inital password, and changes it. + * + * The password should be created with 'server manager' or eqiv first. + * + * All paramaters are provided by the run_rpc_command funcion, except for + * argc, argv which are passes through. + * + * @param domain_sid The domain sid aquired from the remote server + * @param cli A cli_state connected to the server. + * @param mem_ctx Talloc context, destoyed on compleation of the function. + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * + * @return Normal NTSTATUS return. + **/ + static NTSTATUS rpc_join_oldstyle_internals(const DOM_SID *domain_sid, struct cli_state *cli, TALLOC_CTX *mem_ctx, int argc, const char **argv) { @@ -188,12 +234,29 @@ static NTSTATUS rpc_join_oldstyle_internals(const DOM_SID *domain_sid, struct cl return trust_pw_change_and_store_it(cli, mem_ctx, orig_trust_passwd_hash); } +/** + * Join a domain, the old way. + * + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * + * @return A shell status integer (0 for success) + **/ + static int rpc_join_oldstyle(int argc, const char **argv) { return run_rpc_command(PIPE_NETLOGON, NET_FLAGS_ANONYMOUS | NET_FLAGS_PDC, rpc_join_oldstyle_internals, argc, argv); } +/** + * Basic usage function for 'net rpc join' + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + **/ + static int rpc_join_usage(int argc, const char **argv) { d_printf(" net rpc join \t to join a domain with admin username & password\n"); @@ -201,6 +264,16 @@ static int rpc_join_usage(int argc, const char **argv) return -1; } +/** + * 'net rpc join' entrypoint. + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * + * Main 'net_rpc_join()' (where the admain username/password is used) is + * in net_rpc_join.c + **/ + static int rpc_join(int argc, const char **argv) { struct functable func[] = { @@ -215,18 +288,111 @@ static int rpc_join(int argc, const char **argv) return net_run_function(argc, argv, func, rpc_join_usage); } + +/****************************************************************************/ + + +/** + * Add a new user to a remote RPC server + * + * All paramaters are provided by the run_rpc_command funcion, except for + * argc, argv which are passes through. + * + * @param domain_sid The domain sid aquired from the remote server + * @param cli A cli_state connected to the server. + * @param mem_ctx Talloc context, destoyed on compleation of the function. + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * + * @return Normal NTSTATUS return. + **/ + +static NTSTATUS rpc_user_add_internals(const DOM_SID *domain_sid, struct cli_state *cli, TALLOC_CTX *mem_ctx, + int argc, const char **argv) { + + POLICY_HND connect_pol, domain_pol, user_pol; + NTSTATUS result = NT_STATUS_UNSUCCESSFUL; + const char *acct_name; + uint16 acb_info; + uint32 unknown, user_rid; + + if (argc != 1) { + d_printf("Usage: net rpc user add username\n"); + return NT_STATUS_OK; + } + + acct_name = argv[0]; + + /* Get sam policy handle */ + + result = cli_samr_connect(cli, mem_ctx, MAXIMUM_ALLOWED_ACCESS, + &connect_pol); + if (!NT_STATUS_IS_OK(result)) { + goto done; + } + + /* Get domain policy handle */ + + result = cli_samr_open_domain(cli, mem_ctx, &connect_pol, + MAXIMUM_ALLOWED_ACCESS, + domain_sid, &domain_pol); + if (!NT_STATUS_IS_OK(result)) { + goto done; + } + + /* Create domain user */ + + acb_info = ACB_NORMAL; + unknown = 0xe005000b; /* No idea what this is - a permission mask? */ + + result = cli_samr_create_dom_user(cli, mem_ctx, &domain_pol, + acct_name, acb_info, unknown, + &user_pol, &user_rid); + if (!NT_STATUS_IS_OK(result)) { + goto done; + } + + done: + return result; +} + +/** + * Add a new user to a remote RPC server + * + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + * + * @return A shell status integer (0 for success) + **/ + static int rpc_user_add(int argc, const char **argv) { return run_rpc_command(PIPE_SAMR, 0, rpc_user_add_internals, argc, argv); } +/** + * Basic usage function for 'net rpc join' + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + **/ + static int rpc_user_usage(int argc, const char **argv) { d_printf(" net rpc user add \t to add a user\n"); return -1; } +/** + * 'net rpc user' entrypoint. + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + **/ + static int rpc_user(int argc, const char **argv) { struct functable func[] = { @@ -241,6 +407,13 @@ static int rpc_user(int argc, const char **argv) return net_run_function(argc, argv, func, rpc_user_usage); } +/** + * Basic usage function for 'net rpc join' + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + **/ + int net_rpc_usage(int argc, const char **argv) { d_printf(" net rpc join \tto join a domain \n"); @@ -249,6 +422,13 @@ int net_rpc_usage(int argc, const char **argv) return -1; } +/** + * 'net rpc user' entrypoint. + * @param argc Standard main() style argc + * @param argc Standard main() style argv. Initial components are already + * stripped + **/ + int net_rpc(int argc, const char **argv) { struct functable func[] = { -- cgit