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.

(version 1)

A channel interface for captcha authentication. When this interface appears on a ServerAuthentication 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 ServerAuthentication 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.

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.

A struct containing information regarding a single captcha mechanism.

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

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

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.

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.

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

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

A mapping of captcha IDs to answer strings. The ID of the captcha to which the associated answer string is answering. The answer string to answer the captcha referenced by the associated ID.

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.

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.

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.

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.

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 ServerAuthentication channel, and connection to the server fails with an authentication failure, this error code SHOULD be copied into the Connection.ConnectionError signal.

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 ServerAuthentication channel, and connection to the server fails with an authentication failure, these details SHOULD be copied into the Connection.ConnectionError signal.

Information about each of the available captcha methods. 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). 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.

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.

Either the state is not Local_Pending or Try_Again, or it has already been called and CanRetryCaptcha is False.

The ID of the captcha of which to retrieve data. MIME type picked by the Handler, chosen from the list of MIME types received in GetCaptchas. 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. 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"

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.

The state is not in Local_Pending or GetCaptchas had never been called.

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.

The state is not in Local_Pending.

Reason for cancelling. This MAY be used to choose an error response to the remote server, and SHOULD also be reflected in the CaptchaError. 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.

The current state is Failed.

Extra flags to include with Captcha information

This captcha mechanism is required to be successfully answered in order to pass this captcha challenge.

A reason why captcha authentication was aborted by the client.

The user aborted the authentication. If this is used, the CaptchaError SHOULD be set to Cancelled 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. If no Handler supports captcha channels, the ChannelDispatcher will just call Close, because it has no knowledge of specific channel types. 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. 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. 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. 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. The server has indicated an authentication failure. Call GetCaptchas again to get a new captcha, or CancelCaptcha followed by Close to give up. Authentication has failed in some way. There is nothing useful to do in this state except to close the channel with Close.