Add spec extensions.

3 files changed, 364 insertions, 0 deletions

diff --git a/extensions/Authentication_TLS_Certificate.xml b/extensions/Authentication_TLS_Certificate.xml
new file mode 100644
index 00000000..56e378f4
--- /dev/null
+++ b/extensions/Authentication_TLS_Certificate.xml
@@ -0,0 +1,302 @@
+<?xml version="1.0" ?>
+<node name="/Authentication_TLS_Certificate" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright>
+  <tp:license>
+    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 Street, Fifth Floor, Boston, MA 02110-1301, USA.
+  </tp:license>
+
+  <interface name="org.freedesktop.Telepathy.Authentication.TLSCertificate.DRAFT"
+	     tp:causes-havoc="experimental">
+
+    <tp:docstring>
+      This object represents a TLS certificate.
+    </tp:docstring>
+
+    <tp:simple-type name="Certificate_Data" array-name="Certificate_Data_List"
+		    type="ay">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+	<p>The raw data contained in a TLS certificate.</p>
+
+	<p>For X.509 certificates (<tp:member-ref>CertificateType</tp:member-ref>
+	= "x509"), this MUST be in DER format, as defined by the
+	<a href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf">X.690</a>
+	ITU standard.</p>
+
+	<p>For PGP certificates (<tp:member-ref>CertificateType</tp:member-ref>
+	= "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1
+	of <a href="http://www.rfc-editor.org/rfc/4880.txt">RFC 4880</a>.</p>
+      </tp:docstring>
+    </tp:simple-type>
+
+    <tp:enum type="u" name="TLS_Certificate_State">
+      <tp:docstring>
+	The possible states for a <tp:dbus-ref
+	namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate.DRAFT</tp:dbus-ref>
+	object.
+      </tp:docstring>
+
+      <tp:enumvalue suffix="Pending" value="0">
+	<tp:docstring>
+	  The certificate is currently waiting to be accepted or rejected.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Accepted" value="1">
+	<tp:docstring>
+	  The certificate has been verified.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Rejected" value="2">
+	<tp:docstring>
+	  The certificate has been rejected.
+	</tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:enum type="u" name="TLS_Certificate_Reject_Reason">
+      <tp:docstring>
+	Possible reasons to reject a TLS certificate.
+      </tp:docstring>
+
+      <tp:enumvalue suffix="Unknown" value="0">
+	<tp:docstring>
+	  The certificate has been rejected for another reason
+	  not listed in this enumeration.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Untrusted" value="1">
+	<tp:docstring>
+	  The certificate is not trusted.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Expired" value="2">
+	<tp:docstring>
+	  The certificate is expired.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Not_Activated" value="3">
+	<tp:docstring>
+	  The certificate is not active yet.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Fingerprint_Mismatch" value="4">
+	<tp:docstring>
+	  The certificate provided does not have the expected
+	  fingerprint.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Hostname_Mismatch" value="5">
+	<tp:docstring>
+	  The hostname certified does not match the provided one.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Self_Signed" value="6">
+	<tp:docstring>
+	  The certificate is self-signed.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Revoked" value="7">
+	<tp:docstring>
+	  The certificate has been revoked.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Insecure" value="8">
+	<tp:docstring>
+	  The certificate uses an insecure cipher algorithm, or is
+	  cryptographically weak.
+	</tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Limit_Exceeded" value="9">
+	<tp:docstring>
+	  The length in bytes of the certificate, or the depth of the
+	  certificate chain exceed the limits imposed by the crypto
+	  library.
+	</tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <property name="State" type="u" access="read"
+	      tp:type="TLS_Certificate_State"
+	      tp:name-for-bindings="State">
+      <tp:docstring>
+	The current state of this certificate.
+	State change notifications happen by means of the
+	<tp:member-ref>Accepted</tp:member-ref> and
+	<tp:member-ref>Rejected</tp:member-ref> signals.
+      </tp:docstring>
+    </property>
+
+    <property name="RejectError" type="s" access="read"
+	      tp:type="DBus_Error_Name"
+	      tp:name-for-bindings="Reject_Error">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+	<p>If the <tp:member-ref>State</tp:member-ref> is Rejected,
+	the reason why the certificate was rejected; this MAY correspond to
+	the <tp:member-ref>RejectReason</tp:member-ref>, or MAY be a more
+	specific D-Bus error name, perhaps implementation-specific.</p>
+	<p>If the <tp:member-ref>State</tp:member-ref> is not Rejected,
+	this property is not meaningful, and SHOULD be set to an empty
+	string.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="RejectDetails" type="a{sv}" access="read"
+	      tp:type="String_Variant_Map"
+	      tp:name-for-bindings="Reject_Details">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+	<p>If the <tp:member-ref>State</tp:member-ref> is Rejected,
+	additional information about why the certificate was rejected.</p>
+	<p>If the <tp:member-ref>State</tp:member-ref> is not Rejected,
+	this property is not meaningful and SHOULD be set to an empty
+	map.</p>
+	<p>The additional information MAY also include
+	one or more of the following well-known keys:</p>
+	<dl>
+	  <dt>user-requested (b)</dt>
+	  <dd>True if the error was due to an user-requested rejection of
+	  the certificate; False if there was an unrecoverable error in the
+	  verification process.</dd>
+	  <dt>expected-hostname (s)</dt>
+	  <dd>If the rejection reason is Hostname_Mismatch, the hostname that
+	  the server certificate was expected to have.</dd>
+	  <dt>certificate-hostname (s)</dt>
+	  <dd>If the rejection reason is Hostname_Mismatch, the hostname of
+	  the certificate that was presented.
+	  <tp:rationale>
+	    <p>For instance, if you try to connect to gmail.com but are presented
+	    with a TLS certificate issued to evil.example.org, the error details
+	    for Hostname_Mismatch MAY include:</p>
+	    <pre>
+	      {
+	        'expected-hostname': 'gmail.com',
+	        'certificate-hostname': 'evil.example.org',
+	      }
+	    </pre>
+	  </tp:rationale>
+	  </dd>
+          <dt>debug-message (s)</dt>
+          <dd>Debugging information on the error, corresponding to the
+          message part of a D-Bus error message, which SHOULD NOT be
+          displayed to users under normal circumstances</dd>
+	</dl>
+      </tp:docstring>
+    </property>
+
+    <property name="RejectReason" type="u" access="read"
+	      tp:type="TLS_Certificate_Reject_Reason"
+	      tp:name-for-bindings="Reject_Reason">
+      <tp:docstring>
+	If the <tp:member-ref>State</tp:member-ref> is Rejected, the
+	reason why the certificate was rejected.
+	<tp:rationale>
+	  Clients that do not understand the <tp:member-ref>RejectError</tp:member-ref>,
+	  which may be implementation-specific, can use this property to
+	  classify rejection reasons into common categories.
+	</tp:rationale>
+	Otherwise, this property is not meaningful, and SHOULD be set to
+	Unknown.
+      </tp:docstring>
+    </property>
+
+    <property name="CertificateType" type="s" access="read"
+	      tp:name-for-bindings="Certificate_Type">
+      <tp:docstring>
+	The type of this TLS certificate (e.g. 'x509' or 'pgp').
+	<p>This property is immutable</p>
+      </tp:docstring>
+    </property>
+
+    <property name="CertificateChainData" type="aay" access="read"
+	      tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+	<p>One or more TLS certificates forming a trust chain, each encoded as
+	specified by <tp:type>Certificate_Data</tp:type>.</p>
+	<p>The first certificate in the chain MUST be the server certificate,
+	followed by the issuer's certificate, followed by the issuer's issuer
+	and so on.</p>
+      </tp:docstring>
+    </property>
+
+    <signal name="Accepted"
+	    tp:name-for-bindings="Accepted">
+      <tp:docstring>
+	The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted.
+      </tp:docstring>
+    </signal>
+
+    <signal name="Rejected"
+	    tp:name-for-bindings="Rejected">
+      <tp:docstring>
+	The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected.
+      </tp:docstring>
+      <arg name="Reason" type="u" tp:type="TLS_Certificate_Reject_Reason">
+	<tp:docstring>
+	  The new value of <tp:member-ref>RejectReason</tp:member-ref>.
+	</tp:docstring>
+      </arg>
+      <arg name="Error" type="s" tp:type="DBus_Error_Name">
+	<tp:docstring>
+	  The new value of <tp:member-ref>RejectError</tp:member-ref>.
+	</tp:docstring>
+      </arg>
+      <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+	<tp:docstring>
+	  The new value of <tp:member-ref>RejectDetails</tp:member-ref>
+	</tp:docstring>
+      </arg>
+    </signal>
+
+    <method name="Accept" tp:name-for-bindings="Accept">
+      <tp:docstring>
+	Accepts this certificate, i.e. marks it as verified.
+      </tp:docstring>
+    </method>
+
+    <method name="Reject" tp:name-for-bindings="Reject">
+      <tp:docstring>
+	Rejects this certificate.
+      </tp:docstring>
+      <arg direction="in" type="u" name="Reason"
+	   tp:type="TLS_Certificate_Reject_Reason">
+	<tp:docstring>
+	  The new value of <tp:member-ref>RejectReason</tp:member-ref>.
+	</tp:docstring>
+      </arg>
+      <arg direction="in" type="s" name="Error"
+	   tp:type="DBus_Error_Name">
+	<tp:docstring>
+	  The new value of <tp:member-ref>RejectError</tp:member-ref>.
+	</tp:docstring>
+      </arg>
+      <arg direction="in" type="a{sv}" name="Details"
+	   tp:type="String_Variant_Map">
+	<tp:docstring>
+	  The new value of <tp:member-ref>RejectDetails</tp:member-ref>.
+	</tp:docstring>
+      </arg>
+    </method>
+
+  </interface>
+</node>
diff --git a/extensions/Channel_Type_Server_TLS_Connection.xml b/extensions/Channel_Type_Server_TLS_Connection.xml
new file mode 100644
index 00000000..af11218a
--- /dev/null
+++ b/extensions/Channel_Type_Server_TLS_Connection.xml
@@ -0,0 +1,59 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Server_TLS_Connection"
+    xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright>
+  <tp:license>
+    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 Street, Fifth Floor, Boston, MA 02110-1301, USA.
+  </tp:license>
+
+  <interface name="org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection.DRAFT"
+	     tp:causes-havoc="experimental">
+
+    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>A channel type that carries a TLS certificate between a server
+      and a client connecting to it.</p>
+      <p>Channels of this kind always have <tp:dbus-ref
+      namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> = False,
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+      = None and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+      = 0, and cannot be requested with methods such as <tp:dbus-ref
+      namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+      Also, they SHOULD be dispatched while the
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+      owning them is in the CONNECTING state.</p>
+      <p>In this case, handlers SHOULD accept or reject the certificate, using
+      the relevant methods on the provided object, or MAY just <tp:dbus-ref
+      namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the channel before doing so, to fall
+      back to a non-interactive verification process done inside the CM.</p>
+      <p>For example, channels of this kind can pop up while a client is
+      connecting to an XMPP server.</p>
+    </tp:docstring>
+
+    <property name="ServerCertificate" type="o" access="read"
+	      tp:name-for-bindings="ServerCertificate">
+      <tp:docstring>
+	<p>A <tp:dbus-ref
+	namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate.DRAFT</tp:dbus-ref>
+	containing the certificate chain as sent by the server,
+	and other relevant information.</p>
+	<p>This property is immutable.</p>
+      </tp:docstring>
+    </property>
+
+  </interface>
+</node>
+
diff --git a/extensions/all.xml b/extensions/all.xml
index 22827090..7ea6c0cf 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -63,6 +63,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA</p>
 <xi:include href="Channel_Type_Server_Authentication.xml" />
 <xi:include href="Channel_Interface_Sasl_Authentication.xml" />
 
+<xi:include href="Channel_Type_Server_TLS_Connection.xml" />
+<xi:include href="Authentication_TLS_Certificate.xml" />
+
 <tp:generic-types>
   <tp:external-type name="Contact_Handle" type="u"
     from="Telepathy specification"/>