proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Typedefs | Enumerations | Functions
sasl.h File Reference

API for the SASL Secure Transport Layer. More...

#include <sys/types.h>
#include <stdbool.h>
#include <proton/engine.h>

Go to the source code of this file.

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_sasl_tpn_sasl (pn_transport_t *transport)
 Construct an Authentication and Security Layer object.
 
pn_sasl_state_t pn_sasl_state (pn_sasl_t *sasl)
 Access the current state of the layer.
 
void pn_sasl_mechanisms (pn_sasl_t *sasl, const char *mechanisms)
 Set the acceptable SASL mechanisms for the layer.
 
const char * pn_sasl_remote_mechanisms (pn_sasl_t *sasl)
 Retrieve the list of SASL mechanisms provided by the remote.
 
void pn_sasl_client (pn_sasl_t *sasl)
 Configure the SASL layer to act as a SASL client.
 
void pn_sasl_server (pn_sasl_t *sasl)
 Configure the SASL layer to act as a server.
 
void pn_sasl_plain (pn_sasl_t *sasl, const char *username, const char *password)
 Configure the SASL layer to use the "PLAIN" mechanism.
 
size_t pn_sasl_pending (pn_sasl_t *sasl)
 Determine the size of the bytes available via pn_sasl_recv().
 
ssize_t pn_sasl_recv (pn_sasl_t *sasl, char *bytes, size_t size)
 Read challenge/response data sent from the peer.
 
ssize_t pn_sasl_send (pn_sasl_t *sasl, const char *bytes, size_t size)
 Send challenge or response data to the peer.
 
void pn_sasl_done (pn_sasl_t *sasl, pn_sasl_outcome_t outcome)
 Set the outcome of SASL negotiation.
 
pn_sasl_outcome_t pn_sasl_outcome (pn_sasl_t *sasl)
 Retrieve the outcome of SASL negotiation.
 

Detailed Description

API for the SASL Secure Transport Layer.

The SASL layer is responsible for establishing an authenticated and/or encrypted tunnel over which AMQP frames are passed between peers. The peer acting as the SASL Client must provide authentication credentials. The peer acting as the SASL Server must provide authentication against the received credentials.

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_sasl_t* pn_sasl ( pn_transport_t transport)

Construct an Authentication and Security Layer object.

Returns
a new SASL object representing the layer.
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
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:
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_sasl_outcome_t pn_sasl_outcome ( pn_sasl_t sasl)

Retrieve the outcome of SASL negotiation.

Todo:
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.
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
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.
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)
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
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_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.