Merge pull request #1098 from mgatny/add_gssapi_documentation

Add documentation for GSSAPI options.

doc/zmq_getsockopt.txt

@@ -164,6 +164,57 @@ Default value:: N/A
 Applicable socket types:: all
 
 
+ZMQ_GSSAPI_PLAINTEXT: Retrieve GSSAPI plaintext or encrypted status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Returns the 'ZMQ_GSSAPI_PLAINTEXT' option, if any, previously set on the
+socket.  A value of '1' means  that communications will be plaintext.  A value
+of '0' means communications will be encrypted.
+
+[horizontal]
+Option value type:: int
+Option value unit:: 0, 1
+Default value:: 0 (false)
+Applicable socket types:: all, when using TCP or IPC transports
+
+
+ZMQ_GSSAPI_PRINCIPAL: Retrieve the name of the GSSAPI principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_GSSAPI_PRINCIPAL' option shall retrieve the principal name set for the
+GSSAPI security mechanism. The returned value shall be a NULL-terminated string
+and MAY be empty. The returned size SHALL include the terminating null byte.
+
+[horizontal]
+Option value type:: NULL-terminated character string
+Option value unit:: N/A
+Default value:: null string
+Applicable socket types:: all, when using TCP or IPC transports
+
+
+ZMQ_GSSAPI_SERVER: Retrieve current GSSAPI server role
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Returns the 'ZMQ_GSSAPI_SERVER' option, if any, previously set on the socket.
+
+[horizontal]
+Option value type:: int
+Option value unit:: 0, 1
+Default value:: 0 (false)
+Applicable socket types:: all, when using TCP or IPC transports
+
+
+ZMQ_GSSAPI_SERVICE_PRINCIPAL: Retrieve the name of the GSSAPI service principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_GSSAPI_SERVICE_PRINCIPAL' option shall retrieve the principal name of
+the GSSAPI server to which a GSSAPI client socket intends to connect.  The
+returned value shall be a NULL-terminated string and MAY be empty. The returned
+size SHALL include the terminating null byte.
+
+[horizontal]
+Option value type:: NULL-terminated character string
+Option value unit:: N/A
+Default value:: null string
+Applicable socket types:: all, when using TCP or IPC transports
+
+
 ZMQ_HANDSHAKE_IVL: Retrieve maximum handshake interval
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_HANDSHAKE_IVL' option shall retrieve the maximum handshake interval
@@ -301,7 +352,7 @@ for the socket.
 
 [horizontal]
 Option value type:: int
-Option value unit:: ZMQ_NULL, ZMQ_PLAIN, or ZMQ_CURVE
+Option value unit:: ZMQ_NULL, ZMQ_PLAIN, ZMQ_CURVE, or ZMQ_GSSAPI
 Default value:: ZMQ_NULL
 Applicable socket types:: all, when using TCP or IPC transports
 

doc/zmq_gssapi.txt

@@ -0,0 +1,57 @@
+zmq_gssapi(7)
+============
+
+
+NAME
+----
+zmq_gssapi - secure authentication and confidentiality
+
+
+SYNOPSIS
+--------
+
+The GSSAPI mechanism defines a mechanism for secure authentication and
+confidentiality for communications between a client and a server using the
+Generic Security Service Application Program Interface (GSSAPI).  The GSSAPI
+mechanism can be used on both public and private networks.  GSSAPI itself is
+defined in IETF RFC-2743: <http://tools.ietf.org/html/rfc2743>. The ZeroMQ
+GSSAPI mechanism is defined by this document: <http://rfc.zeromq.org/spec:38>.
+
+
+CLIENT AND SERVER ROLES
+-----------------------
+A socket using GSSAPI can be either client or server, but not both.
+
+To become either a GSSAPI client or server, the application sets the
+ZMQ_GSSAPI_PRINCIPAL option to provide the socket with the name of the pricipal
+for whom GSSAPI credentials should be acquired.
+
+To become a GSSAPI server, the application addtionally sets the
+ZMQ_GSSAPI_SERVER option on the socket.
+
+To become a GSSAPI client, the application sets additionally sets the
+ZMQ_GSSAPI_SERVICE_PRINCIPAL option to the name of the principal of the server
+to which it intends to connect.  
+
+
+OPTIONAL ENCRYPTION
+-------------------
+By default, the GSSAPI mechanism will encrypt all communications between client
+and server.  If encryption is not desired (e.g. on private networks), the
+client and server applications can disable it by setting the
+ZMQ_GSSAPI_PLAINTEXT option.  Both the client and server must set this option
+to the same value.
+
+
+SEE ALSO
+--------
+linkzmq:zmq_setsockopt[3]
+linkzmq:zmq_null[7]
+linkzmq:zmq_curve[7]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

doc/zmq_setsockopt.txt

@@ -170,6 +170,55 @@ Default value:: NULL
 Applicable socket types:: all, when using TCP transport
 
 
+ZMQ_GSSAPI_PLAINTEXT: Disable GSSAPI encryption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines whether communications on the socket will encrypted, see
+linkzmq:zmq_gssapi[7]. A value of '1' means  that communications will be
+plaintext.  A value of '0' means communications will be encrypted.
+
+[horizontal]
+Option value type:: int
+Option value unit:: 0, 1
+Default value:: 0 (false)
+Applicable socket types:: all, when using TCP transport
+
+
+ZMQ_GSSAPI_PRINCIPAL: Set name of GSSAPI principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sets the name of the pricipal for whom GSSAPI credentials should be acquired.
+
+[horizontal]
+Option value type:: character string
+Option value unit:: N/A
+Default value:: not set
+Applicable socket types:: all, when using TCP transport
+
+
+ZMQ_GSSAPI_SERVER: Set GSSAPI server role
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Defines whether the socket will act as server for GSSAPI security, see
+linkzmq:zmq_gssapi[7]. A value of '1' means the socket will act as GSSAPI
+server. A value of '0' means the socket will act as GSSAPI client.
+
+[horizontal]
+Option value type:: int
+Option value unit:: 0, 1
+Default value:: 0 (false)
+Applicable socket types:: all, when using TCP transport
+
+
+ZMQ_GSSAPI_SERVICE_PRINCIPAL: Set name of GSSAPI service principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sets the name of the pricipal of the GSSAPI server to which a GSSAPI client
+intends to connect.
+
+[horizontal]
+Option value type:: character string
+Option value unit:: N/A
+Default value:: not set
+Applicable socket types:: all, when using TCP transport
+
+
 ZMQ_HANDSHAKE_IVL: Set maximum handshake interval
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_HANDSHAKE_IVL' option shall set the maximum handshake interval for