Commit 7dc1803f authored by ale's avatar ale

Add documentation to the libsso C library header

parent 2db100af
......@@ -35,23 +35,104 @@ struct sso_ticket {
typedef struct sso_ticket *sso_ticket_t;
/** Create a new sso_ticket.
*
* Assembles a new sso_ticket struct with the given parameters.
*
* @param user Username.
* @param service SSO service (including mandatory trailing slash).
* @param domain SSO authentication domain.
* @param groups Group membership for this user (NULL-terminated array of
* strings).
* @param validity_seconds Set the expiration time, based on current time.
* @return A pointer to a newly allocated sso_ticket structure, which you must
* then free with sso_ticket_free().
*/
sso_ticket_t sso_ticket_new(const char *user, const char *service,
const char *domain, const char **groups,
int validity_seconds);
/** Free the memory used by a sso_ticket.
*
* @param t Pointer to the sso_ticket to free.
*/
void sso_ticket_free(sso_ticket_t t);
/** Sign a sso_ticket using a secret key.
*
* Signs and encodes a ticket to a serialized ASCII form.
*
* @param[in] t Pointer to the sso_ticket to sign.
* @param[in] secret_key Secret key. This must be a buffer of
* exactly SSO_SECRET_KEY_SIZE bytes.
* @param[out] out Output buffer.
* @param[in] outsz Size of the available output buffer.
* @return An error code in case of failure, SSO_OK otherwise.
*/
int sso_ticket_sign(sso_ticket_t t, const unsigned char *secret_key, char *out,
size_t outsz);
/** Generate a pair of public and private keys.
*
* Note that the resulting buffers will contain binary data, not
* NULL-terminated strings. Key sizes are constant, use the
* SSO_PRIVATE_KEY_SIZE and SSO_SECRET_KEY_SIZE macros.
*
* @param[out] publicp Pointer to a buffer of at least SSO_PRIVATE_KEY_SIZE
* bytes.
* @param[out] secretp Pointer to a buffer of at least SSO_SECRET_KEY_SIZE
* bytes.
* @returns An error code in case of failure, SSO_OK otherwise.
*/
int sso_generate_keys(unsigned char *publicp, unsigned char *secretp);
/** Decode a serialized sso_ticket and validate its signature.
*
* This function decodes a ticket from its serialized ASCII form (as
* generated by sso_ticket_sign), and verifies its cryptographic
* signature against the provided public key.
*
* You must call sso_validate() after this function, to validate
* the sso_ticket contents.
*
* @param[out] t Pointer to a sso_ticket_t that will hold the decoded
* sso_ticket. The resulting pointer should be freed by
* calling sso_ticket_free().
* @param[in] str ASCII-encoded serialized ticket.
* @param[in] public_key Public key. This must be a
* buffer of exactly SSO_PUBLIC_KEY_SIZE bytes.
* @returns An error code in case of failure, SSO_OK otherwise.
*/
int sso_ticket_open(sso_ticket_t *t, const char *str,
const unsigned char *public_key);
/** Validate sso_ticket contents.
*
* Tickets returned by sso_ticket_open() must be validated in the
* application context:
*
* - 'service' and 'domain' must match
* - expiration date should not be past current time
* - if 'groups' is non-NULL, the intersection between 'groups' and
* the groups specified in the ticket must not be empty.
*
* @param t Pointer to the sso_ticket to validate.
* @param service SSO service (including trailing slash).
* @param domain SSO authentication domain.
* @param groups List of groups that the user should be a member of
* (NULL-terminated list of strings). Note that any matching
* group will do.
* @returns An error code in case of failure, SSO_OK otherwise.
*/
int sso_validate(sso_ticket_t t, const char *service, const char *domain,
const char **groups);
/** Return a user-readable string corresponding to a SSO error code.
*
* @param err Error code.
* @returns A pointer to a statically-allocated string. Does not need
* to be freed.
*/
const char *sso_strerror(int err);
/* Base64 encoding utilities. */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment