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">
  21     <tp:added version="0.19.13">(as stable API)</tp:added>
  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:struct name="TLS_Certificate_Rejection" array-name="TLS_Certificate_Rejection_List">
  44       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  45         <p>Struct representing one reason why a TLS certificate was rejected.</p>
  46         <p>Since there can be multiple things wrong with a TLS certificate,
  47         arrays of this type are used to represent lists of reasons for
  48         rejection. In that case, the most important reason SHOULD be placed
  49         first in the list.</p>
  50       </tp:docstring>
  51
  52       <tp:member name="Reason" type="u"
  53                  tp:type="TLS_Certificate_Reject_Reason">
  54         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  55           <p>The value of the TLS_Certificate_Reject_Reason enumeration for
  56           this certificate rejection.
  57           <tp:rationale>
  58             Clients that do not understand the <code>Error</code> member,
  59             which may be implementation-specific, can use this property to
  60             classify rejection reasons into common categories.
  61           </tp:rationale>
  62           </p>
  63         </tp:docstring>
  64       </tp:member>
  65
  66       <tp:member name="Error" type="s"
  67                  tp:type="DBus_Error_Name">
  68         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  69           <p>The DBus error name for this certificate rejection.</p>
  70           <p>This MAY correspond to the value of the <code>Reason</code> member,
  71           or MAY be a more specific D-Bus error name, perhaps implementation-specific.</p>
  72         </tp:docstring>
  73       </tp:member>
  74
  75       <tp:member name="Details" type="a{sv}"
  76                  tp:type="String_Variant_Map">
  77         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  78           <p>Additional information about why the certificate was rejected.
  79           This MAY also include one or more of the following well-known keys:</p>
  80           <p>
  81           <dl>
  82             <dt>user-requested (b)</dt>
  83             <dd>True if the error was due to an user-requested rejection of
  84             the certificate; False if there was an unrecoverable error in the
  85             verification process.</dd>
  86             <dt>expected-hostname (s)</dt>
  87             <dd>If the rejection reason is Hostname_Mismatch, the hostname that
  88             the server certificate was expected to have.</dd>
  89             <dt>certificate-hostname (s)</dt>
  90             <dd>If the rejection reason is Hostname_Mismatch, the hostname of
  91             the certificate that was presented.
  92             <tp:rationale>
  93               <p>For instance, if you try to connect to gmail.com but are presented
  94               with a TLS certificate issued to evil.example.org, the error details
  95               for Hostname_Mismatch MAY include:</p>
  96               <pre>
  97                 {
  98                   'expected-hostname': 'gmail.com',
  99                   'certificate-hostname': 'evil.example.org',
 100                 }
 101               </pre>
 102             </tp:rationale>
 103             </dd>
 104             <dt>debug-message (s)</dt>
 105             <dd>Debugging information on the error, corresponding to the
 106             message part of a D-Bus error message, which SHOULD NOT be
 107             displayed to users under normal circumstances</dd>
 108           </dl>
 109           </p>
 110         </tp:docstring>
 111       </tp:member>
 112     </tp:struct>
 113
 114     <tp:enum type="u" name="TLS_Certificate_State">
 115       <tp:docstring>
 116         The possible states for a <tp:dbus-ref
 117         namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref>
 118         object.
 119       </tp:docstring>
 120
 121       <tp:enumvalue suffix="Pending" value="0">
 122         <tp:docstring>
 123           The certificate is currently waiting to be accepted or rejected.
 124         </tp:docstring>
 125       </tp:enumvalue>
 126
 127       <tp:enumvalue suffix="Accepted" value="1">
 128         <tp:docstring>
 129           The certificate has been verified.
 130         </tp:docstring>
 131       </tp:enumvalue>
 132
 133       <tp:enumvalue suffix="Rejected" value="2">
 134         <tp:docstring>
 135           The certificate has been rejected.
 136         </tp:docstring>
 137       </tp:enumvalue>
 138     </tp:enum>
 139
 140     <tp:enum type="u" name="TLS_Certificate_Reject_Reason">
 141       <tp:docstring>
 142         Possible reasons to reject a TLS certificate.
 143       </tp:docstring>
 144
 145       <tp:enumvalue suffix="Unknown" value="0">
 146         <tp:docstring>
 147           The certificate has been rejected for another reason
 148           not listed in this enumeration.
 149         </tp:docstring>
 150       </tp:enumvalue>
 151
 152       <tp:enumvalue suffix="Untrusted" value="1">
 153         <tp:docstring>
 154           The certificate is not trusted.
 155         </tp:docstring>
 156       </tp:enumvalue>
 157
 158       <tp:enumvalue suffix="Expired" value="2">
 159         <tp:docstring>
 160           The certificate is expired.
 161         </tp:docstring>
 162       </tp:enumvalue>
 163
 164       <tp:enumvalue suffix="Not_Activated" value="3">
 165         <tp:docstring>
 166           The certificate is not active yet.
 167         </tp:docstring>
 168       </tp:enumvalue>
 169
 170       <tp:enumvalue suffix="Fingerprint_Mismatch" value="4">
 171         <tp:docstring>
 172           The certificate provided does not have the expected
 173           fingerprint.
 174         </tp:docstring>
 175       </tp:enumvalue>
 176
 177       <tp:enumvalue suffix="Hostname_Mismatch" value="5">
 178         <tp:docstring>
 179           The hostname certified does not match the provided one.
 180         </tp:docstring>
 181       </tp:enumvalue>
 182
 183       <tp:enumvalue suffix="Self_Signed" value="6">
 184         <tp:docstring>
 185           The certificate is self-signed.
 186         </tp:docstring>
 187       </tp:enumvalue>
 188
 189       <tp:enumvalue suffix="Revoked" value="7">
 190         <tp:docstring>
 191           The certificate has been revoked.
 192         </tp:docstring>
 193       </tp:enumvalue>
 194
 195       <tp:enumvalue suffix="Insecure" value="8">
 196         <tp:docstring>
 197           The certificate uses an insecure cipher algorithm, or is
 198           cryptographically weak.
 199         </tp:docstring>
 200       </tp:enumvalue>
 201
 202       <tp:enumvalue suffix="Limit_Exceeded" value="9">
 203         <tp:docstring>
 204           The length in bytes of the certificate, or the depth of the
 205           certificate chain exceed the limits imposed by the crypto
 206           library.
 207         </tp:docstring>
 208       </tp:enumvalue>
 209     </tp:enum>
 210
 211     <property name="State" type="u" access="read"
 212               tp:type="TLS_Certificate_State"
 213               tp:name-for-bindings="State">
 214       <tp:docstring>
 215         The current state of this certificate.
 216         State change notifications happen by means of the
 217         <tp:member-ref>Accepted</tp:member-ref> and
 218         <tp:member-ref>Rejected</tp:member-ref> signals.
 219       </tp:docstring>
 220     </property>
 221
 222     <property name="Rejections" type="a(usa{sv})" access="read"
 223               tp:type="TLS_Certificate_Rejection[]" tp:name-for-bindings="Rejections">
 224       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 225         <p>If the <tp:member-ref>State</tp:member-ref> is Rejected,
 226         an array of <tp:type>TLS_Certificate_Rejection</tp:type>
 227         structures containing the reason why the certificate is rejected.</p>
 228         <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected,
 229         this property is not meaningful, and SHOULD be set to an empty
 230         array.</p>
 231         <p>The first rejection in the list MAY be assumed to be
 232         the most important; if the array contains more than one
 233         element, the CM MAY either use the values after the first,
 234         or ignore them.</p>
 235       </tp:docstring>
 236     </property>
 237
 238     <property name="CertificateType" type="s" access="read"
 239               tp:name-for-bindings="Certificate_Type">
 240       <tp:docstring>
 241         The type of this TLS certificate (e.g. 'x509' or 'pgp').
 242         <p>This property is immutable</p>
 243       </tp:docstring>
 244     </property>
 245
 246     <property name="CertificateChainData" type="aay" access="read"
 247               tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data">
 248       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 249         <p>One or more TLS certificates forming a trust chain, each encoded as
 250         specified by <tp:type>Certificate_Data</tp:type>.</p>
 251         <p>The first certificate in the chain MUST be the server certificate,
 252         followed by the issuer's certificate, followed by the issuer's issuer
 253         and so on.</p>
 254       </tp:docstring>
 255     </property>
 256
 257     <signal name="Accepted"
 258             tp:name-for-bindings="Accepted">
 259       <tp:docstring>
 260         The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted.
 261       </tp:docstring>
 262     </signal>
 263
 264     <signal name="Rejected"
 265             tp:name-for-bindings="Rejected">
 266       <tp:docstring>
 267         The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected.
 268       </tp:docstring>
 269       <arg name="Rejections" type="a(usa{sv})" tp:type="TLS_Certificate_Rejection[]">
 270         <tp:docstring>
 271           The new value of the <tp:member-ref>Rejections</tp:member-ref> property.
 272         </tp:docstring>
 273       </arg>
 274     </signal>
 275
 276     <method name="Accept" tp:name-for-bindings="Accept">
 277       <tp:docstring>
 278         Accepts this certificate, i.e. marks it as verified.
 279       </tp:docstring>
 280     </method>
 281
 282     <method name="Reject" tp:name-for-bindings="Reject">
 283       <tp:docstring>
 284         Rejects this certificate.
 285       </tp:docstring>
 286       <arg direction="in" type="a(usa{sv})" name="Rejections"
 287            tp:type="TLS_Certificate_Rejection[]">
 288         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 289           <p>The new value of the <tp:member-ref>Rejections</tp:member-ref> property.</p>
 290           <p>This MUST NOT be an empty array.</p>
 291         </tp:docstring>
 292       </arg>
 293       <tp:possible-errors>
 294         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
 295           <tp:docstring>
 296             Raised when the method is called on an object whose <tp:member-ref>State</tp:member-ref>
 297             is not <code>Pending</code>, or when the provided rejection list is empty.
 298           </tp:docstring>
 299         </tp:error>
 300       </tp:possible-errors>
 301     </method>
 302
 303   </interface>
 304 </node>
 305 <!-- vim:set sw=2 sts=2 et ft=xml: -->