5.3 The PLAIN mechanism

The PLAIN mechanism uses username and password to authenticate users. Two user names are relevant. The first, the authentication identity, indicate the credential holder, i.e., whom the provided password belongs to. The second, the authorization identity, is typically empty, to indicate that the user requests to log on to the server as herself. However, if the authorization identity is not empty, the server should decide whether the authenticated user may log on as the authorization identity. Normally, only “super-user” accounts such as `admin' or similar should be allowed this.

In the client, this mechanism is always enabled, and require the GSASL_AUTHID and GSASL_PASSWORD properties. If set, GSASL_AUTHZID will also be used.

In the server, the mechanism is always enabled. Two approaches to authenticate and authorize the client is provided.

In the first approach, the server side of the mechanism will invoke the GSASL_VALIDATE_SIMPLE callback property to decide whether the client should be accepted or not. The callback may inspect the GSASL_AUTHID, GSASL_AUTHID, and GSASL_PASSWORD properties. These properties values will be normalized.

If the first approach fails (because, e.g., your callback return `GSASL_NO_CALLBACK' to signal that it does not implement GSASL_VALIDATE_SIMPLE) the mechanism will continue to query the application for a password, via the GSASL_PASSWORD property. Your callback may use the GSASL_AUTHID and GSASL_AUTHZID properties to select the proper password. The password is then normalized and compared to the client credential.

Which approach to use? If your database store hashed passwords, you have no option, but must use the first approach. If passwords in your user database are stored in prepared (SASLprep) form, the first approach will be faster. If you do not have prepared passwords available, you can use the second approach to make sure the password is prepared properly before comparison.