extensions/Authentication_TLS_Certificate.xml

   1 <?xml version="1.0" ?>
   2 <node name="/Authentication_TLS_Certificate" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   3   <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright>
   4   <tp:license>
   5     This library is free software; you can redistribute it and/or
   6 modify it under the terms of the GNU Lesser General Public
   7 License as published by the Free Software Foundation; either
   8 version 2.1 of the License, or (at your option) any later version.
   9
  10 This library is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public
  16 License along with this library; if not, write to the Free Software
  17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18   </tp:license>
  19
  20   <interface name="org.freedesktop.Telepathy.Authentication.TLSCertificate.DRAFT"
  21              tp:causes-havoc="experimental">
  22
  23     <tp:docstring>
  24       This object represents a TLS certificate.
  25     </tp:docstring>
  26
  27     <tp:simple-type name="Certificate_Data" array-name="Certificate_Data_List"
  28                     type="ay">
  29       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  30         <p>The raw data contained in a TLS certificate.</p>
  31
  32         <p>For X.509 certificates (<tp:member-ref>CertificateType</tp:member-ref>
  33         = "x509"), this MUST be in DER format, as defined by the
  34         <a href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf">X.690</a>
  35         ITU standard.</p>
  36
  37         <p>For PGP certificates (<tp:member-ref>CertificateType</tp:member-ref>
  38         = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1
  39         of <a href="http://www.rfc-editor.org/rfc/4880.txt">RFC 4880</a>.</p>
  40       </tp:docstring>
  41     </tp:simple-type>
  42
  43     <tp:enum type="u" name="TLS_Certificate_State">
  44       <tp:docstring>
  45         The possible states for a <tp:dbus-ref
  46         namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate.DRAFT</tp:dbus-ref>
  47         object.
  48       </tp:docstring>
  49
  50       <tp:enumvalue suffix="Pending" value="0">
  51         <tp:docstring>
  52           The certificate is currently waiting to be accepted or rejected.
  53         </tp:docstring>
  54       </tp:enumvalue>
  55
  56       <tp:enumvalue suffix="Accepted" value="1">
  57         <tp:docstring>
  58           The certificate has been verified.
  59         </tp:docstring>
  60       </tp:enumvalue>
  61
  62       <tp:enumvalue suffix="Rejected" value="2">
  63         <tp:docstring>
  64           The certificate has been rejected.
  65         </tp:docstring>
  66       </tp:enumvalue>
  67     </tp:enum>
  68
  69     <tp:enum type="u" name="TLS_Certificate_Reject_Reason">
  70       <tp:docstring>
  71         Possible reasons to reject a TLS certificate.
  72       </tp:docstring>
  73
  74       <tp:enumvalue suffix="Unknown" value="0">
  75         <tp:docstring>
  76           The certificate has been rejected for another reason
  77           not listed in this enumeration.
  78         </tp:docstring>
  79       </tp:enumvalue>
  80
  81       <tp:enumvalue suffix="Untrusted" value="1">
  82         <tp:docstring>
  83           The certificate is not trusted.
  84         </tp:docstring>
  85       </tp:enumvalue>
  86
  87       <tp:enumvalue suffix="Expired" value="2">
  88         <tp:docstring>
  89           The certificate is expired.
  90         </tp:docstring>
  91       </tp:enumvalue>
  92
  93       <tp:enumvalue suffix="Not_Activated" value="3">
  94         <tp:docstring>
  95           The certificate is not active yet.
  96         </tp:docstring>
  97       </tp:enumvalue>
  98
  99       <tp:enumvalue suffix="Fingerprint_Mismatch" value="4">
 100         <tp:docstring>
 101           The certificate provided does not have the expected
 102           fingerprint.
 103         </tp:docstring>
 104       </tp:enumvalue>
 105
 106       <tp:enumvalue suffix="Hostname_Mismatch" value="5">
 107         <tp:docstring>
 108           The hostname certified does not match the provided one.
 109         </tp:docstring>
 110       </tp:enumvalue>
 111
 112       <tp:enumvalue suffix="Self_Signed" value="6">
 113         <tp:docstring>
 114           The certificate is self-signed.
 115         </tp:docstring>
 116       </tp:enumvalue>
 117
 118       <tp:enumvalue suffix="Revoked" value="7">
 119         <tp:docstring>
 120           The certificate has been revoked.
 121         </tp:docstring>
 122       </tp:enumvalue>
 123
 124       <tp:enumvalue suffix="Insecure" value="8">
 125         <tp:docstring>
 126           The certificate uses an insecure cipher algorithm, or is
 127           cryptographically weak.
 128         </tp:docstring>
 129       </tp:enumvalue>
 130
 131       <tp:enumvalue suffix="Limit_Exceeded" value="9">
 132         <tp:docstring>
 133           The length in bytes of the certificate, or the depth of the
 134           certificate chain exceed the limits imposed by the crypto
 135           library.
 136         </tp:docstring>
 137       </tp:enumvalue>
 138     </tp:enum>
 139
 140     <property name="State" type="u" access="read"
 141               tp:type="TLS_Certificate_State"
 142               tp:name-for-bindings="State">
 143       <tp:docstring>
 144         The current state of this certificate.
 145         State change notifications happen by means of the
 146         <tp:member-ref>Accepted</tp:member-ref> and
 147         <tp:member-ref>Rejected</tp:member-ref> signals.
 148       </tp:docstring>
 149     </property>
 150
 151     <property name="RejectError" type="s" access="read"
 152               tp:type="DBus_Error_Name"
 153               tp:name-for-bindings="Reject_Error">
 154       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 155         <p>If the <tp:member-ref>State</tp:member-ref> is Rejected,
 156         the reason why the certificate was rejected; this MAY correspond to
 157         the <tp:member-ref>RejectReason</tp:member-ref>, or MAY be a more
 158         specific D-Bus error name, perhaps implementation-specific.</p>
 159         <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected,
 160         this property is not meaningful, and SHOULD be set to an empty
 161         string.</p>
 162       </tp:docstring>
 163     </property>
 164
 165     <property name="RejectDetails" type="a{sv}" access="read"
 166               tp:type="String_Variant_Map"
 167               tp:name-for-bindings="Reject_Details">
 168       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 169         <p>If the <tp:member-ref>State</tp:member-ref> is Rejected,
 170         additional information about why the certificate was rejected.</p>
 171         <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected,
 172         this property is not meaningful and SHOULD be set to an empty
 173         map.</p>
 174         <p>The additional information MAY also include
 175         one or more of the following well-known keys:</p>
 176         <dl>
 177           <dt>user-requested (b)</dt>
 178           <dd>True if the error was due to an user-requested rejection of
 179           the certificate; False if there was an unrecoverable error in the
 180           verification process.</dd>
 181           <dt>expected-hostname (s)</dt>
 182           <dd>If the rejection reason is Hostname_Mismatch, the hostname that
 183           the server certificate was expected to have.</dd>
 184           <dt>certificate-hostname (s)</dt>
 185           <dd>If the rejection reason is Hostname_Mismatch, the hostname of
 186           the certificate that was presented.
 187           <tp:rationale>
 188             <p>For instance, if you try to connect to gmail.com but are presented
 189             with a TLS certificate issued to evil.example.org, the error details
 190             for Hostname_Mismatch MAY include:</p>
 191             <pre>
 192               {
 193                 'expected-hostname': 'gmail.com',
 194                 'certificate-hostname': 'evil.example.org',
 195               }
 196             </pre>
 197           </tp:rationale>
 198           </dd>
 199           <dt>debug-message (s)</dt>
 200           <dd>Debugging information on the error, corresponding to the
 201           message part of a D-Bus error message, which SHOULD NOT be
 202           displayed to users under normal circumstances</dd>
 203         </dl>
 204       </tp:docstring>
 205     </property>
 206
 207     <property name="RejectReason" type="u" access="read"
 208               tp:type="TLS_Certificate_Reject_Reason"
 209               tp:name-for-bindings="Reject_Reason">
 210       <tp:docstring>
 211         If the <tp:member-ref>State</tp:member-ref> is Rejected, the
 212         reason why the certificate was rejected.
 213         <tp:rationale>
 214           Clients that do not understand the <tp:member-ref>RejectError</tp:member-ref>,
 215           which may be implementation-specific, can use this property to
 216           classify rejection reasons into common categories.
 217         </tp:rationale>
 218         Otherwise, this property is not meaningful, and SHOULD be set to
 219         Unknown.
 220       </tp:docstring>
 221     </property>
 222
 223     <property name="CertificateType" type="s" access="read"
 224               tp:name-for-bindings="Certificate_Type">
 225       <tp:docstring>
 226         The type of this TLS certificate (e.g. 'x509' or 'pgp').
 227         <p>This property is immutable</p>
 228       </tp:docstring>
 229     </property>
 230
 231     <property name="CertificateChainData" type="aay" access="read"
 232               tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data">
 233       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 234         <p>One or more TLS certificates forming a trust chain, each encoded as
 235         specified by <tp:type>Certificate_Data</tp:type>.</p>
 236         <p>The first certificate in the chain MUST be the server certificate,
 237         followed by the issuer's certificate, followed by the issuer's issuer
 238         and so on.</p>
 239       </tp:docstring>
 240     </property>
 241
 242     <signal name="Accepted"
 243             tp:name-for-bindings="Accepted">
 244       <tp:docstring>
 245         The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted.
 246       </tp:docstring>
 247     </signal>
 248
 249     <signal name="Rejected"
 250             tp:name-for-bindings="Rejected">
 251       <tp:docstring>
 252         The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected.
 253       </tp:docstring>
 254       <arg name="Reason" type="u" tp:type="TLS_Certificate_Reject_Reason">
 255         <tp:docstring>
 256           The new value of <tp:member-ref>RejectReason</tp:member-ref>.
 257         </tp:docstring>
 258       </arg>
 259       <arg name="Error" type="s" tp:type="DBus_Error_Name">
 260         <tp:docstring>
 261           The new value of <tp:member-ref>RejectError</tp:member-ref>.
 262         </tp:docstring>
 263       </arg>
 264       <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
 265         <tp:docstring>
 266           The new value of <tp:member-ref>RejectDetails</tp:member-ref>
 267         </tp:docstring>
 268       </arg>
 269     </signal>
 270
 271     <method name="Accept" tp:name-for-bindings="Accept">
 272       <tp:docstring>
 273         Accepts this certificate, i.e. marks it as verified.
 274       </tp:docstring>
 275     </method>
 276
 277     <method name="Reject" tp:name-for-bindings="Reject">
 278       <tp:docstring>
 279         Rejects this certificate.
 280       </tp:docstring>
 281       <arg direction="in" type="u" name="Reason"
 282            tp:type="TLS_Certificate_Reject_Reason">
 283         <tp:docstring>
 284           The new value of <tp:member-ref>RejectReason</tp:member-ref>.
 285         </tp:docstring>
 286       </arg>
 287       <arg direction="in" type="s" name="Error"
 288            tp:type="DBus_Error_Name">
 289         <tp:docstring>
 290           The new value of <tp:member-ref>RejectError</tp:member-ref>.
 291         </tp:docstring>
 292       </arg>
 293       <arg direction="in" type="a{sv}" name="Details"
 294            tp:type="String_Variant_Map">
 295         <tp:docstring>
 296           The new value of <tp:member-ref>RejectDetails</tp:member-ref>.
 297         </tp:docstring>
 298       </arg>
 299     </method>
 300
 301   </interface>
 302 </node>