diff options
Diffstat (limited to 'spec/Authentication_TLS_Certificate.xml')
| -rw-r--r-- | spec/Authentication_TLS_Certificate.xml | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml new file mode 100644 index 0000000..db1d76f --- /dev/null +++ b/spec/Authentication_TLS_Certificate.xml @@ -0,0 +1,305 @@ +<?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"> + <tp:added version="0.19.13">(as stable API)</tp:added> + + <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:struct name="TLS_Certificate_Rejection" array-name="TLS_Certificate_Rejection_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Struct representing one reason why a TLS certificate was rejected.</p> + <p>Since there can be multiple things wrong with a TLS certificate, + arrays of this type are used to represent lists of reasons for + rejection. In that case, the most important reason SHOULD be placed + first in the list.</p> + </tp:docstring> + + <tp:member name="Reason" type="u" + tp:type="TLS_Certificate_Reject_Reason"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The value of the TLS_Certificate_Reject_Reason enumeration for + this certificate rejection. + <tp:rationale> + Clients that do not understand the <code>Error</code> member, + which may be implementation-specific, can use this property to + classify rejection reasons into common categories. + </tp:rationale> + </p> + </tp:docstring> + </tp:member> + + <tp:member name="Error" type="s" + tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The DBus error name for this certificate rejection.</p> + <p>This MAY correspond to the value of the <code>Reason</code> member, + or MAY be a more specific D-Bus error name, perhaps implementation-specific.</p> + </tp:docstring> + </tp:member> + + <tp:member name="Details" type="a{sv}" + tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about why the certificate was rejected. + This MAY also include one or more of the following well-known keys:</p> + <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> + </p> + </tp:docstring> + </tp:member> + </tp:struct> + + <tp:enum type="u" name="TLS_Certificate_State"> + <tp:docstring> + The possible states for a <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</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="Rejections" type="a(usa{sv})" access="read" + tp:type="TLS_Certificate_Rejection[]" tp:name-for-bindings="Rejections"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the <tp:member-ref>State</tp:member-ref> is Rejected, + an array of <tp:type>TLS_Certificate_Rejection</tp:type> + structures containing the reason why the certificate is 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 + array.</p> + <p>The first rejection in the list MAY be assumed to be + the most important; if the array contains more than one + element, the CM MAY either use the values after the first, + or ignore them.</p> + </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="Rejections" type="a(usa{sv})" tp:type="TLS_Certificate_Rejection[]"> + <tp:docstring> + The new value of the <tp:member-ref>Rejections</tp:member-ref> property. + </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="a(usa{sv})" name="Rejections" + tp:type="TLS_Certificate_Rejection[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The new value of the <tp:member-ref>Rejections</tp:member-ref> property.</p> + <p>This MUST NOT be an empty array.</p> + </tp:docstring> + </arg> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + Raised when the method is called on an object whose <tp:member-ref>State</tp:member-ref> + is not <code>Pending</code>, or when the provided rejection list is empty. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |