From c25b0eddc6d1945deeb60dc3cfd5332be2aefcd8 Mon Sep 17 00:00:00 2001 From: Douglas Thain Date: Mon, 18 Nov 2024 16:56:42 -0500 Subject: [PATCH] Add API docs for chirp_reli functions which were marked FIXME. --- chirp/src/chirp_reli.h | 64 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 4 deletions(-) diff --git a/chirp/src/chirp_reli.h b/chirp/src/chirp_reli.h index 87d61c0362..82c0e8b83a 100644 --- a/chirp/src/chirp_reli.h +++ b/chirp/src/chirp_reli.h @@ -337,14 +337,70 @@ Note that this function has no timeoutbecause it operates solely on memory struc void chirp_reli_closedir(struct chirp_dir *dir); -/* FIXME document */ +/** Create a new blank access control ticket. +@param host The name and port of the Chirp server to access. +@param name An empty array that will be filled with a unique ticket filename. +@param bits The cryptographic length of the ticket, in bits. (typically 1024) +@param stoptime The absolute time at which to abort. +@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno. +*/ + INT64_T chirp_reli_ticket_create(const char *host, char name[CHIRP_PATH_MAX], unsigned bits, time_t stoptime); + +/** Register an access control ticket with a file serer. +@param host The name and port of the Chirp server to access. +@param name The name of an existing ticket. +@param subject The subject to be granted access with this ticket, which should be "self" for normal users. +@param duration The lifetime of this ticket, in seconds. +@param stoptime The absolute time at which to abort. +@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno. +*/ + INT64_T chirp_reli_ticket_register(const char *host, const char *name, const char *subject, time_t duration, time_t stoptime); -INT64_T chirp_reli_ticket_delete(const char *host, const char *name, time_t stoptime); -INT64_T chirp_reli_ticket_list(const char *host, const char *subject, char ***list, time_t stoptime); -INT64_T chirp_reli_ticket_get(const char *host, const char *name, char **subject, char **ticket, time_t * duration, char ***rights, time_t stoptime); + +/** Modify an access control ticket to grant futher access. +@param host The name and port of the Chirp server to access. +@param name The name of an existing ticket. +@param path The filesystem path that will be added to the ticket. +@param aclmask The access rights that will be added to the ticket, any of "rwldax". +@param stoptime The absolute time at which to abort. +@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno. +*/ + INT64_T chirp_reli_ticket_modify(const char *host, const char *name, const char *path, const char *aclmask, time_t stoptime); +/** Get the details of a registered ticket. +@param host The name and port of the Chirp server to access. +@param name The name of an existing ticket. +@param subject A pointer to a string that will be allocated with the name of the ticket owner. +@param ticket A pointer to a string that will be allocated with the name of the ticket. (XXX) +@param duration A pointer to an integer that will be filled with the duration of the ticket. +@param rights A pointer to a list of strings that will be filled with ticket rights. +@param stoptime The absolute time at which to abort. +@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno. +*/ + +INT64_T chirp_reli_ticket_get(const char *host, const char *name, char **subject, char **ticket, time_t * duration, char ***rights, time_t stoptime); + +/** List registered tikets on a server. +@param host The name and port of the Chirp server to access. +@param subject The user whose tickets to list, typically "self" for a normal user. +@param list A pointer to an (unallocated) list of strings which will be filled in with registered tickets. +@param stoptime The absolute time at which to abort. +@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno. +*/ + +INT64_T chirp_reli_ticket_list(const char *host, const char *subject, char ***list, time_t stoptime); + +/** Delete an access control ticket. +@param host The name and port of the Chirp server to access. +@param name The name of an existing ticket file on the local filesystem. +@param stoptime The absolute time at which to abort. +@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno. +*/ + +INT64_T chirp_reli_ticket_delete(const char *host, const char *name, time_t stoptime); + /** Get an access control list. @param host The name and port of the Chirp server to access. @param path The pathname of the directory to access.