C AMQP Protocol Engine API  0.4
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
sasl.h File Reference
#include <proton/import_export.h>
#include <sys/types.h>
#include <stdbool.h>
#include <proton/engine.h>
Include dependency graph for sasl.h:
This graph shows which files directly or indirectly include this file:

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
}
 
enum  pn_sasl_state_t {
  PN_SASL_CONF, PN_SASL_IDLE, PN_SASL_STEP, PN_SASL_PASS,
  PN_SASL_FAIL
}
 

Functions

PN_EXTERN pn_sasl_tpn_sasl (pn_transport_t *transport)
 
PN_EXTERN pn_sasl_state_t pn_sasl_state (pn_sasl_t *sasl)
 
PN_EXTERN void pn_sasl_mechanisms (pn_sasl_t *sasl, const char *mechanisms)
 
PN_EXTERN const char * pn_sasl_remote_mechanisms (pn_sasl_t *sasl)
 
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_plain (pn_sasl_t *sasl, const char *username, const char *password)
 
PN_EXTERN size_t pn_sasl_pending (pn_sasl_t *sasl)
 
PN_EXTERN ssize_t pn_sasl_recv (pn_sasl_t *sasl, char *bytes, size_t size)
 
PN_EXTERN ssize_t pn_sasl_send (pn_sasl_t *sasl, const char *bytes, size_t size)
 
PN_EXTERN void pn_sasl_done (pn_sasl_t *sasl, pn_sasl_outcome_t outcome)
 
PN_EXTERN pn_sasl_outcome_t pn_sasl_outcome (pn_sasl_t *sasl)
 

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_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.