Interface Channel.Interface.CaptchaAuthentication1

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

Methods

GetCaptchas () → a(ussuas): Captcha_Info, u: Number_Required, s: Language
GetCaptchaData (u: ID, s: Mime_Type) → ay: Captcha_Data
AnswerCaptchas (a{us}: Answers) → nothing
CancelCaptcha (u: Reason, s: Debug_Message) → nothing

Properties

CanRetryCaptcha b Read only Immutable
CaptchaStatus u (Captcha_Status) Read only
CaptchaError s (DBus_Error_Name) Read only
CaptchaErrorDetails a{sv} (String_Variant_Map) Read only

Types

Captcha_Cancel_Reason Enum u
Captcha_Status Enum u
Captcha_Flags Flags u
Captcha_Answers Mapping a{us}
Captcha_Info Struct (ussuas)
Added in 0.25.2. (version 1)
Objects implementing this interface must also implement:

Description

A channel interface for captcha authentication. When this interface appears on a ServerAuthentication1 channel, it represents authentication with the server. In future, it could also be used to authenticate with secondary services, or even to authenticate end-to-end connections with contacts. As a result, this interface does not REQUIRE ServerAuthentication1 to allow for a potential future Channel.Type.PeerAuthentication interface.

In any protocol that requires a captcha, the connection manager can use this channel to let a user interface carry out a simple captcha handshake with it, as a way to test the user is human interactively.

For channels managed by a ChannelDispatcher, only the channel's Handler may call the methods on this interface. Other clients MAY observe the authentication process by watching its signals and properties.

The most commonly used form of captcha challenge is OCR (recognition of distorted letters or words in an image), but for accessibility reasons, this interface also allows various other types of challenge, such as plain-text questions or recognition of words in audio. Its structure is modelled on XMPP's XEP-0158, but can be used with other protocols by mapping their semantics into those used in XMPP.

Rationale:

It is important to support multiple types of captcha challenge to avoid discriminating against certain users; for instance, blind or partially-sighted users cannot be expected to answer an OCR challenge.

XEP-0158 supports a superset of all other known protocols' captcha interfaces, and is sufficiently elaborate that we expect it will continue to do so.

There can only be one Handler, which is a good fit for the question/answer model implied by captchas.

Methods

(Permalink)

GetCaptchas () → a(ussuas): Captcha_Info, u: Number_Required, s: Language

Returns

  • Captcha_Info — a(ussuas) (Captcha_Info_List)
    • Information about each of the available captcha methods.
  • Number_Required — u
    • The number of captcha methods required to be answered in order to successfully complete this captcha challenge (most frequently 1, but XMPP allows servers to demand that more than one captcha is answered).
  • Language — s (Language_Tag)
    • The language of each Label in Captcha_Info if available, for instance en_US, or "" if unknown.

Gets information regarding each of the captcha methods available and which and how many need to be successfully answered

To call this method successfully, the state must be Local_Pending or Try_Again. If it is Local_Pending, it remains Local_Pending. If called more than once while in Local_Pending state, or if the state is Try_Again, this method fetches a new set of captcha challenges, if possible, and the state returns to Local_Pending.

Rationale:

For instance, you could call GetCaptchas again from Local_Pending state if the user indicates that they can't understand the initially-offered captcha.

This is a method, not a property, so that it can be used to fetch more than one set of captcha challenges, and so that change notification is not required. Only the Handler should call this method and calling GetAll would not reduce round-trips, so the usual reasons to prefer a property do not apply here.

Possible Errors

  • Not Available
    • Either the state is not Local_Pending or Try_Again, or it has already been called and CanRetryCaptcha is False.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
(Permalink)

GetCaptchaData (u: ID, s: Mime_Type) → ay: Captcha_Data

Parameters

  • ID — u
    • The ID of the captcha of which to retrieve data.
  • Mime_Type — s
    • MIME type picked by the Handler, chosen from the list of MIME types received in GetCaptchas.
    Rationale:
    XEP-0158 allows the same captcha to be made available in multiple formats, for instance the same spoken question as audio/x-wav, application/ogg and audio/speex.

Returns

  • Captcha_Data — ay
    • Captcha data as requested.

Fetch and return the captcha data. In protocols where captchas are downloaded out-of-band (for instance via HTTP), the connection manager is expected to do so.

Returns an empty array if the type was "qa"

Rationale:

If audio-based and image-based captchas are both available, we don't want to waste time downloading the audio until/unless the user asks to hear it. The extra D-Bus round-trips are not a problem, since they are expected to be quick compared with the time taken for the user to solve the captcha.

Possible Errors

(Permalink)

AnswerCaptchas (a{us}: Answers) → nothing

Parameters

  • Answers — a{us} (Captcha_Answers)
    • The mapping of captcha IDs to answer strings.

Answer as many captchas as desired and/or required.

Callable in state Local_Pending only. State changes to Remote_Pending.

Possible Errors

  • Not Available
    • The state is not in Local_Pending.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
(Permalink)

CancelCaptcha (u: Reason, s: Debug_Message) → nothing

Parameters

  • Reason — u (Captcha_Cancel_Reason)
    • Reason for cancelling. This MAY be used to choose an error response to the remote server, and SHOULD also be reflected in the CaptchaError.
  • Debug_Message — s
    • A textual description of the reason for cancelling, supplied by the Handler. This message SHOULD NOT be sent to the remote server, but SHOULD be copied into the 'debug-message' field of the CaptchaErrorDetails and ConnectionError.

Cancel. State changes to Failed with error NotAvailable or Cancelled if it isn't already Failed. All you can do now is to close the channel.

Possible Errors

Properties

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

CanRetryCaptcha — b

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.

If true, GetCaptchas can be expected to return new captcha information when in the Local_Pending state. If false, GetCaptchas will return NotAvailable on subsequent calls.

Rationale:

Refreshing the captcha isn't required to work, although some protocols and implementations allow it. This is usually done in case a given captcha is unintelligible.

(Permalink)

CaptchaStatus — u (Captcha_Status)

Read only
When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal is emitted with the new value.

The current status of this channel.

Because only the Handler should call methods on this interface, the Handler MAY reduce round-trips by not fetching the initial value of this property, and instead assume that is initially Local_Pending.

Rationale:

This assumption normally avoids the need to call GetAll(), since the values of CaptchaError and CaptchaErrorDetails are also implied by this assumption, and the only other property is CanRetryCaptcha, which is immutable.

(Permalink)

CaptchaError — s (DBus_Error_Name)

Read only
When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal is emitted with the new value.

The reason for the CaptchaStatus, or an empty string if the state is neither Try_Again nor Failed.

Typical values: "", Cancelled, AuthenticationFailed, CaptchaNotSupported

In particular, an ordinary authentication failure (as would be produced for an incorrect answer) SHOULD be represented by AuthenticationFailed, cancellation by the user's request SHOULD be represented by Cancelled, cancellation due to the inability to display the captcha to the user or otherwise answer it SHOULD be represented by CaptchaNotSupported, and cancellation by a local process due to inconsistent or invalid challenges from the server SHOULD be represented by ServiceConfused.

If this interface appears on a ServerAuthentication1 channel, and connection to the server fails with an authentication failure, this error code SHOULD be copied into the Connection.ConnectionError signal.

(Permalink)

CaptchaErrorDetails — a{sv} (String_Variant_Map)

Read only
When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal is emitted with the new value.

If CaptchaError is non-empty, any additional information about the last disconnection; otherwise, the empty map. The keys and values are the same as for the second argument of Connection.ConnectionError.

If this interface appears on a ServerAuthentication1 channel, and connection to the server fails with an authentication failure, these details SHOULD be copied into the Connection.ConnectionError signal.

Types

Enum (Permalink)

Captcha_Cancel_Reason — u

A reason why captcha authentication was aborted by the client.

  • User_Cancelled (0)
    • The user aborted the authentication. If this is used, the CaptchaError SHOULD be set to Cancelled
  • Not_Supported (1)
    • The Handler doesn't support the given/required captcha types. If this is used, the CaptchaError SHOULD be set to CaptchaNotSupported. This SHOULD also be used if Close is called before CancelCaptcha.
    Rationale:
    If no Handler supports captcha channels, the ChannelDispatcher will just call Close, because it has no knowledge of specific channel types.
  • Service_Confused (2)
    • The Handler doesn't understand the captcha data received. The challenger may be sending gibberish. If this is used, the CaptchaError SHOULD be set to ServiceConfused.
Enum (Permalink)

Captcha_Status — u

  • Local_Pending (0)
    • The challenge/response exchange is in progress and waiting for a local action. Call AnswerCaptchas to go to the Remote_Pending state, or call CancelCaptcha followed by Close to give up.
  • Remote_Pending (1)
    • The challenge/response exchange is in progress and waiting for a response from the server. Wait for a reply from the server, which will result in the Succeeded, Try_Again, or Failed state, or call CancelCaptcha followed by Close to give up.
  • Succeeded (2)
    • Everyone is happy. Connection to the server will proceed as soon as this state is reached. There is nothing useful to do in this state except to call Close to close the channel.
  • Try_Again (3)
    • The server has indicated an authentication failure. Call GetCaptchas again to get a new captcha, or CancelCaptcha followed by Close to give up.
  • Failed (4)
    • Authentication has failed in some way. There is nothing useful to do in this state except to close the channel with Close.
Flags (Permalink)

Captcha_Flags — u

Extra flags to include with Captcha information

  • Required (1)
    • This captcha mechanism is required to be successfully answered in order to pass this captcha challenge.
Mapping (Permalink)

Captcha_Answers — a{us}

A mapping of captcha IDs to answer strings.
  • ID — u
    • The ID of the captcha to which the associated answer string is answering.
  • Answer — s
    • The answer string to answer the captcha referenced by the associated ID.
Struct (Permalink)

Captcha_Info — (ussuas)

A struct containing information regarding a single captcha mechanism.

  • ID — u

    • The ID with which to reference this captcha method when retrieving its data and answering it. They are unique within this channel instance only.

  • Type — s

    • The type of challenge as defined by XEP-0158. For instance, the commonly-used "type the letters/words you see in this image" challenge is represented by ocr

  • Label — s

    • A human-readable label for the challenge, as defined in XEP-0158.

    If the server does not supply a label for a challenge of type other than qa, connection managers SHOULD set Label to an empty string instead of generating their own text. If the Label is an empty string, the Handler SHOULD replace it with a generic label in the user's locale, such as the strings suggested in XEP-0158 (for instance, Enter the text you see for ocr challenges). The Handler MAY use those generic labels in any case, as per the Internationalization Considerations section of XEP-0158.

    Rationale:

    Connection managers are not usually localized, so text generated by the connection manager would be in English, regardless of the user's locale. The Handler is better-placed to generate a generic Label in the user's locale.

    For challenges of type qa, the Label is a plain-text question for the user to answer. The connection manager SHOULD NOT provide an empty Label; if it does, the Handler SHOULD treat that challenge as impossible, and SHOULD NOT attempt to display it.

  • Flags — u (Captcha_Flags)

    • One flag defined: Required. Most captchas will have no flags.

  • Available_MIME_Types — as

    • A list of MIME types the server is offering to provide for this captcha method.