From 761bdb952000e333751164487d0a73fcd7293bfc Mon Sep 17 00:00:00 2001 From: Alexander Kanavin Date: Mon, 2 Sep 2013 21:17:19 +0300 Subject: [PATCH] docs: update documentation of SignonSecurityContext --- libgsignon-glib/signon-security-context.c | 46 +++++++++++++++++------ libgsignon-glib/signon-security-context.h | 2 +- 2 files changed, 36 insertions(+), 12 deletions(-) diff --git a/libgsignon-glib/signon-security-context.c b/libgsignon-glib/signon-security-context.c index 2999cb9..da2304d 100644 --- a/libgsignon-glib/signon-security-context.c +++ b/libgsignon-glib/signon-security-context.c @@ -25,10 +25,34 @@ /** * SECTION:signon-security-context * @title: SignonSecurityContext - * @short_description: Representation of a security context. + * @short_description: representation of a security context. * * The #SignonSecurityContext represents a security context within - * system and also within application. + * system and also within application. Security contexts are used: + * + * - within identities to specify the owner of the identity, and + * users of the identity (items on the access control list). See #SignonIdentity. + * - by gSSO daemon to identify the application accessing the gSSO service and + * to determine if the application is an identity's owner, or is on the identity's access + * control list, and make access control decisions accordingly. + * + * #SignonSecurityContext contains two strings: a system context and an + * application context. + * + * System context can be a binary path, SMACK-label, or MSSF token. Specific + * interpretation of the system context value is performed by a gSSO extension module. + * The default gSSO extension expects binary paths. + * + * Application context identifies a script or a webpage within an application, + * and it's used for providing access control to runtime environments (when making an access + * control decision requires not only a binary identifier, but also information + * about what the binary is doing). + * + * System context + * and application context can contain a wildcard match "*" which disables the ACL + * check when a default gSSO extension is used. Check the documentation for a + * platform specific extension to determine if "*" has any effect with that + * custom extension. */ #include "signon-security-context.h" @@ -50,7 +74,7 @@ _security_context_free (gpointer ptr) * * Allocates a new security context item. * - * Returns: (transfer full) allocated #SignonSecurityContext. + * Returns: (transfer full): allocated #SignonSecurityContext. */ SignonSecurityContext * signon_security_context_new () @@ -71,7 +95,7 @@ signon_security_context_new () * * Allocates and initializes a new security context item. * - * Returns: (transfer full) allocated #SignonSecurityContext. + * Returns: (transfer full): allocated #SignonSecurityContext. */ SignonSecurityContext * signon_security_context_new_from_values (const gchar *system_context, @@ -97,7 +121,7 @@ signon_security_context_new_from_values (const gchar *system_context, * * Copy a security context item. * - * Returns: (transfer full) a copy of the #SignonSecurityContext item. + * Returns: (transfer full): a copy of the #SignonSecurityContext item. */ SignonSecurityContext * signon_security_context_copy (const SignonSecurityContext *src_ctx) @@ -150,7 +174,7 @@ signon_security_context_set_system_context (SignonSecurityContext *ctx, * Get the system context part (such as SMACK label or MSSF token) of the * #SignonSecurityContext. * - * Returns: (transfer none) system context. + * Returns: (transfer none): system context. */ const gchar * signon_security_context_get_system_context (const SignonSecurityContext *ctx) @@ -185,7 +209,7 @@ signon_security_context_set_application_context (SignonSecurityContext *ctx, * Get the application context part (such as script name or a web page) of * the #SignonSecurityContext. * - * Returns: (transfer none) application context. + * Returns: (transfer none): application context. */ const gchar * signon_security_context_get_application_context ( @@ -202,7 +226,7 @@ signon_security_context_get_application_context ( * * Build a GVariant of type "(ss)" from a #SignonSecurityContext item. * - * Returns: (transfer full) GVariant construct of a #SignonSecurityContext. + * Returns: (transfer full): GVariant construct of a #SignonSecurityContext. */ GVariant * signon_security_context_build_variant (const SignonSecurityContext *ctx) @@ -224,7 +248,7 @@ signon_security_context_build_variant (const SignonSecurityContext *ctx) * * Builds a #SignonSecurityContext item from a GVariant of type "(ss)". * - * Returns: (transfer full) #SignonSecurityContext item. + * Returns: (transfer full): #SignonSecurityContext item. */ SignonSecurityContext * signon_security_context_deconstruct_variant (GVariant *variant) @@ -249,7 +273,7 @@ signon_security_context_deconstruct_variant (GVariant *variant) * Builds a GVariant of type "a(ss)" from a GList of #SignonSecurityContext * items. * - * Returns: (transfer full) GVariant construct of a #SignonSecurityContextList. + * Returns: (transfer full): GVariant construct of a #SignonSecurityContextList. */ GVariant * signon_security_context_list_build_variant ( @@ -326,7 +350,7 @@ signon_security_context_list_copy (const SignonSecurityContextList *src_list) /** * signon_security_context_list_free: - * @seclist: (transfer full) #SignonSecurityContextList item. + * @seclist: (transfer full): #SignonSecurityContextList item. * * Frees all items and the GList of #SignonSecurityContext. */ diff --git a/libgsignon-glib/signon-security-context.h b/libgsignon-glib/signon-security-context.h index 450dc48..6ba7082 100644 --- a/libgsignon-glib/signon-security-context.h +++ b/libgsignon-glib/signon-security-context.h @@ -38,7 +38,7 @@ typedef struct _SignonSecurityContext SignonSecurityContext; * binary path. * @app_ctx: application context, such as a script or a web page. * - * Security context descriptor. Practically a string tuple. + * Security context descriptor used for access control checks. */ struct _SignonSecurityContext { -- 2.34.1