From 46ff673063f32027802edf83bfff98f274149036 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Fri, 31 Jul 2009 16:38:14 +0200 Subject: Add the current docbook part of the spec and the D-Bus introspection part converted to the Telepathy D-Bus Introspection spec. tools/spec-to-introspect.xsl converts the Telepathy format to the EggDBus format used by keyring. --- secret-service/tools/spec-to-introspect.xsl | 225 ++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 secret-service/tools/spec-to-introspect.xsl (limited to 'secret-service/tools') diff --git a/secret-service/tools/spec-to-introspect.xsl b/secret-service/tools/spec-to-introspect.xsl new file mode 100644 index 0000000..b2682b1 --- /dev/null +++ b/secret-service/tools/spec-to-introspect.xsl @@ -0,0 +1,225 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Node doesn't contain a type. + + + + + + + + + + ObjectPath + String + Byte + Boolean + Int16 + UInt16 + Int32 + UInt32 + Int64 + UInt64 + Double + Signature + + Array< + + + + > + + + + + Unknown DBus Type + + + + + + + + + + + + + + Dict< + + + , + + + + > + + + + Unspecified type . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3-70-g09d2 From 3b64399e5549a017b82fb4f7f1a0cc433a0a2492 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Fri, 31 Jul 2009 23:56:00 +0200 Subject: Add spec-to-docbook.xsl for converting a telepathy spec to DocBook XML. Improve spec-to-introspect.xsl - no more extra spaces in type declarations. --- secret-service/org.freedesktop.Secrets.xml | 4 +- secret-service/tools/resolve-type.xsl | 122 +++ secret-service/tools/spec-to-docbook.xsl | 1168 +++++++++++++++++++++++++++ secret-service/tools/spec-to-introspect.xsl | 104 +-- 4 files changed, 1305 insertions(+), 93 deletions(-) create mode 100644 secret-service/tools/resolve-type.xsl create mode 100644 secret-service/tools/spec-to-docbook.xsl (limited to 'secret-service/tools') diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index ac43135..b69f06d 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -48,7 +48,7 @@ --> - The #Secret type holds a (possibly encoded) secret. + The Secret type holds a (possibly encoded) secret. Algorithm used to encode the secrets value. @@ -65,7 +65,7 @@ D-Bus object-path - + A secret diff --git a/secret-service/tools/resolve-type.xsl b/secret-service/tools/resolve-type.xsl new file mode 100644 index 0000000..a37f2af --- /dev/null +++ b/secret-service/tools/resolve-type.xsl @@ -0,0 +1,122 @@ + + + + + + + + + + + + + + + + + + + + + + + Node doesn't contain a type. + + + + + + + + + + + + ObjectPath + String + Byte + Boolean + Int16 + UInt16 + Int32 + UInt32 + Int64 + UInt64 + Double + Signature + Variant + + Dict< + + + + , + + + + > + + + Array< + + + + > + + + + + Unknown DBus Type + + + + + + + + + + + + + + Dict< + + + , + + + + > + + + + Unspecified type . + + + + + diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl new file mode 100644 index 0000000..33446a1 --- /dev/null +++ b/secret-service/tools/spec-to-docbook.xsl @@ -0,0 +1,1168 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + . + + + + + + + + + + + + + + + + + + + + + + ERR: cannot find D-Bus interface, method, + signal or property called ' + + ' + + + + + + + + + + + + + ERR: Cannot use tp:member-ref when not in an + <interface> + + + + + + + + + + ERR: interface + + has no signal/method/property called + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added in version . + + + + + + + + + Changed in version : + + + + Changed in version + + + + + + + + Deprecated since version . + + + + + + + + + + + + + Errors + + + + + + Types + + + + + + + + Simple types + + + + + + + Enumerated types + + + + + + + Sets of flags + + + + + + + Struct types + + + + + + + Map types + + + + + + + Types defined elsewhere + + + + + + + + + + + <literal><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></literal> + + + + + + + + + + + + + + + + + + + + + + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + This interface is + and is likely to cause havoc to your API/ABI if bindings are generated. + Don't include it in libraries that care about compatibility. + + + + + + + Implementations of this interface must also implement: + + + + + + + + + + + + + + + + + + + + + + Methods + + + + + + + Signals + + + + + + + Telepathy Properties + + Accessed using the + + org.freedesktop.Telepathy.Properties + + + + + + + + + + + D-Bus Properties + + Accessed using the org.freedesktop.DBus.Properties interface. + + + + + + + + + + + + + + + + ERR: missing @name on a tp:flags type + + + + + + ERR: missing @type on tp:flags type + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + + + + + + + + + + + + + + + = + + + + + + + + + + + (Undocumented) + + + + + + + + + + + + + + ERR: missing @name on a tp:enum type + + + + + + ERR: missing @type on tp:enum type + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + + + + + + + + + + + + + + + = + + + + + + + + + + + (Undocumented) + + + + + + + + + + + + + + ERR: property + + does not have an interface as parent + + + + + + ERR: missing @name on a property of + + + + + + + + ERR: missing @type on property + + : ' + + ' + + + + + + - + + + + + + , + + + read-only + + + write-only + + + read/write + + + + ERR: unknown or missing value for + @access on property + + : ' + + ' + + + + + + + + + + + + + + + + + + − + + + + + + + + + + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + In bindings that need a separate name, arrays of + should be called + . + + + + Members + + + + + + + + + + + − + + + + + + + ERR: missing @name on a tp:simple-type + + + + + + ERR: missing @type on tp:simple-type + + + + + + + + <literal><xsl:value-of select="@name"/> − <xsl:value-of select="@type"/></literal> + + + + + + + + + + + + + + + ERR: missing @name on a tp:external-type + + + + + + ERR: missing @type on tp:external-type + + + + + + + + − + + Defined by: + + + + + − ( + + , + ) + + + + − a{ + + → + } + + + + + + <literal> + <xsl:value-of select="@name"/> + </literal> + + + + + + + + In bindings that need a separate name, arrays of + should be called + . + + + Arrays of don't generally + make sense. + + + + + struct + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ERR: method + + does not have an interface as parent + + + + + + ERR: missing @name on a method of + + + + + + + + + ERR: an arg of method + + has no type + + + + + + + ERR: an 'in' arg of method + + has no name + + + + + + + INFO: an 'out' arg of method + + has no name + + + + + + ERR: an arg of method + + has direction neither 'in' nor 'out' + + + + + + + + <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> + + + + + + + + + + + + + + + + + + + + + + + + + + Parameters + + + + Name + Type + Direction + Description + + + + + + +
+ + + + + Possible errors + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ( + + + + ) + + + + + + + + + a{ + + + + } + + + + + + + ERR: Unable to find type ' + + ' + + + + + + + + ERR: tp:type ' + + ' has D-Bus type ' + + ' but has been used with type=' + + ' + + + + + + + + + + + + ( + + + + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + (undocumented) + + + + + + + + + + + + + + + - + + + + + + + + + + (undocumented) + + + + + + + + + + + + + + + + + + + (generic description) + + + (Undocumented.) + + + + + + + + + + + ERR: signal + + does not have an interface as parent + + + + + + ERR: missing @name on a signal of + + + + + + + + + ERR: an arg of signal + + has no type + + + + + ERR: an arg of signal + + has no name + + + + + + + INFO: an arg of signal + + has unnecessary direction 'in' + + + + + ERR: an arg of signal + + has direction other than 'in' + + + + + + + + <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> + + + + + + + + + + + + + + + + + Parameters + + + + Name + Type + Description + + + + + + +
+ + + + + + + + <xsl:value-of select="tp:title"/> + + + + + + + + + + + Interfaces + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stray text: {{{ + + }}} + + + + + + + Unrecognised element: { + + } + + + + + + + diff --git a/secret-service/tools/spec-to-introspect.xsl b/secret-service/tools/spec-to-introspect.xsl index b2682b1..ca8b4b6 100644 --- a/secret-service/tools/spec-to-introspect.xsl +++ b/secret-service/tools/spec-to-introspect.xsl @@ -8,18 +8,19 @@ Copyright 2009 Michael Leupold - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of - the License, or (at your option) any later version. + 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 program is distributed in the hope that it will be useful, + 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 General Public License for more details. + 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 General Public License - along with this program. If not, see . + 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 --> + + @@ -40,87 +43,6 @@ - - - - - - - - - - - - - - - - - Node doesn't contain a type. - - - - - - - - - - ObjectPath - String - Byte - Boolean - Int16 - UInt16 - Int32 - UInt32 - Int64 - UInt64 - Double - Signature - - Array< - - - - > - - - - - Unknown DBus Type - - - - - - - - - - - - - - Dict< - - - , - - - - > - - - - Unspecified type . - - - - - @@ -151,7 +73,7 @@ - + -- cgit v1.2.3-70-g09d2 From b4cef1c66a4fd7e19ebcb770fbbc406a4ece4db3 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Fri, 31 Jul 2009 23:58:50 +0200 Subject: sect[1234] -> section --- secret-service/tools/spec-to-docbook.xsl | 76 ++++++++++++++++---------------- 1 file changed, 38 insertions(+), 38 deletions(-) (limited to 'secret-service/tools') diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index 33446a1..b69cf75 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -192,47 +192,47 @@ - +
Simple types - +
- +
Enumerated types - +
- +
Sets of flags - +
- +
Struct types - +
- +
Map types - +
- +
Types defined elsewhere - +
@@ -266,7 +266,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -302,21 +302,21 @@ - +
Methods - +
- +
Signals - +
- +
Telepathy Properties Accessed using the @@ -327,11 +327,11 @@ - +
- +
D-Bus Properties Accessed using the org.freedesktop.DBus.Properties interface. @@ -339,12 +339,12 @@ - +
- +
@@ -362,7 +362,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -400,7 +400,7 @@ - +
@@ -419,7 +419,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -457,7 +457,7 @@ - +
@@ -546,7 +546,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -558,13 +558,13 @@ . - +
Members - - +
+
@@ -590,7 +590,7 @@ - +
<literal><xsl:value-of select="@name"/> − <xsl:value-of select="@type"/></literal> @@ -600,7 +600,7 @@ - +
@@ -642,7 +642,7 @@ - +
<literal> <xsl:value-of select="@name"/> @@ -673,7 +673,7 @@ <glosslist> <xsl:apply-templates select="tp:member" mode="description"/> </glosslist> - </sect2> + </section> </xsl:template> <xsl:template match="arg" mode="paramdef"> @@ -755,7 +755,7 @@ </xsl:choose> </xsl:for-each> - <sect3> + <section> <title id="{concat(../@name, concat('.', @name))}"> <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> @@ -810,7 +810,7 @@ - +
@@ -1032,7 +1032,7 @@ - +
<literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> @@ -1066,7 +1066,7 @@ - +
-- cgit v1.2.3-70-g09d2 From 20c5210807cae6c7724d1aebe2f1d5c3e0f300eb Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 02:53:32 +0200 Subject: Remove superfluous --- secret-service/tools/spec-to-docbook.xsl | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) (limited to 'secret-service/tools') diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index b69cf75..72763e6 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -759,23 +759,21 @@ <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + -- cgit v1.2.3-70-g09d2 From 4ad12bd950a49c2f96c6125076e141e94cdcde49 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 03:33:14 +0200 Subject: @direction => uppercase. --- secret-service/tools/spec-to-docbook.xsl | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'secret-service/tools') diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index 72763e6..00fc56e 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -42,6 +42,14 @@ + + + + IN + OUT + + + @@ -663,7 +671,7 @@ make sense. - + struct @@ -678,6 +686,10 @@ + + + + @@ -690,11 +702,15 @@ - + - + + + + + -- cgit v1.2.3-70-g09d2 From 01676233cf76a15dc33555ba7d7fb58d202a31e5 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 04:22:37 +0200 Subject: Minor cleanups. Add copyright (Telepathy D-Bus doesn't know authors). --- secret-service/org.freedesktop.Secrets.xml | 6 ++ secret-service/tools/spec-to-docbook.xsl | 144 +++++------------------------ 2 files changed, 29 insertions(+), 121 deletions(-) (limited to 'secret-service/tools') diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index b69f06d..da5d609 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -9,6 +9,12 @@ Secret Storage specification 0.1 + + Copyright (C) 2009 Stef Walter <stef@memberwebs.com> + + + Copyright (C) 2009 Michael Leupold <lemma@confuego.org> + - - - + + + @@ -569,7 +569,7 @@
Members - +
@@ -690,30 +690,23 @@ - - - + + + + + + - - - - - - - - - - - - - - - - + + + + + + @@ -796,22 +789,9 @@ - - Parameters - - - - Name - Type - Direction - Description - - - - - - -
+ + + @@ -931,32 +911,7 @@ - - - - - - - - - - (undocumented) - - - - - - - - - - - - - - - - - + @@ -1064,21 +1019,9 @@ - - Parameters - - - - Name - Type - Description - - - - - - -
+ + + @@ -1102,17 +1045,6 @@ Interfaces - - - - - - - - - - - @@ -1122,36 +1054,6 @@ - - -- cgit v1.2.3-70-g09d2 From eb47416f4a6e75f77bda61481d2b754b1e5c7638 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 12:11:59 +0200 Subject: Enable building the whole spec with XInclude. --- secret-service/specification.xml | 141 +++++++++++++------------------ secret-service/tools/spec-to-docbook.xsl | 6 +- 2 files changed, 64 insertions(+), 83 deletions(-) (limited to 'secret-service/tools') diff --git a/secret-service/specification.xml b/secret-service/specification.xml index 57f7cb2..6301ff8 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -72,10 +72,10 @@ choose to use a textual format to combine these values into one. For example, the 'desktop' key file format, or XML or another form of markup. - Secrets may be encrypted when transferred + Secrets may be encrypted when transferred to the client application and vice versa. - The Secret structure encapsulates + The Secret structure encapsulates a secret value along with it's transfer encryption parameters. @@ -84,10 +84,10 @@ Each secret is stored together with lookup attributes and a label. These together - form an item. + form an item. A group of items together form a - collection. + collection. A collection is similar in concept to the terms 'keyring' or 'wallet'. Collections and items are represented as DBus objects, and each have their own @@ -105,18 +105,18 @@ The service must prevent locked collections or items from modification. On such an invalid access the - IsLocked + IsLocked error should be raised. Client applications without special requirements should store in the default collection. Use the - DefaultCollection + DefaultCollection property on the Service interface to determine the default collection. In addition the default collection is always accessible through a specific object path. Client applications with special needs can create a new collection by calling the - CreateCollection() + CreateCollection() method on the Service interface. A client application must have opened a session before a collection can be created. The @@ -124,20 +124,20 @@ items within it may only be unlocked by the application that created the collection. Service implementors may choose not to implement this feature and should ignore the private argument when - creating a collection. + creating a collection. Client applications that demand this feature, should check the the - Private property + Private property after creating a collection to see if the request for a private collection was ignored. A collection can be deleted by calling the - Delete() + Delete() method on the Service interface. A client application must have opened a session before a collection can be created. However the collection does not need to be unlocked. In addition private collections can be deleted by any application. - + Lookup Attributes Attributes can and should be stored with a secret to facilitate lookup @@ -167,16 +167,16 @@ between the client application and the service. A session is established by calling the service's - OpenSession() + OpenSession() method. Once established, a session is bound to calling application's connection to the DBus session bus. Generally only one session can be established per client application. Calling OpenSession() a second time results in an - AlreadyExists + AlreadyExists error. A session is closed when the client application disconnects from the DBus session bus. Alternatively the client application can call the - Close() + Close() method on the session interface. Once a session is closed all session specific negotiations and authentication should be dropped by the service. @@ -205,7 +205,7 @@ a common way to store secrets. It's predecessors are the desktop specific APIs used by GNOME Keyring and KWallet. - +
Negotiation of Algorithms In order to encrypt secrets in transit, the service and the client @@ -214,13 +214,13 @@ The client application opens a session with the service, and then calls the - + Negotiate() method on that session. The algorithms argument to the Negotiate() method specifies a set of algorithms to be used together for key agreement and encryption. The other arguments are algorithm specific. If a service does not support a specific set of algorithms, a - NotSupported + NotSupported error is returned, and the client is free to try another set of algorithms. The plain algorithm is almost always supported. @@ -231,19 +231,19 @@ Once an algorithm has been negotiated, it is used for all transfer of secrets between the service and the client application in both directions. Algorithm specific parameters may be transfered with each - secret. - + secret. +
- +
Algorithm: plain Algorithm string: plain - + Negotiate input: empty string - + Negotiate output: empty string - + Secret parameter: empty string @@ -251,23 +251,23 @@ It is strongly recommended that a service implementing this API support the plain algorithm. - +
- +
Algorithm: dh-ietf1024-aes128-cbc-pkcs7 Algorithm string: dh-ietf1024-aes128-cbc-pkcs7 - + Negotiate input: client dh pub key as an array of bytes - + Negotiate output: service dh pub key as an array of bytes - + Secret parameter: 16 byte AES initialization vector. TODO: Document - +
@@ -281,7 +281,7 @@ In order to unlock an item or collection a session is established by the client application, and the - BeginAuthenticate() + BeginAuthenticate() method is called with one or more DBus object paths of items or collections. The BeginAuthenticate() method is asynchronous and may return before the item is actually unlocked. @@ -291,11 +291,11 @@ After the service tries to unlock an item or collection, whether successfully or unsuccessfully, the - Authenticated + Authenticated signal on the session interface is emitted. The client application may, but is not required to, call the - CompleteAuthenticate() + CompleteAuthenticate() method. One or more DBus object paths of items or collections that BeginAuthenticate() was previously called with, can be passed in. The CompleteAuthenticate() returns the items that were successfully authenticated. In addition if the unlock process is not @@ -346,62 +346,43 @@ D-Bus API Reference - - - Object Paths - + + Object Paths The various DBus object paths used with the Secrets API are designed to be human readable but not displayed to the user. The object path of an item or collection should not change for its lifetime, under normal circumstances. - - /org/freedesktop/Secrets - The object path for the service. - + /org/freedesktop/Secrets + The object path for the service. - - /org/freedesktop/Secrets/collection/xxxx - The object path for a collection, where xxxx represents a - possibly encoded or truncated version of the initial label of the collection. - + /org/freedesktop/Secrets/collection/xxxx + The object path for a collection, where xxxx represents a + possibly encoded or truncated version of the initial label of the collection. - - /org/freedesktop/Secrets/collection/xxxx/iiii + /org/freedesktop/Secrets/collection/xxxx/iiii The object path for an item, where xxxx is the collection (above) and iiii is an auto-generated item specific identifier. - - - - /org/freedesktop/Secrets/session/ssss - The object path for a session, where ssss is an auto-generated - session specific identifier. - - - - /org/freedesktop/Secrets/default - The default collection for client applications to store secrets is available under - this object path in addition to its real object path (above). - - - - - - org.freedesktop.Secrets.Collection Interface - - - org.freedesktop.Secrets.Collection Interface - Collection of items - - - - - - - - - - + + /org/freedesktop/Secrets/session/ssss + The object path for a session, where ssss is an auto-generated + session specific identifier. + + /org/freedesktop/Secrets/default + The default collection for client applications to store secrets is available under + this object path in addition to its real object path (above). + + + + + + + + + + + + - + diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index af158fa..e37c1a7 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -192,7 +192,7 @@ - + Types @@ -1043,13 +1043,13 @@ --> - + Interfaces - + -- cgit v1.2.3-70-g09d2 From 28ed9f02cd60403d2b1a92c13f1c06058fa58136 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 13:00:19 +0200 Subject: Add params to control toc generation. --- secret-service/params-html.xsl | 34 ++++++++++++ secret-service/specification.xml | 95 ++++++++++++++++++++------------ secret-service/tools/spec-to-docbook.xsl | 6 +- 3 files changed, 97 insertions(+), 38 deletions(-) create mode 100644 secret-service/params-html.xsl (limited to 'secret-service/tools') diff --git a/secret-service/params-html.xsl b/secret-service/params-html.xsl new file mode 100644 index 0000000..5f3fb27 --- /dev/null +++ b/secret-service/params-html.xsl @@ -0,0 +1,34 @@ + + + + + + 3 + 0 + + book toc + part nop + chapter nop + + style.css + ansi + + diff --git a/secret-service/specification.xml b/secret-service/specification.xml index 6301ff8..b631b6f 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -75,7 +75,7 @@ Secrets may be encrypted when transferred to the client application and vice versa. - The Secret structure encapsulates + The Secret structure encapsulates a secret value along with it's transfer encryption parameters. @@ -105,18 +105,20 @@ The service must prevent locked collections or items from modification. On such an invalid access the - IsLocked + IsLocked error should be raised. Client applications without special requirements should store in the default collection. Use the - DefaultCollection + + DefaultCollection property on the Service interface to determine the default collection. In addition the default collection is always accessible through a specific object path. Client applications with special needs can create a new collection by calling the - CreateCollection() + + CreateCollection() method on the Service interface. A client application must have opened a session before a collection can be created. The @@ -126,11 +128,12 @@ private argument when creating a collection. Client applications that demand this feature, should check the the - Private property - after creating a collection to see if the request for a private collection was ignored. + Private + property after creating a collection to see if the request for a private collection + was ignored. A collection can be deleted by calling the - Delete() + Delete() method on the Service interface. A client application must have opened a session before a collection can be created. However the collection does not need to be unlocked. In addition private collections can @@ -167,16 +170,18 @@ between the client application and the service. A session is established by calling the service's - OpenSession() + + OpenSession() method. Once established, a session is bound to calling application's connection to the DBus session bus. Generally only one session can be established per client application. Calling OpenSession() a second time results in an - AlreadyExists + + AlreadyExists error. A session is closed when the client application disconnects from the DBus session bus. Alternatively the client application can call the - Close() + Close() method on the session interface. Once a session is closed all session specific negotiations and authentication should be dropped by the service. @@ -214,13 +219,14 @@ The client application opens a session with the service, and then calls the - - Negotiate() method on that session. The algorithms argument to the + + Negotiate() method on that session. The algorithms argument to the Negotiate() method specifies a set of algorithms to be used together for key agreement and encryption. The other arguments are algorithm specific. If a service does not support a specific set of algorithms, a - NotSupported + + NotSupported error is returned, and the client is free to try another set of algorithms. The plain algorithm is almost always supported. @@ -231,21 +237,29 @@ Once an algorithm has been negotiated, it is used for all transfer of secrets between the service and the client application in both directions. Algorithm specific parameters may be transfered with each - secret. + secret.
Algorithm: plain - - Algorithm string: plain - - Negotiate input: empty string - - Negotiate output: empty string - - Secret parameter: empty string - + + + Algorithm string + + Negotiate input + + Negotiate output + + Secret parameter + + + plain + empty string + empty string + empty string + + The plain algorithm does no encryption whatsoever. @@ -256,15 +270,23 @@
Algorithm: dh-ietf1024-aes128-cbc-pkcs7 - - Algorithm string: dh-ietf1024-aes128-cbc-pkcs7 - - Negotiate input: client dh pub key as an array of bytes - - Negotiate output: service dh pub key as an array of bytes - - Secret parameter: 16 byte AES initialization vector. - + + + Algorithm string + + Negotiate input + + Negotiate output + + Secret parameter + + + dh-ietf1024-aes128-cbc-pkcs7 + client dh pub key as an array of bytes + service dh pub key as an array of bytes + 16 byte AES initialization vector + + TODO: Document
@@ -281,7 +303,8 @@ In order to unlock an item or collection a session is established by the client application, and the - BeginAuthenticate() + + BeginAuthenticate() method is called with one or more DBus object paths of items or collections. The BeginAuthenticate() method is asynchronous and may return before the item is actually unlocked. @@ -291,11 +314,13 @@ After the service tries to unlock an item or collection, whether successfully or unsuccessfully, the - Authenticated + + Authenticated() signal on the session interface is emitted. The client application may, but is not required to, call the - CompleteAuthenticate() + + CompleteAuthenticate() method. One or more DBus object paths of items or collections that BeginAuthenticate() was previously called with, can be passed in. The CompleteAuthenticate() returns the items that were successfully authenticated. In addition if the unlock process is not diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index e37c1a7..1de1f89 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -498,12 +498,12 @@ - - - + - + - + , -- cgit v1.2.3-70-g09d2 From c250c5aefcc8e14ffa54463a694c26370c1bcf6a Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 15:56:23 +0200 Subject: -> Docbook 5.0 --- secret-service/params-html.xsl | 1 + secret-service/specification.xml | 22 +- secret-service/tools/spec-to-docbook.xsl | 335 ++++++++++++++++++++----------- 3 files changed, 226 insertions(+), 132 deletions(-) (limited to 'secret-service/tools') diff --git a/secret-service/params-html.xsl b/secret-service/params-html.xsl index 5f3fb27..cc73eee 100644 --- a/secret-service/params-html.xsl +++ b/secret-service/params-html.xsl @@ -30,5 +30,6 @@ style.css ansi + 1 diff --git a/secret-service/specification.xml b/secret-service/specification.xml index b631b6f..7c1eafd 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -1,7 +1,5 @@ - - + Secrets API Specification @@ -40,7 +38,7 @@ - + API Documentation Introduction @@ -140,7 +138,7 @@ be deleted by any application. - + Lookup Attributes Attributes can and should be stored with a secret to facilitate lookup @@ -161,7 +159,7 @@ manner in order to support simple and effecient lookups. - + Sessions A session is established between a client application and a service. A session @@ -186,7 +184,7 @@ negotiations and authentication should be dropped by the service. - + Transfer of Secrets Since this is a D-Bus API, the data in all method calls and other accesses @@ -293,7 +291,7 @@ - + Authentication or Unlocking Some items and/or collections may be marked as locked by the service. @@ -368,10 +366,10 @@ - + D-Bus API Reference - + Object Paths The various DBus object paths used with the Secrets API are designed to be human @@ -411,11 +409,11 @@ + omit-xml-declaration="no"/> @@ -192,7 +190,8 @@ - + + types Types @@ -246,7 +245,10 @@ - + <title> + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/> + </xsl:attribute> <literal><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></literal> @@ -274,85 +276,130 @@ -
- <literal><xsl:value-of select="@name"/></literal> + - - - - This interface is - and is likely to cause havoc to your API/ABI if bindings are generated. - Don't include it in libraries that care about compatibility. - - - + + + + + + + + + + D-Bus Interface + + + + + + + + + + + + + + + + + + + - - - Implementations of this interface must also implement: - - - - - - - - - - - - - + + + + + This interface is + and is likely to cause havoc to your API/ABI if bindings are generated. + Don't include it in libraries that care about compatibility. + + + + - - - - + + + + Implementations of this interface must also implement: + + + + + + + + + + + + + + - -
- Methods - -
- + + + + Methods + + + + + + Signals + + + + - -
- Signals - -
- + + + Methods + + + - -
- Telepathy Properties - - Accessed using the - - org.freedesktop.Telepathy.Properties - - - - - -
- + + + Signals + + + - -
- D-Bus Properties - - Accessed using the org.freedesktop.DBus.Properties interface. - - - - -
- + + + Telepathy Properties + + Accessed using the + + org.freedesktop.Telepathy.Properties + + + + + + + + + + + D-Bus Properties + + Accessed using the org.freedesktop.DBus.Properties interface. + + + + + + + + - + -
+ @@ -371,7 +418,10 @@
- <literal><xsl:value-of select="@name"/></literal> + + + + <literal><xsl:value-of select="@name"/></literal> @@ -428,7 +478,10 @@
- <literal><xsl:value-of select="@name"/></literal> + + + + <literal><xsl:value-of select="@name"/></literal> @@ -468,7 +521,7 @@
- + @@ -497,7 +550,10 @@ - + + + + - @@ -536,7 +592,7 @@ - + @@ -555,7 +611,10 @@
- + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat('type-', @name)"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="@name"/></literal> @@ -599,7 +658,10 @@
- + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat('type-', @name)"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="@name"/> − <xsl:value-of select="@type"/></literal> @@ -628,8 +690,11 @@ - - − + + + + + − Defined by: @@ -651,7 +716,10 @@
- + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat('type-', @name)"/> + </xsl:attribute> + <title> <literal> <xsl:value-of select="@name"/> </literal> @@ -709,7 +777,47 @@ </glossentry> </xsl:template> - <xsl:template match="method"> + <xsl:template match="method|signal" mode="funcsynopsis"> + <funcsynopsis> + <funcprototype> + <funcdef> + <function> + <xsl:value-of select="@name"/> + </function> + </funcdef> + <xsl:choose> + <xsl:when test="arg"> + <xsl:apply-templates select="arg" mode="paramdef"/> + </xsl:when> + <xsl:otherwise> + <void/> + </xsl:otherwise> + </xsl:choose> + </funcprototype> + </funcsynopsis> + </xsl:template> + + <xsl:template match="method|signal" mode="funcsynopsislinked"> + <funcsynopsis> + <funcprototype> + <funcdef> + <function linkend="{concat(parent::interface//@name, '.', @name)}"> + <xsl:value-of select="@name"/> + </function> + </funcdef> + <xsl:choose> + <xsl:when test="arg"> + <xsl:apply-templates select="arg" mode="paramdef"/> + </xsl:when> + <xsl:otherwise> + <void/> + </xsl:otherwise> + </xsl:choose> + </funcprototype> + </funcsynopsis> + </xsl:template> + + <xsl:template match="method" mode="detail"> <xsl:if test="not(parent::interface)"> <xsl:message terminate="yes"> @@ -764,26 +872,15 @@ </xsl:choose> </xsl:for-each> - <section> - <title id="{concat(../@name, concat('.', @name))}"> + <refsection> + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat(../@name, concat('.', @name))"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> - - - - - - - - - - - - - - - - + + @@ -804,7 +901,7 @@ -
+ @@ -949,7 +1046,7 @@ - + @@ -1001,18 +1098,14 @@ -
- + <refsection> + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat(../@name, concat('.', @name))"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> - - - - - - - - + @@ -1023,11 +1116,11 @@ -
+ - + <xsl:value-of select="tp:title"/> @@ -1043,13 +1136,15 @@ --> - + + interfaces Interfaces - + + errors -- cgit v1.2.3-70-g09d2 From 24427d24927bbd22b3b82a6d04d3d0df05346867 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 16:17:51 +0200 Subject: Add links to the funcsynopsis listing in the top section of each interface. Unfortunately xmlto doesn't generate links for them yet. --- secret-service/tools/spec-to-docbook.xsl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'secret-service/tools') diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index b2cadd6..1917798 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -3,6 +3,7 @@