Interface Authentication.TLSCertificate

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

Methods

Accept () → nothing
Reject (a(usa{sv}): Rejections) → nothing

Signals

Accepted ()
Rejected (a(usa{sv}): Rejections)

Properties

State u ( TLS_Certificate_State) Read only
Rejections a(usa{sv}) ( TLS_Certificate_Rejection_List) Read only
CertificateType s Read only
CertificateChainData aay ( Certificate_Data_List) Read only

Types

Certificate_Data Simple Type ay
TLS_Certificate_State Enum u
TLS_Certificate_Reject_Reason Enum u
TLS_Certificate_Rejection Struct (usa{sv})
Added in 0.19.13. (as stable API)
Objects implementing this interface must also implement:

Description

This object represents a TLS certificate.

Methods

(Permalink)

Accept () → nothing

Accepts this certificate, i.e. marks it as verified.
(Permalink)

Reject (a(usa{sv}): Rejections) → nothing

Parameters

Rejects this certificate.

Possible Errors

  • Invalid Argument
    • Raised when the method is called on an object whose State is not Pending, or when the provided rejection list is empty.

Signals

(Permalink)

Accepted ()

The State of this certificate has changed to Accepted.
(Permalink)

Rejected (a(usa{sv}): Rejections)

Parameters

The State of this certificate has changed to Rejected.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

State — u (TLS_Certificate_State)

Read only
The current state of this certificate. State change notifications happen by means of the Accepted and Rejected signals.
(Permalink)

Rejections — a(usa{sv}) (TLS_Certificate_Rejection_List)

Read only

If the State is Rejected, an array of TLS_Certificate_Rejection structures containing the reason why the certificate is rejected.

If the State is not Rejected, this property is not meaningful, and SHOULD be set to an empty array.

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.

(Permalink)

CertificateType — s

Read only
The type of this TLS certificate (e.g. 'x509' or 'pgp').

This property is immutable

(Permalink)

CertificateChainData — aay (Certificate_Data_List)

Read only

One or more TLS certificates forming a trust chain, each encoded as specified by Certificate_Data.

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.

Types

Simple Type (Permalink)

Certificate_Data — ay

The raw data contained in a TLS certificate.

For X.509 certificates (CertificateType = "x509"), this MUST be in DER format, as defined by the X.690 ITU standard.

For PGP certificates (CertificateType = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1 of RFC 4880.

Enum (Permalink)

TLS_Certificate_State — u

The possible states for a TLSCertificate object.
  • Pending (0)
    • The certificate is currently waiting to be accepted or rejected.
  • Accepted (1)
    • The certificate has been verified.
  • Rejected (2)
    • The certificate has been rejected.
Enum (Permalink)

TLS_Certificate_Reject_Reason — u

Possible reasons to reject a TLS certificate.
  • Unknown (0)
    • The certificate has been rejected for another reason not listed in this enumeration.
  • Untrusted (1)
    • The certificate is not trusted.
  • Expired (2)
    • The certificate is expired.
  • Not_Activated (3)
    • The certificate is not active yet.
  • Fingerprint_Mismatch (4)
    • The certificate provided does not have the expected fingerprint.
  • Hostname_Mismatch (5)
    • The hostname certified does not match the provided one.
  • Self_Signed (6)
    • The certificate is self-signed.
  • Revoked (7)
    • The certificate has been revoked.
  • Insecure (8)
    • The certificate uses an insecure cipher algorithm, or is cryptographically weak.
  • Limit_Exceeded (9)
    • The length in bytes of the certificate, or the depth of the certificate chain exceed the limits imposed by the crypto library.
Struct (Permalink)

TLS_Certificate_Rejection — (usa{sv})

Struct representing one reason why a TLS certificate was rejected.

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.

  • Reason — u (TLS_Certificate_Reject_Reason)

    • The value of the TLS_Certificate_Reject_Reason enumeration for this certificate rejection.

    Rationale:
    Clients that do not understand the Error member, which may be implementation-specific, can use this property to classify rejection reasons into common categories.

  • Error — s (DBus_Error_Name)

    • The DBus error name for this certificate rejection.

    This MAY correspond to the value of the Reason member, or MAY be a more specific D-Bus error name, perhaps implementation-specific.

  • Details — a{sv} (String_Variant_Map)

    • Additional information about why the certificate was rejected. This MAY also include one or more of the following well-known keys:

    user-requested (b)
    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.
    expected-hostname (s)
    If the rejection reason is Hostname_Mismatch, the hostname that the server certificate was expected to have.
    certificate-hostname (s)
    If the rejection reason is Hostname_Mismatch, the hostname of the certificate that was presented.
    Rationale:

    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:

                    {
                  'expected-hostname': 'gmail.com',
                  'certificate-hostname': 'evil.example.org',
                }
    debug-message (s)
    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