r6079: Add inline documentation on the credentials context API.

Andrew Bartlett
(This used to be commit 258c04e3678b936bb564ecef10f14128c0a54510)

1 files changed, 118 insertions, 6 deletions

diff --git a/source4/lib/credentials.c b/source4/lib/credentials.c
index 167650f8c2..9c892b0688 100644
--- a/source4/lib/credentials.c
+++ b/source4/lib/credentials.c
@@ -26,7 +26,10 @@
 #include "include/secrets.h"
 #include "lib/ldb/include/ldb.h"
 
-/* Create a new credentials structure, on the specified TALLOC_CTX */
+/**
+ * Create a new credentials structure
+ * @param mem_ctx TALLOC_CTX parent for credentials structure 
+ */
 struct cli_credentials *cli_credentials_init(TALLOC_CTX *mem_ctx) 
 {
 	struct cli_credentials *cred = talloc_zero(mem_ctx, struct cli_credentials);
@@ -37,6 +40,12 @@ struct cli_credentials *cli_credentials_init(TALLOC_CTX *mem_ctx)
 	return cred;
 }
 
+/**
+ * Obtain the username for this credentials context.
+ * @param cred credentials context
+ * @retval The username set on this context.
+ * @note Return value will never be NULL except by programmer error.
+ */
 const char *cli_credentials_get_username(struct cli_credentials *cred)
 {
 	if (cred->machine_account_pending) {
@@ -62,6 +71,11 @@ BOOL cli_credentials_set_username(struct cli_credentials *cred, const char *val,
 	return False;
 }
 
+/**
+ * Obtain the password for this credentials context.
+ * @param cred credentials context
+ * @retval If set, the cleartext password, otherwise NULL
+ */
 const char *cli_credentials_get_password(struct cli_credentials *cred)
 {
 	if (cred->machine_account_pending) {
@@ -87,6 +101,12 @@ BOOL cli_credentials_set_password(struct cli_credentials *cred, const char *val,
 	return False;
 }
 
+/**
+ * Obtain the 'short' or 'NetBIOS' domain for this credentials context.
+ * @param cred credentials context
+ * @retval The domain set on this context. 
+ * @note Return value will never be NULL except by programmer error.
+ */
 const char *cli_credentials_get_domain(struct cli_credentials *cred)
 {
 	if (cred->machine_account_pending) {
@@ -113,6 +133,12 @@ BOOL cli_credentials_set_domain(struct cli_credentials *cred, const char *val, e
 	return False;
 }
 
+/**
+ * Obtain the Kerberos realm for this credentials context.
+ * @param cred credentials context
+ * @retval The realm set on this context. 
+ * @note Return value will never be NULL except by programmer error.
+ */
 const char *cli_credentials_get_realm(struct cli_credentials *cred)
 {	
 	if (cred->machine_account_pending) {
@@ -127,8 +153,15 @@ const char *cli_credentials_get_realm(struct cli_credentials *cred)
 	return cred->realm;
 }
 
+/**
+ * Obtain the user's Kerberos principal for this credentials context.
+ * @param cred credentials context
+ * @param mem_ctx A talloc context to return the prinipal name on.
+ * @retval The user's Kerberos principal
+ * @note Return value may be NULL due to out-of memeory or invalid mem_ctx
+ */
 char *cli_credentials_get_principal(struct cli_credentials *cred,
-					   TALLOC_CTX *mem_ctx)
+				    TALLOC_CTX *mem_ctx)
 {
 	return talloc_asprintf(mem_ctx, "%s@%s", 
 			       cli_credentials_get_username(cred),
@@ -146,6 +179,13 @@ BOOL cli_credentials_set_realm(struct cli_credentials *cred, const char *val, en
 	return False;
 }
 
+/**
+ * Obtain the 'short' or 'NetBIOS' workstation name for this credentials context.
+ *
+ * @param cred credentials context
+ * @retval The workstation name set on this context. 
+ * @note Return value will never be NULL except by programmer error.
+ */
 const char *cli_credentials_get_workstation(struct cli_credentials *cred)
 {
 	if (cred->workstation_obtained == CRED_CALLBACK) {
@@ -167,6 +207,14 @@ BOOL cli_credentials_set_workstation(struct cli_credentials *cred, const char *v
 	return False;
 }
 
+/**
+ * Read a file descriptor, and parse it for a password (eg from a file or stdin)
+ *
+ * @param credentials Credentials structure on which to set the password
+ * @param fd open file descriptor to read the password from 
+ * @param obtained This enum describes how 'specified' this password is
+ */
+
 BOOL cli_credentials_parse_password_fd(struct cli_credentials *credentials, int fd, enum credentials_obtained obtained)
 {
 	char *p;
@@ -201,6 +249,14 @@ BOOL cli_credentials_parse_password_fd(struct cli_credentials *credentials, int
 	return True;
 }
 
+/**
+ * Read a named file, and parse it for a password
+ *
+ * @param credentials Credentials structure on which to set the password
+ * @param file a named file to read the password from 
+ * @param obtained This enum describes how 'specified' this password is
+ */
+
 BOOL cli_credentials_parse_password_file(struct cli_credentials *credentials, const char *file, enum credentials_obtained obtained)
 {
 	int fd = open(file, O_RDONLY, 0);
@@ -219,6 +275,14 @@ BOOL cli_credentials_parse_password_file(struct cli_credentials *credentials, co
 	return ret;
 }
 
+/**
+ * Read a named file, and parse it for username, domain, realm and password
+ *
+ * @param credentials Credentials structure on which to set the password
+ * @param file a named file to read the details from 
+ * @param obtained This enum describes how 'specified' this password is
+ */
+
 BOOL cli_credentials_parse_file(struct cli_credentials *cred, const char *file, enum credentials_obtained obtained) 
 {
 	XFILE *auth;
@@ -278,6 +342,16 @@ BOOL cli_credentials_parse_file(struct cli_credentials *cred, const char *file,
 }
 
 
+/**
+ * Given a string, typically obtained from a -U argument, parse it into domain, username, realm and password fields
+ *
+ * The format accepted is [domain\\]user[%password] or user[@realm][%password]
+ *
+ * @param credentials Credentials structure on which to set the password
+ * @param data the string containing the username, password etc
+ * @param obtained This enum describes how 'specified' this password is
+ */
+
 void cli_credentials_parse_string(struct cli_credentials *credentials, const char *data, enum credentials_obtained obtained)
 {
 	char *uname, *p;
@@ -299,7 +373,12 @@ void cli_credentials_parse_string(struct cli_credentials *credentials, const cha
 	cli_credentials_set_username(credentials, uname, obtained);
 }
 
-/* Initialise defaults from the lp_*() functions */
+/**
+ * Specifies default values for domain, workstation and realm
+ * from the smb.conf configuration file
+ *
+ * @param cred Credentials structure to fill in
+ */
 void cli_credentials_set_conf(struct cli_credentials *cred)
 {
 	cli_credentials_set_domain(cred, lp_workgroup(), CRED_GUESSED);
@@ -307,6 +386,12 @@ void cli_credentials_set_conf(struct cli_credentials *cred)
 	cli_credentials_set_realm(cred, lp_realm(), CRED_GUESSED);
 }
 
+/**
+ * Guess defaults for credentials from environment variables, 
+ * and from the configuration file
+ * 
+ * @param cred Credentials structure to fill in
+ */
 void cli_credentials_guess(struct cli_credentials *cred)
 {
 	char *p;
@@ -342,6 +427,12 @@ void cli_credentials_guess(struct cli_credentials *cred)
 	}
 }
 
+/**
+ * Fill in credentials for the machine trust account, from the secrets database.
+ * 
+ * @param cred Credentials structure to fill in
+ * @retval NTSTATUS error detailing any failure
+ */
 NTSTATUS cli_credentials_set_machine_account(struct cli_credentials *cred)
 {
 	TALLOC_CTX *mem_ctx;
@@ -424,11 +515,23 @@ NTSTATUS cli_credentials_set_machine_account(struct cli_credentials *cred)
 	return NT_STATUS_OK;
 }
 
+/**
+ * Ask that when required, the credentials system will be filled with
+ * machine trust account, from the secrets database.
+ * 
+ * @param cred Credentials structure to fill in
+ * @note This function is used to call the above function after, rather 
+ *       than during, popt processing.
+ *
+ */
 void cli_credentials_set_machine_account_pending(struct cli_credentials *cred)
 {
 	cred->machine_account_pending = True;
 }
-/* Attach NETLOGON credentials for use with SCHANNEL */
+
+/**
+ * Attach NETLOGON credentials for use with SCHANNEL
+ */
 
 void cli_credentials_set_netlogon_creds(struct cli_credentials *cred, 
 					struct creds_CredentialState *netlogon_creds)
@@ -436,14 +539,18 @@ void cli_credentials_set_netlogon_creds(struct cli_credentials *cred,
 	cred->netlogon_creds = talloc_reference(cred, netlogon_creds);
 }
 
-/* Return attached NETLOGON credentials */
+/**
+ * Return attached NETLOGON credentials 
+ */
 
 struct creds_CredentialState *cli_credentials_get_netlogon_creds(struct cli_credentials *cred)
 {
 	return cred->netlogon_creds;
 }
 
-/* Fill in a credentails structure as anonymous */
+/**
+ * Fill in a credentials structure as the anonymous user
+ */
 void cli_credentials_set_anonymous(struct cli_credentials *cred) 
 {
 	cli_credentials_set_username(cred, "", CRED_SPECIFIED);
@@ -451,6 +558,11 @@ void cli_credentials_set_anonymous(struct cli_credentials *cred)
 	cli_credentials_set_password(cred, NULL, CRED_SPECIFIED);
 }
 
+/**
+ * Describe a credentials context as anonymous or authenticated
+ * @retval True if anonymous, False if a username is specified
+ */
+
 BOOL cli_credentials_is_anonymous(struct cli_credentials *cred)
 {
 	const char *username = cli_credentials_get_username(cred);