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