On 27/05/2026 16:01 EEST kristoffermollerhoj--- via dovecot <dovecot@dovecot.org> wrote:

Hi, I am currently about to port a legacy / custom authentication mechanism from 2.3 to 2.4.

Many things have changed in this area, and I have unfortunately not been able to find any valid documentation about this topic.

I have looked here: https://doc.dovecot.org/2.4.4/developers/design/auth_process.html but as far as I can see all the content is about the code design for dovecot 2.3, not 2.4.

Just to mention a few examples: There is not anymore a struct named mech_module, there is no such file as mech.h, and also the API for the central callback functions such as auth_new() and auth_initial() seems to have changed a lot (both arguments and return types).

Maybe a somewhat unfinished version of the documentation can be found on a specific branch?

Thank you, Kristoffer Møllerhøj.

I think it might be more useful if you tell what you are actually planning to implement?

Aki

Op 27-5-2026 om 15:01 schreef kristoffermollerhoj--- via dovecot:

Hi, I am currently about to port a legacy / custom authentication mechanism from 2.3 to 2.4.

Many things have changed in this area, and I have unfortunately not been able to find any valid documentation about this topic.

I did most of that. This very large overhaul of the server SASL code started around commit ef984daba219e9bdf08ad0c520d3e8f18728e7c0.

I have looked here:https://doc.dovecot.org/2.4.4/developers/design/auth_process.html but as far as I can see all the content is about the code design for dovecot 2.3, not 2.4.

Oh, I didn't know some programming details of the auth service and SASL mechanisms were also described in the docs. Yes, those should be updated then.

Just to mention a few examples: There is not anymore a struct named mech_module, there is no such file as mech.h, and also the API for the central callback functions such as auth_new() and auth_initial() seems to have changed a lot (both arguments and return types).

Much of the mech-*.c code is moved to lib-sasl to make the SASL server independently testable and fuzzible. If you are looking for an example server-side implementation of a SASL mechanism, you can find it in src/lib-sasl/sasl-server-mech-*.c. The standard GSSAPI mechanism is implemented there as well (conditional on autoconf parameters).

There is glue code in src/auth/auth-sasl*.c. This provides an interface between the generic callback API of lib-sasl/server and the request infrastructure and the passdb lookup services provided by the auth service. The more complex SASL mechanisms have some specific glue code there as well.

For testing, I usually also implement the client SASL mechanism (even if it would unlikely be used in any real use case). All client mechanisms are in src/lib-sasl/dsasl-client-mech-*.c. For GSSAPI mechanisms (GS2 is in the pipeline), I created a dummy gssapi library to make writing unit tests for GSSAPI mechanisms possible. You can see how that works in src/lib-sasl/test-sasl-authentication.c, in which client and server SASL implementations are tested against eachother. The dummy is src/lib-sasl/gssapi-dummy.c and krb5-dummy.c. Note that the client SASL API will change somewhat soon, but for a client mechanism the changes are quite minor.

Maybe a somewhat unfinished version of the documentation can be found on a specific branch?

Not yet.

Regards,

Stephan.

Op 27-5-2026 om 15:01 schreef kristoffermollerhoj--- via dovecot:

Hi, I am currently about to port a legacy / custom authentication mechanism from 2.3 to 2.4.

Many things have changed in this area, and I have unfortunately not been able to find any valid documentation about this topic.

I did most of that. This very large overhaul of the server SASL code started around commit ef984daba219e9bdf08ad0c520d3e8f18728e7c0.

I have looked here: [1]https://doc.dovecot.org/2.4.4/developers/design/auth_process.html but as far as I can see all the content is about the code design for dovecot 2.3, not 2.4.

Oh, I didn't know some programming details of the auth service and SASL mechanisms were also described in the docs. Yes, those should be updated then.

Just to mention a few examples: There is not anymore a struct named mech_module, there is no such file as mech.h, and also the API for the central callback functions such as auth_new() and auth_initial() seems to have changed a lot (both arguments and return types).

Much of the mech-*.c code is moved to lib-sasl to make the SASL server independently testable and fuzzible. If you are looking for an example server-side implementation of a SASL mechanism, you can find it in src/lib-sasl/sasl-server-mech-*.c. The standard GSSAPI mechanism is implemented there as well (conditional on autoconf parameters).

There is glue code in src/auth/auth-sasl*.c. This provides an interface between the generic callback API of lib-sasl/server and the request infrastructure and the passdb lookup services provided by the auth service. The more complex SASL mechanisms have some specific glue code there as well.

For testing, I usually also implement the client SASL mechanism (even if it would unlikely be used in any real use case). All client mechanisms are in src/lib-sasl/dsasl-client-mech-*.c. For GSSAPI mechanisms (GS2 is in the pipeline), I created a dummy gssapi library to make writing unit tests for GSSAPI mechanisms possible. You can see how that works in src/lib-sasl/test-sasl-authentication.c, in which client and server SASL implementations are tested against eachother. The dummy is src/lib-sasl/gssapi-dummy.c and krb5-dummy.c. Note that the client SASL API will change somewhat soon, but for a client mechanism the changes are quite minor.

Maybe a somewhat unfinished version of the documentation can be found on a specific branch?

Not yet.

Regards,

Stephan.

References

Visible links

1. https://doc.dovecot.org/2.4.4/developers/design/auth_process.html