From 0a4123fd91ec40222a880788b70e0075a018105f Mon Sep 17 00:00:00 2001 From: Mike Gatny Date: Thu, 19 Jun 2014 23:57:48 -0400 Subject: [PATCH] Add documentation for GSSAPI options. --- doc/zmq_getsockopt.txt | 53 ++++++++++++++++++++++++++++++++++++++- doc/zmq_gssapi.txt | 57 ++++++++++++++++++++++++++++++++++++++++++ doc/zmq_setsockopt.txt | 49 ++++++++++++++++++++++++++++++++++++ 3 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 doc/zmq_gssapi.txt diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 57c0673a..6961cc7a 100644 --- a/doc/zmq_getsockopt.txt +++ b/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 diff --git a/doc/zmq_gssapi.txt b/doc/zmq_gssapi.txt new file mode 100644 index 00000000..82e90ca1 --- /dev/null +++ b/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: . The ZeroMQ +GSSAPI mechanism is defined by this document: . + + +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 . diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 2876dfcb..d3214c96 100644 --- a/doc/zmq_setsockopt.txt +++ b/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