/builddir/build/BUILD/qpid-proton-0.4/proton-c/include/proton/sasl.h File Reference

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

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

Go to the source code of this file.

Defines

#define PROTON_SASL_H   1

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

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.


Define Documentation

#define PROTON_SASL_H   1

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] sasl the 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] sasl the layer to update
[in] mechanisms a 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] sasl the 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] sasl the layer to configure.
[in] username credential for the PLAIN authentication mechanism
[in] password credential 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] sasl the layer to read from.
[out] bytes written with up to size bytes of inbound data.
[in] size maximum 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] sasl the 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] sasl The SASL layer.
[in] bytes The challenge/response data.
[in] size The 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] sasl the 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] sasl the layer to retrieve the state from.
Returns:
The state of the sasl layer.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on 13 Mar 2013 for proton by  doxygen 1.6.1