proton  0
Typedefs | Enumerations | Functions

Typedefs

typedef struct pn_sasl_t pn_sasl_t
 

Enumerations

enum  pn_sasl_outcome_t {
  PN_SASL_NONE =-1, PN_SASL_OK =0, PN_SASL_AUTH =1, PN_SASL_SYS =2,
  PN_SASL_PERM =3, PN_SASL_TEMP =4, PN_SASL_SKIPPED =5
}
 The result of the SASL negotiation. More...
 
enum  pn_sasl_state_t { PN_SASL_IDLE, PN_SASL_STEP, PN_SASL_PASS, PN_SASL_FAIL }
 The state of the SASL negotiation process. More...
 

Functions

PN_EXTERN pn_sasl_tpn_sasl (pn_transport_t *transport)
 Construct an Authentication and Security Layer object. More...
 
PN_EXTERN pn_sasl_state_t pn_sasl_state (pn_sasl_t *sasl)
 Access the current state of the layer. More...
 
PN_EXTERN void pn_sasl_mechanisms (pn_sasl_t *sasl, const char *mechanisms)
 Set the acceptable SASL mechanisms for the layer. More...
 
PN_EXTERN const char * pn_sasl_remote_mechanisms (pn_sasl_t *sasl)
 Retrieve the list of SASL mechanisms provided by the remote. More...
 
PN_EXTERN void pn_sasl_client (pn_sasl_t *sasl)
 
PN_EXTERN void pn_sasl_server (pn_sasl_t *sasl)
 
PN_EXTERN void pn_sasl_allow_skip (pn_sasl_t *sasl, bool allow)
 Configure a SASL server layer to permit the client to skip the SASL exchange. More...
 
PN_EXTERN void pn_sasl_plain (pn_sasl_t *sasl, const char *username, const char *password)
 Configure the SASL layer to use the "PLAIN" mechanism. More...
 
PN_EXTERN size_t pn_sasl_pending (pn_sasl_t *sasl)
 Determine the size of the bytes available via pn_sasl_recv(). More...
 
PN_EXTERN ssize_t pn_sasl_recv (pn_sasl_t *sasl, char *bytes, size_t size)
 Read challenge/response data sent from the peer. More...
 
PN_EXTERN ssize_t pn_sasl_send (pn_sasl_t *sasl, const char *bytes, size_t size)
 Send challenge or response data to the peer. More...
 
PN_EXTERN void pn_sasl_done (pn_sasl_t *sasl, pn_sasl_outcome_t outcome)
 Set the outcome of SASL negotiation. More...
 
PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome (pn_sasl_t *sasl)
 Retrieve the outcome of SASL negotiation. More...
 

Detailed Description

Typedef Documentation

typedef struct pn_sasl_t pn_sasl_t

Enumeration Type Documentation

The result of the SASL negotiation.

Enumerator
PN_SASL_NONE 
PN_SASL_OK 

negotiation not completed

PN_SASL_AUTH 

authentication succeeded

PN_SASL_SYS 

failed due to bad credentials

PN_SASL_PERM 

failed due to a system error

PN_SASL_TEMP 

failed due to unrecoverable error

PN_SASL_SKIPPED 

failed due to transient error

The state of the SASL negotiation process.

Enumerator
PN_SASL_IDLE 
PN_SASL_STEP 

Pending SASL Init.

PN_SASL_PASS 

negotiation in progress

PN_SASL_FAIL 

negotiation completed successfully

negotiation failed

Function Documentation

PN_EXTERN pn_sasl_t* pn_sasl ( pn_transport_t transport)

Construct an Authentication and Security Layer object.

Returns
a new SASL object representing the layer.
PN_EXTERN void pn_sasl_allow_skip ( pn_sasl_t sasl,
bool  allow 
)

Configure a SASL server layer to permit the client to skip the SASL exchange.

If the peer client skips the SASL exchange (i.e. goes right to the AMQP header) this server layer will succeed and result in the outcome of PN_SASL_SKIPPED. The default behavior is to fail and close the connection if the client skips SASL.

Parameters
[in]saslthe SASL layer to configure
[in]allowtrue -> allow skip; false -> forbid skip
PN_EXTERN void pn_sasl_client ( pn_sasl_t sasl)
Deprecated:
Configure the SASL layer to act as a SASL client.

This is now unnecessary, and performs no function. The server/clientness of the sasl layer is determined from the role of the transport that is used to create it. The API is retained here so as not to break existing code.

Parameters
[in]saslthe SASL layer to configure as a client
PN_EXTERN void pn_sasl_done ( pn_sasl_t sasl,
pn_sasl_outcome_t  outcome 
)

Set the outcome of SASL negotiation.

Used by the server to set the result of the negotiation process.

Todo:
PN_EXTERN void pn_sasl_mechanisms ( pn_sasl_t sasl,
const char *  mechanisms 
)

Set the acceptable SASL mechanisms for the layer.

Parameters
[in]saslthe layer to update
[in]mechanismsa list of acceptable SASL mechanisms, separated by space
PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome ( pn_sasl_t sasl)

Retrieve the outcome of SASL negotiation.

Todo:
PN_EXTERN size_t pn_sasl_pending ( pn_sasl_t sasl)

Determine the size of the bytes available via pn_sasl_recv().

Returns the size in bytes available via pn_sasl_recv().

Parameters
[in]saslthe SASL layer.
Returns
The number of bytes available, zero if no available data.
PN_EXTERN void pn_sasl_plain ( pn_sasl_t sasl,
const char *  username,
const char *  password 
)

Configure the SASL layer to use the "PLAIN" mechanism.

A utility function to configure a simple client SASL layer using PLAIN authentication.

Parameters
[in]saslthe layer to configure.
[in]usernamecredential for the PLAIN authentication mechanism
[in]passwordcredential for the PLAIN authentication mechanism
PN_EXTERN ssize_t pn_sasl_recv ( pn_sasl_t sasl,
char *  bytes,
size_t  size 
)

Read challenge/response data sent from the peer.

Use pn_sasl_pending to determine the size of the data.

Parameters
[in]saslthe layer to read from.
[out]byteswritten with up to size bytes of inbound data.
[in]sizemaximum number of bytes that bytes can accept.
Returns
The number of bytes written to bytes, or an error code if < 0.
PN_EXTERN const char* pn_sasl_remote_mechanisms ( pn_sasl_t sasl)

Retrieve the list of SASL mechanisms provided by the remote.

Parameters
[in]saslthe SASL layer.
Returns
a string containing a list of the SASL mechanisms advertised by the remote (separated by spaces)
PN_EXTERN ssize_t pn_sasl_send ( pn_sasl_t sasl,
const char *  bytes,
size_t  size 
)

Send challenge or response data to the peer.

Parameters
[in]saslThe SASL layer.
[in]bytesThe challenge/response data.
[in]sizeThe number of data octets in bytes.
Returns
The number of octets read from bytes, or an error code if < 0
PN_EXTERN void pn_sasl_server ( pn_sasl_t sasl)
Deprecated:
Configure the SASL layer to act as a server.

This is now only necessary for backwards compatibility if creating a server pn_sasl_t from a pn_transport_t which was created implicitly as a client by pn_transport().

Parameters
[in]saslthe SASL layer to configure as a server
PN_EXTERN pn_sasl_state_t pn_sasl_state ( pn_sasl_t sasl)

Access the current state of the layer.

Parameters
[in]saslthe layer to retrieve the state from.
Returns
The state of the sasl layer.