Versions Compared

Old Version 13

changes.mady.by.user Andrew Stitcher

Saved on

compared with

New Version Current

changes.mady.by.user Andrew Stitcher

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated to include newest work on code and many of the review comments

...

Conversely the SASL layer is very rudimentary and essentially punts to the application to handle the SASL protocol interchange. The SASL code does have some built in capability to use the ANONYMOUS mechanism and some code to simplify implementing the PLAIN SASL protocol exchange. Using the Proton-C 0.8 9 SASL codebase requires the application to directly read the SASL protocol bytes from the peer process them and send raw protocol bytes back to the peer.

...

Instead of the Proton-C 0.8 9 situation where the application has to directly read and write AMQP SASL frames using pn_sasl_recv(), pn_sasl_send() etc. the meat of the protocol interchange happens behind the scenes; the application only has to set up authentication parameters, and then allow Proton-C to handle SASL without application intervention.

At the client the parameters that can be set up include username/password (with pn_transportconnection_set_user/pn_connection_set_password() ), if necessary the SASL mechanisms used can be affected to either force SASL to use the ANONYMOUS mechanism set (pn_sasl_force_anonymous() ) or to exclude some mechanisms offered by the server (pn_sasl_excludeallowed_mechs() ).

By default the server will adapt to whatever layers the client uses to communicate. But the server application can specify that the connection must be encrypted or authenticated (using pn_transport_require_encryption() and pn_transport_require_auth() ). Also if required the server application can force the SASL layer to use the ANONYMOUS mechanism or to exclude some mechanisms that might be installed on the system (by using pn_sasl_force_anonymous() or pn_sasl_exclude_mechs() ). The location and name of the configuration file used by the SASL implementation can be changed by using the pn_sasl_config_name() and pn_sasl_config_path() APIs.

...

This function is a helper function that constructs and sends a SASL PLAIN mechanism frame. As directly sending the frames is no longer the responsibility of the application it is not needed, however it is broadly replaced with pn_transport_set_user_password() which allows the client to set the authentication username and password.

Functions Added

  • const char *void pn_sasl_getallow_userskip(pn_sasl_t *sasl, bool allow)

This

...

function is replaced with pn_transport_require_

...

auth(pn_

...

transport_t *transport, bool required) although the sense is reversed. By default anonymous connections are allowed. This is not really a change as previously there was no API guard against the SASL ANONYMOUS mechanism which is no better authenticated than not using SASL at all.

Functions Added

  • const char *pn_sasl_get_mechuser(pn_sasl_t *sasl)
    Return the selected SASL mechanism: The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.
  • void pn_sasl_exclude_mechs(pn_sasl_t *sasl, const char *mechs)
    Specify SASL mechanisms that are not to be considered for authentication. This can be used on either the client or the server to restrict the SASL mechanisms that may be used.
    Multiple  mechanisms to exclude are space separated in the string that is passed into this function.
  • This is usually used at the the server end to find the name of the authenticated user. On the client it will merely return whatever user was passed in to pn_transport_set_user_password().
    The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received. If the SASL layer was not negotiated then 0 is returned If the ANONYMOUS mechanism is used then the user will be "anonymous" Otherwise a string containing the authenticated user is returned.
  • const char *pn_sasl_get_mechvoid pn_sasl_force_anonymous(pn_sasl_t *sasl)
    This is used on either server or client to setup the SASL layer so that it will pre-emptively assume the ANONYMOUS mechanism and immediately send the appropriate frames without needing to do any actual authentication.
    However an important note is that if this is set on  a client and the connected server really does require authentication then the server will fail and disconnect the connection with no useful feedback to the application as the SASL layer state will already be assuming it has authenticated. Conversely if this is set on a server the client will only be offered the ANONYMOUS mechanism and if it does not support that mechanism it will disconnect.
  • void pn_sasl_config_name(pn_sasl_t *sasl, const char *name)
    This is used to construct the SASL configuration filename. In the current implementation ".conf" is added to the name and the file is looked for in the configuration directory.
    If not set it will default to "proton-server" for a sasl server and "proton-client" for a client.
  • void pn_sasl_config_path(pn_sasl_t *sasl, const char *path)
    This is used to tell SASL where to look for the configuration file. In the current implementation it can be a colon separated list of directories.
    The environment variable PN_SASL_CONFIG_PATH can also be used to set this path, but if both methods are used then this pn_sasl_config_path() will take precedence.
    If not set the underlying implementation default will be used.

Transport

Functions Added

  • Return the selected SASL mechanism: The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.
  • void pn_sasl_allowed_mechs(pn_sasl_t *sasl, const char *mechs)
    Specify SASL mechanisms that are to be considered for authentication. This can be used on either the client or the server to restrict the SASL mechanisms that may be used.
    Multiple  allowed mechanisms are space separated in the string that is passed into this function.
    As a special case on the client if the only mechanism allowed is "ANONYMOUS" then this will activate a mode ("Pipelined mode") where the client will assume that the server will accept anonymous SASL connections and will not wait for the SASL protocol interchange, but will just send all the relevant SASL frames unconditionally.
    However an important note is that if this is set on  a client and the connected server really does require authentication then the server will fail and disconnect the connection with no useful feedback to the application as the SASL layer state will already be assuming it has authenticated.
    There is no similar server pipelined mode as it is not possible together with detecting and adapting to whatever AMQP protocol layers the connecting client is using.
  • void pn_sasl_config_name(pn_sasl_t *sasl, const char *name)
    This is used to construct the SASL configuration filename. In the current implementation ".conf" is added to the name and the file is looked for in the configuration directory.
    If not set it will default to "proton-server" for a sasl server and "proton-client" for a client.
  • void pn_sasl_config_path(pn_sasl_t *sasl, const char *path)
    This is used to tell SASL where to look for the configuration file. In the current implementation it can be a colon separated list of directories.
    The environment variable PN_SASL_CONFIG_PATH can also be used to set this path, but if both methods are used then this pn_sasl_config_path() will take precedence.
    If not set the underlying implementation default will be used.

Transport

Functions Added

  • const char *pn_transport_get_user(pn_transport_t *transport)

    This is usually used at the the server end to find the name of the authenticated user, On the client it will merely return whatever user was passed in to pn_connection_set_user().

    The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.

    If a the user is anonymous (either no SASL layer is negotiated or the SASL ANONYMOUS mechanism is used) then the user will be "anonymous", otherwise a string containing the user is returned.

  • void pn_transport_require_auth(pn_transport_t *transport, bool required)

    Set whether a non authenticated transport connection is allowed.

    There are several ways within the AMQP protocol suite to get unauthenticated connections:

    • Use no SASL layer (with either no SSL or SSL without client certificates)

    • Use an SASL layer but the ANONYMOUS mechanism

The default if this option is not set is to allow unauthenticated connections.

  • bool pn_transport_is_authenticated(pn_transport_t *transport)
    Returns whether the transport is authenticated.
    This property may not be stable until after the PN_CONNECTION_REMOTE_OPEN event is received.
  • void pn_transport_require_encryptionvoid pn_transport_set_user_password(pn_transport_t *transport, const char *user, const char* passwordbool required)
    Set the authentication username and password for a client transportwhether a non encrypted transport connection is allowed.
    There are several ways within the AMQP protocol suite to get encrypted connections:
    • Use SSL
    • Use SASL with a mechanism that supports security layers
    The default if this option is not set is to allow unencrypted connections.
  • bool pn_transport_is_encrypted

    If not set then no authentication will be negotiated unless the client sasl layer is explicitly created (this would be for something like Kerberos where the credentials are implicit in the environment, or to explicitly use the ANONYMOUS SASL mechanism).

    const char *pn_transport_get_user(pn_transport_t *transport)

    This is usually used at the the server end to find the name of the authenticated user, On the client it will merely return whatever user was passed in to pn_transport_set_user_password().

    The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.

    If a the user is anonymous (either no SASL layer is negotiated or the SASL ANONYMOUS mechanism is used) then the user will be "anonymous", otherwise a string containing the user is returned.

  • void pn_transport_set_remote_hostname(pn_transport_t *transport, const char* fqdn)
    Used on the client to set the fully qualified domain name of the server we are connecting to. This is used to authenticate that we are indeed connected to this host if the SASL mechanism supports it or if we are using SSL.

  • void pn_transport_require_auth(pn_transport_t *transport, bool required)

    Set whether a non authenticated transport connection is allowed.

    There are several ways within the AMQP protocol suite to get unauthenticated connections:

    • Use no SASL layer (with either no SSL or SSL without client certificates)

    • Use an SASL layer but the ANONYMOUS mechanism

The default if this option is not set is to allow unauthenticated connections.

 

  • void pn_transport_require_encryption(pn_transport_t *transport, bool required)
    Set whether a non encrypted transport connection is allowed.
    There are several ways within the AMQP protocol suite to get encrypted connections:
    • Use SSL
    • Use SASL with a mechanism that supports security layers
    The default if this option is not set is to allow unencrypted connections.

 

  • Returns whether the transport is encrypted.
    This property may not be stable until after the PN_CONNECTION_REMOTE_OPEN event is received.

Connection

Functions Added

  • void pn_connection_set_user(pn_connection_t *connection, const char *user)

    Set the authentication username for a client transport

    If not set then no authentication will be negotiated unless the client sasl layer is explicitly created (this would be for something like Kerberos where the credentials are implicit in the environment, or to explicitly use the ANONYMOUS SASL mechanism).

  • void pn_connection_set_password(pn_connection_t *connection, const char* password)

    Set the authentication password for a client transport. Note that there is no way to retrieve the password from the API as them implementation is supposed to use it and then zero it out of memory as soon as it is finished with it.

  • const char *pn_connection_get_user(pn_connection_t *connection)
    Get the authentication username for a client transport.

New Events

  • PN_TRANSPORT_AUTHENTICATED
    This event is sent when a server successfully authenticates a client connection (or when it accepts an unauthenticated connection that does not need to be authenticated).On the client it is sent when the client successfully authenticates to the server. If encryption is configured for the connection, it will be also be established by the point at which this event is received. If the authentication or encryption handshake is unsuccessful then both server and client applications will receive a PN_TRANSPORT_ERROR event.

...

A substantial portion of this work is complete and ready to be included for the 0.9 10 Proton release (subject to API and code review of course). You can follow along with my changes by looking in my Github Proton repository:

https://github.com/astitcher/qpid-proton/commits/saslPROTON-work334

The items of work that will remain to be completed for 0.10 are:

  •  Tie the SSL code into the more unified transport API:
    The current code base has no changes in the SSL code for these changes.
  •  Consequently, pn_transport_require_encryption() is not implemented.
  •  There needs to be a way to inject a byte stream that already comes from SSL without autodetection
    as this is how the qpidd broker will be able to use SSL with this SASL implementation.
  •  Using SASL for encryption is currently not implemented.
  •  Example code. 
  •  An implementation of the PLAIN SASL mechanism that can be used when Cyrus SASL is not available.
    This will involve some application interaction as the application will have to authenticate the user, password combination itself and signal to proton whether the incoming connection is authenticated or not.
    The likely mechanism will be to send a transport event and for the application to use pn_sasl_done() to signal the outcome.