From 9d5d5c638e5a54c0ea5e72ef7513e4f14c6796cc Mon Sep 17 00:00:00 2001 From: Imran Zaman Date: Thu, 7 Nov 2013 16:52:38 +0200 Subject: [PATCH] initial docs skeleton --- Makefile.am | 11 +++- autogen.sh | 41 ++++++++++-- configure.ac | 4 +- docs/Makefile.am | 111 +++++++++++++++++++++++++++++++ docs/building.xml | 178 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/examples.xml | 162 +++++++++++++++++++++++++++++++++++++++++++++ docs/gumd-docs.sgml | 75 +++++++++++++++++++++ docs/introduction.xml | 93 ++++++++++++++++++++++++++ docs/version.xml.in | 1 + 9 files changed, 667 insertions(+), 9 deletions(-) create mode 100644 docs/Makefile.am create mode 100644 docs/building.xml create mode 100644 docs/examples.xml create mode 100644 docs/gumd-docs.sgml create mode 100644 docs/introduction.xml create mode 100644 docs/version.xml.in diff --git a/Makefile.am b/Makefile.am index b997984..9619c6a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,12 +1,17 @@ ACLOCAL_AMFLAGS = -I m4 -# --enable-distcheck is here to make it possible to use -# also --enable-dbus-type=session here +# configure flags used in by distcheck AM_DISTCHECK_CONFIGURE_FLAGS = \ --enable-distcheck \ + --enable-dbus-type=p2p\ --enable-tests -SUBDIRS = src test examples +if ENABLE_GTK_DOC +AM_DISTCHECK_CONFIGURE_FLAGS += \ + --enable-gtk-doc +endif + +SUBDIRS = src test examples docs EXTRA_DIST = dists tools diff --git a/autogen.sh b/autogen.sh index 7609c1f..0520504 100755 --- a/autogen.sh +++ b/autogen.sh @@ -1,13 +1,44 @@ #!/bin/sh -e +# This file is part of gum +# +# Copyright (C) 2013 Intel Corporation. +# +# Contact: Imran Zaman +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA +# 02110-1301 USA + + srcdir=`dirname $0` test -z "$srcdir" && srcdir=. +if which gtkdocize >/dev/null 2>/dev/null; then + gtkdocize --docdir docs/ +else + rm -f docs/gtk-doc.make + echo 'EXTRA_DIST =' > docs/gtk-doc.make +fi + aclocal #-I m4 -autoheader -libtoolize --copy --force -autoconf +autoheader +libtoolize --copy --force +autoconf automake --add-missing --copy -autoreconf --install --force -. $srcdir/configure "$@" + +autoreconf --force --install --symlink + +./configure "$@" diff --git a/configure.ac b/configure.ac index c82839b..535589e 100644 --- a/configure.ac +++ b/configure.ac @@ -132,7 +132,7 @@ fi AM_CONDITIONAL(HAVE_DEBUG, [test x$enable_debug = xyes]) # Gtk-doc -GTK_DOC_CHECK +GTK_DOC_CHECK([1.18],[--flavour no-tmpl]) # Checks for typedefs, structures, and compiler characteristics. GUM_CFLAGS='$(GLIB_CFLAGS) -D_POSIX_C_SOURCE=\"200809L\" -D_GNU_SOURCE -D_REENTRANT -D_THREAD_SAFE' @@ -182,6 +182,8 @@ src/daemon/dbus/gumd-dbus.conf src/lib/Makefile src/lib/libgum.pc src/lib/libgum-uninstalled.pc +docs/Makefile +docs/version.xml test/Makefile test/common/Makefile test/daemon/Makefile diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..c01a985 --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,111 @@ +## Process this file with automake to produce Makefile.in + +# We require automake 1.6 at least. +AUTOMAKE_OPTIONS = 1.6 + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=gumd + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 + + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml + +# Directories containing the source code. +# gtk-doc will search all .c and .h files beneath these paths +# for inline comments documenting functions and macros. +# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk +#DOC_SOURCE_DIR=$(top_srcdir)/include\ +#$(top_srcdir)/src/common\ +#$(top_srcdir)/src/lib + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml +MKDB_OPTIONS=--xml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB= +CFILE_GLOB= + +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +EXTRA_HFILES= + +# Header files or dirs to ignore when scanning. Use base file/dir names +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code +IGNORE_HFILES=\ +gum-internals.h\ +gum-user-service.h\ +gum-group-service.h + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files=building.xml + +# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded +# These files must be listed here *and* in content_files +# e.g. expand_content_files=running.sgml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS= + +GTKDOC_LIBS=\ + $(top_builddir)/src/common/libgum-common.la\ + $(top_builddir)/src/lib/libgum.la + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/docs/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +EXTRA_DIST += + +# Files not to distribute +# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types +# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt +#DISTCLEANFILES += + +# Comment this out if you want 'make check' to test you doc status +# and run some sanity checks +if ENABLE_GTK_DOC +include $(top_srcdir)/test/test_common.mk +TESTS = $(GTKDOC_CHECK) +endif + +CLEANFILES += $(DOC_MODULE)-*.txt $(DOC_MODULE).types diff --git a/docs/building.xml b/docs/building.xml new file mode 100644 index 0000000..0569f22 --- /dev/null +++ b/docs/building.xml @@ -0,0 +1,178 @@ + + + + + Building and installing the user management daemon (gumd) + and client library (libgum). + + 3 + Gumd + + + + Building gumd and libgum + + gumd and libgum uses the standard GNU build system, + using autoconf for package + configuration and resolving portability issues, + automake for building makefiles + that comply with the GNU Coding Standards, and + libtool for building shared + libraries on multiple platforms. The normal sequence for + compiling and installing gumd and libgum from distribution tarballs is + thus: + + + ./configure + make + make install + + + If you have obtained the source code directly from git repository, + execute the ./autogen.sh script + before the steps above. + + + + The standard options provided by GNU + autoconf may be passed to the + configure script. Please see the + autoconf documentation or run + ./configure --help for information about + the standard options. + + + + + Dependencies + + Before you can compile gumd and libgum, you need to have + various other tools and libraries installed on your + system. The two tools needed during the build process + are pkg-config and + GNU make. + + + + + + pkg-config + + is a tool for tracking the compilation flags needed for + libraries that are used by the gumd and libgum. (For each + library, a small .pc text file is + installed in a standard location that contains the compilation + flags needed for that library along with version number + information.) + + + + + gumd depends on a number of other libraries. + + + + + The GLib + library is the development framework that gumd and libgum + is built on. + + + + + The check library + provides a unit testing framework. It is needed only if you would + like to run unit tests with make check. + + + + + The + + Systemd + + provides dbus login apis that gumd is using for + querying/terminating users sessions e.g. when a user is deleted. + + + + + + + Extra Configuration Options + + + In addition to the normal options, the + configure script supports these additional arguments: + + + + <systemitem>--enable-debug</systemitem> + + + Turns on debugging support. This allows setting environment + variables to influence the runtime behaviour of gumd and libgum + (see GumConfig). + + + + + <systemitem>--enable-tests</systemitem> + + + This enables unit tests and implicitly enables debugging support as + well. + + + + + <systemitem>--enable-dbus-type=dbus-type</systemitem> + + + Sets the way in which libgum is using DBus to communicate with + gumd. dbus-type can be one of + + + + 'p2p' which is the default value. + Gumd will use direct connection over a UNIX domain socket + with the client library without involving the DBus daemon. + + + + + 'session' which will use the session bus. + This is not recommended to use because session bus isn't secure + against eavesdropping, but it can be used for debugging purposes, + as it allows the use of standard tools such as + dbus-monitor, d-feet and + so on. + + + + + 'system' which will use the system bus. + + + + + + + + + Building distribution packages + + + Instead of running make install to install gumd and + libgum into a system location it is possible to build + distribution-specific packages. dists/ directory + in the source tree contains a number of package confuguration files, + and to use them also a distribution tarball is needed. If you are + building from a git tree, use make dist to create + such a tarball. + + + + diff --git a/docs/examples.xml b/docs/examples.xml new file mode 100644 index 0000000..8ff15e2 --- /dev/null +++ b/docs/examples.xml @@ -0,0 +1,162 @@ + + + + + gumd usage examples + + + + Introduction + + libgsignond-glib comes with an example application gsso-example + that demonstrates the most common use cases: listing available authentication methods and + their mechanisms, creating and removing identities and performing authentication + sessions. + + + Before running the example application, make sure that gSSO daemon and + gSSO UI (that is appropriate for your system) are installed and configured + correctly. + + + The source code for the example application is available at + + http://code.google.com/p/accounts-sso/source/browse/examples/gsso-example.c?repo=libgsignon-glib&name=master + + + The full list of available gsso-example options can be + obtained with gsso-example --help-all + + + + + Authentication methods and mechanisms + + The list of available authentication methods can be obtained with + --query-methods: + +> gsso-example --query-methods: +Available authentication methods: + password + oauth + digest + + + + For each of the available authentication methods it's possible to query + available authentication mechanisms with + gsso-example --query-mechanisms=method: + +> gsso-example --query-mechanisms=oauth +Available authentication mechanisms for method oauth: + oauth1 + oauth2 + + + + + + Identity management + + The list of stored identities that the gsso-example application is allowed + to use can be obtained with gsso-example --query-identities: + +> gsso-example --query-identities +Available identities: + id=27 caption='My test identity' + id=28 caption='Another test identity' + + + + To create an identity, use --create-identity option + with identity caption (user-readable name) and --identity-method + with the authentication method that the identity will be using. + +> gsso-example --create-identity="My test identity" --identity-method=password +Identity stored with id 28 + + + + To remove an identity, use --remove-identity option + with identity id: + +> gsso-example --remove-identity=28 +Identity removed + + + + + Using 'password' authentication method + + 'password' authentication simply returns to the application the username + and the password associated with an identity. If they haven't been stored + in gSSO secret database, they're asked from the user through gSSO UI. + + + To use the method, first create an identity with authentication method + set to 'password' (as shown above), note its identitiy id and then run: + +> gsso-example --get-password=27 +Geting password +Got response: {'UserName': <'megauser'>, 'Secret': <'megapassword'>} + + + + + Using 'oauth' authentication method + + 'oauth' authentication method is used to obtain an OAuth1 or OAuth2 + authentication token from a remote service over HTTP. An application + needs to supply a few service-specific parameters when initiating the + authentication. gSSO example application supports obtaining an oauth + token from Google service (google-specific parameters are hardcoded + into the app source code). + + + Obtaining an OAuth token may also include authorization of the application + by the user, which is done through user interaction with the service webpages + that are shown by gSSO UI. From the application point of view this authorization + happens completely transparently behind the scenes. + + + Before trying the example, if you're behind a proxy, and are using + the Gtk-based gSSO UI, make sure that your GNOME proxy settings are + correctly configured, either via GNOME UI, or via command line: + +> gsettings list-recursively org.gnome.system.proxy + + To set the proxy, use: + +> gsettings set org.gnome.system.proxy mode 'manual' +> gsettings set org.gnome.system.proxy.http port 8080 +> gsettings set org.gnome.system.proxy.http host 'myproxy.domain.lan' + + To disable the proxy, use + +> gsettings set org.gnome.system.proxy mode 'none' + + See all available configurations keys here: + + http://developer.gnome.org/ProxyConfiguration/ + + + You would also need a client identifier and key from Google. Instructions + about how to get them are available at + https://developers.google.com/console/help/#generatingoauth2 + + + Once the above are settled, create an identity with 'oauth' method + (as shown above) and issue: + +> gsso-example --get-google-token=12 --client-id=xxxxxxx.apps.googleusercontent.com --client-secret=yyyyyyyyyyyyy +Geting token +Got response: {'Scope': <'email'>, 'AccessToken': <'tokenvalue'>, + 'TokenParameters': <@a{sv} {}>, 'TokenType': <'Bearer'>, + 'RefreshToken': <'refreshtokenvalue'>, 'Duration': <int64 3600>, + 'Timestamp': <int64 1377707888>} + + + + \ No newline at end of file diff --git a/docs/gumd-docs.sgml b/docs/gumd-docs.sgml new file mode 100644 index 0000000..dae4bfa --- /dev/null +++ b/docs/gumd-docs.sgml @@ -0,0 +1,75 @@ + + +]> + + + gumd and libgum API Reference Manual + This document is for gumd and libgum, version &version;. + + + + + User management Overview + + + + + + + Common + + + + + + Miscellaneous + + + + + + + + gumd + + + gumd configuration + + + + + + + + gumd and libgum Objects + + Object Hierarchy + + + + + + Appendices + + API Index + + + + + + + Index of deprecated API + + + + + + + + + + + diff --git a/docs/introduction.xml b/docs/introduction.xml new file mode 100644 index 0000000..b5f5b8d --- /dev/null +++ b/docs/introduction.xml @@ -0,0 +1,93 @@ + + + + + gumd introduction + + + + What is gumd? + + gumd is a framework for centrally storing authentication credentials + and handling authentication on behalf of applications as requested by + them. It consists of a gumd daemon that implements secure storage of + login credentials (for example usernames and passwords), plugins for + different authentication systems and a client library (libgsignond-glib) + for applications to communicate with this system. + + + By using this client library, an application can authenticate to a + (usually remote) service using an existing set of credentials, and manage + the credentials database as well (subject to access restrictions). + + + Some authentication methods require interaction with the user, for example + to request a username and password, or to show a webpage with which the + user is expected to interact. This functionality is provided by gumd UI + component, and it's completely invisible from the applications' point + of view. + + + The client library (libgsignond-glib) interacts with gumd daemon through + D-Bus. These D-Bus APIs should not be used directly as they are not documented, subject + to change and don't come with backwards compatibility guarantees. + + + + Terminology + + gumd is built around a few key concepts which are explained below: + + + + Authentication service: the top level + object representing the gumd service. It can be used to query + existing identities, available + authentication menthods and their mechanisms. Authentication + service is represented in the client library by + SignonAuthService objects. + + + + + Identity: This is a local object representing a record in the + credentials DB. It contains information about the username and password (the + latter is write-only), plus some metadata such as a descriptive caption, access + control list, reference count, and other metadata. Identities are identified by + numeric identity IDs and represented in the client library by + SignonIdentity objects. + + + + + Security context: The information that is used by gumd daemon + to make access control decisions when applications try to access identities + for reading, writing, or starting authentication sessions. Security contexts + consist of two strings: the system context which identifies the application process, + and application context which identifies what the application process is doing. Security + contexts are represented in the client library by + SignonSecurityContext objects. + + + + + Authentication method: the SSO daemon supports different + authentication methods, each implemented by a plugin. Well known examples of + authentication methods include SASL, + or OAuth. Authentication methods + might support different authentication mechanisms, which are method-specific variants of authentication process. + + + + + Authentication session: the process of performing the authentication. + It is represented in the client library by SignonAuthSession objects. + Authentication sessions are started from existing identites. + + + + + + \ No newline at end of file diff --git a/docs/version.xml.in b/docs/version.xml.in new file mode 100644 index 0000000..a24f987 --- /dev/null +++ b/docs/version.xml.in @@ -0,0 +1 @@ +@PACKAGE_VERSION@ -- 2.7.4