proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Typedefs | Enumerations | Functions
SASL
Transport

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
}
 The result of the SASL negotiation. More...
enum  pn_sasl_state_t {
  PN_SASL_CONF, 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.
PN_EXTERN pn_sasl_state_t pn_sasl_state (pn_sasl_t *sasl)
 Access the current state of the layer.
PN_EXTERN void pn_sasl_mechanisms (pn_sasl_t *sasl, const char *mechanisms)
 Set the acceptable SASL mechanisms for the layer.
PN_EXTERN const char * pn_sasl_remote_mechanisms (pn_sasl_t *sasl)
 Retrieve the list of SASL mechanisms provided by the remote.
PN_EXTERN void pn_sasl_client (pn_sasl_t *sasl)
 Configure the SASL layer to act as a SASL client.
PN_EXTERN void pn_sasl_server (pn_sasl_t *sasl)
 Configure the SASL layer to act as a server.
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.
PN_EXTERN size_t pn_sasl_pending (pn_sasl_t *sasl)
 Determine the size of the bytes available via pn_sasl_recv().
PN_EXTERN ssize_t pn_sasl_recv (pn_sasl_t *sasl, char *bytes, size_t size)
 Read challenge/response data sent from the peer.
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.
PN_EXTERN void pn_sasl_done (pn_sasl_t *sasl, pn_sasl_outcome_t outcome)
 Set the outcome of SASL negotiation.
PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome (pn_sasl_t *sasl)
 Retrieve the outcome of SASL negotiation.

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

The state of the SASL negotiation process.

Enumerator:
PN_SASL_CONF 
PN_SASL_IDLE 

Pending configuration by application.

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_client ( pn_sasl_t sasl)

Configure the SASL layer to act as a SASL client.

The role of client is similar to a TCP client - the peer requesting the connection.

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)

Configure the SASL layer to act as a server.

The role of server is similar to a TCP server - the peer accepting the connection.

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.