cztop 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d264ee06de06bac407c3d7e06c7e70c140ccb22
-  data.tar.gz: 078a0a7b26a80c8d43e94e5d606acc3772599369
+  metadata.gz: d8c82a0f35f091e2d464beabb00adaf5ad0f0b35
+  data.tar.gz: aa92e0a78ca5ca7dcc00441d16e004085024a60a
 SHA512:
-  metadata.gz: b3baaa8210899a4c87e39731bc9273e77745758057bebc1e01abad0872f3b0c088466a195f8c1ee92401f98571fbb8c1805c9f8e2c017d3abeadc2a88fe54d92
-  data.tar.gz: 39179480f025cc1d7c36cf5cd394f8dfb4be3a0a3d178463a136fc2e8d287ff696f37ad39a2423cdb35681a7d171a671a9bc9b5b751f3e11667182f892a7cd75
+  metadata.gz: 792e7990a6451bd7f02b638e02c782c95c9d54cbc009aa371de33234ed84b06d88737f830406363e96b44425f643c051948a57aa81719e9059627c48252a308b
+  data.tar.gz: 1af4724a36e2959e1e94f552c9289e51f98aa5565df5bb6c14cc8a99130401fd4713fa3f75090e2dcdc9cc466521d7e2a51bea756df20d34a10767767d3822d8

data/CHANGES.md

@@ -1,3 +1,9 @@
+0.9.0 (10/20/2016)
+-----
+* add CertStore interface to zcertstore
+* add ability to pass an existing CertStore to Authenticator
+* add ZAP Request/Response classes (useful for testing)
+
 0.8.0 (09/25/2016)
 -----
 * update dependency of czmq-ffi-gen to "~> 0.10.0"

data/README.md

@@ -97,6 +97,7 @@ Here's an overview of the core classes:
   * [Z85](http://www.rubydoc.info/gems/cztop/CZTop/Z85)
     * [Padded](http://www.rubydoc.info/gems/cztop/CZTop/Z85/Padded) < Z85
     * [Pipe](http://www.rubydoc.info/gems/cztop/CZTop/Z85/Pipe)
+  * [ZAP](http://www.rubydoc.info/gems/cztop/CZTop/ZAP)
 
 More information in the [API documentation](http://www.rubydoc.info/github/paddor/cztop).
 

data/lib/cztop/authenticator.rb

@@ -18,8 +18,18 @@ module CZTop
     # This installs authentication on all {Socket}s and {Actor}s. Until you
     # add policies, all incoming _NULL_ connections are allowed,
     # and all _PLAIN_ and _CURVE_ connections are denied.
-    def initialize
-      @actor = Actor.new(ZAUTH_FPTR)
+    #
+    # @param cert_store [CertStore] a custom certificate store
+    # @note If you pass a {CertStore}, its native object will be owned by the
+    #   actor (and freed by it when the actor terminates). That means you MUST
+    #   disale auto free in the CertStore object.
+    def initialize(cert_store = nil)
+      if cert_store
+        raise ArgumentError unless cert_store.is_a?(CertStore)
+        cert_store = cert_store.ffi_delegate
+        cert_store.__undef_finalizer # native object is now owned by zauth() actor
+      end
+      @actor = Actor.new(ZAUTH_FPTR, cert_store)
     end
 
     # @return [Actor] the actor behind this authenticator
@@ -72,17 +82,17 @@ module CZTop
       @actor.wait
     end
 
-    ANY_CERTIFICATE = "*"
+    # used to allow any CURVE client
+    ALLOW_ANY = "*"
 
     # Configure CURVE authentication, using a directory that holds all public
     # client certificates, i.e. their public keys. The certificates must have been
     # created using {Certificate#save}/{Certificate#save_public}. You can add
     # and remove certificates in that directory at any time.
     #
-    # @param directory [String] the directory to take the keys from (the
-    #   default value will allow any certificate)
+    # @param directory [String] the directory to take the keys from
     # @return [void]
-    def curve(directory = ANY_CERTIFICATE)
+    def curve(directory = ALLOW_ANY)
       @actor << ["CURVE", directory]
       @actor.wait
     end

data/lib/cztop/cert_store.rb

@@ -0,0 +1,42 @@
+module CZTop
+
+  # A store for CURVE security certificates, either backed by files on disk or
+  # in-memory.
+  #
+  # @see http://api.zeromq.org/czmq3-0:zcertstore
+  class CertStore
+    include ::CZMQ::FFI
+    include HasFFIDelegate
+    extend CZTop::HasFFIDelegate::ClassMethods
+
+    # Initializes a new certificate store.
+    #
+    # @param location [String, #to_s, nil] location the path to the
+    #   directories to load certificates from, or nil if no certificates need
+    #   to be loaded from the disk
+    def initialize(location = nil)
+      location = location.to_s if location
+      attach_ffi_delegate(Zcertstore.new(location))
+    end
+
+    # Looks up a certificate in the store by its public key.
+    #
+    # @param pubkey [String] the public key in question, in Z85 format
+    # @return [Certificate] the matching certificate, if found
+    # @return [nil] if no matching certificate was found
+    def lookup(pubkey)
+      ptr = ffi_delegate.lookup(pubkey)
+      return nil if ptr.null?
+      Certificate.from_ffi_delegate(ptr)
+    end
+
+    # Inserts a new certificate into the store.
+    #
+    # @param cert [Certificate] the certificate to insert
+    # @return [void]
+    def insert(cert)
+      raise ArgumentError unless cert.is_a?(Certificate)
+      ffi_delegate.insert(cert.ffi_delegate)
+    end
+  end
+end

data/lib/cztop/version.rb

@@ -1,3 +1,3 @@
 module CZTop
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/cztop/zap.rb

@@ -0,0 +1,234 @@
+module CZTop
+  # This module provides two classes useful when implementing your own ZAP
+  # authentication handler or when directly communicating with one. Within
+  # CZTop, it's merely used for testing.
+  #
+  # Some of the features:
+  # * useful for both sides of the ZAP communication, i.e. useful for testing
+  # * security mechanism agnostic
+  # * protocol errors, version mismatches, and internal errors as exceptions
+  # * useful to implement your own ZAP handler
+  #
+  # @note This is not needed to be able to use {CZTop::Authenticator}!
+  # @see https://rfc.zeromq.org/spec:27/ZAP
+  module ZAP
+    # the endpoint a ZAP authenticator has bound to
+    ENDPOINT = "inproc://zeromq.zap.01"
+
+    # the ZAP version supported by this code
+    VERSION = "1.0"
+
+    # superclass for ZAP errors
+    class Error < StandardError
+    end
+
+    # used when the response contains an unsupported version
+    class VersionMismatch < Error
+    end
+
+    # security mechanisms mentioned in ZeroMQ RFC 27.
+    module Mechanisms
+      NULL = "NULL"
+      PLAIN = "PLAIN"
+      CURVE = "CURVE"
+    end
+
+    # Represents a ZAP request.
+    class Request
+      # Crafts a new {Request} from a message.
+      #
+      # @param msg [CZTop::message] the message
+      # @return [Request] the request
+      # @raise [VersionMismatch] if the message contains an unsupported version
+      def self.from_message(msg)
+          version,       # The version frame, which SHALL contain the three octets "1.0".
+          request_id,    # The request id, which MAY contain an opaque binary blob.
+          domain,        # The domain, which SHALL contain a string.
+          address,       # The address, the origin network IP address.
+          identity,      # The identity, the connection Identity, if any.
+          mechanism,     # The mechanism, which SHALL contain a string.
+          *credentials = # The credentials, which SHALL be zero or more opaque frames.
+            msg.to_a
+
+        raise VersionMismatch if version != VERSION
+
+        new(domain, credentials, mechanism: mechanism).tap do |r|
+          r.version = version
+          r.request_id = request_id
+          r.address = address
+          r.identity = identity
+        end
+      end
+
+      # @return [String] ZAP version
+      attr_accessor :version
+
+      # @return [String, #to_s] the authentication domain
+      attr_accessor :domain
+
+      # @return [Array<String, #to_s>] the credentials, 0 or more
+      attr_accessor :credentials
+
+      # @return [String, #to_s]
+      attr_accessor :request_id
+
+      # @return [String, #to_s]
+      attr_accessor :address
+
+      # @return [String, #to_s] the connection identity
+      attr_accessor :identity
+
+      # @see Mechanisms
+      # @return [String, #to_s] the security mechanism to be used
+      attr_accessor :mechanism
+
+      # Initializes a new ZAP request. The security mechanism is set to
+      # CURVE (can be changed later).
+      #
+      # @param domain [String] the domain within to authenticate
+      # @param credentials [Array<String>] the credentials of the user,
+      #   depending on the security mechanism used
+      def initialize(domain, credentials = [], mechanism: Mechanisms::CURVE)
+        @domain = domain
+        @credentials = credentials
+        @mechanism = mechanism
+        @version = VERSION
+      end
+
+      # Creates a sendable message from this {Request}.
+      # @return [CZTop::Message} this request packed into a message
+      def to_msg
+        fields = [ @version, @request_id, @domain, @address,
+          @identity, @mechanism, @credentials].flatten.map(&:to_s)
+
+        CZTop::Message.new(fields)
+      end
+    end
+
+    # Represents a ZAP response.
+    class Response
+
+      # used to indicate a temporary error
+      class TemporaryError < Error
+      end
+
+      # used to indicate an internal error of the authenticator
+      class InternalError < Error
+      end
+
+      # Status codes of ZAP responses.
+      module StatusCodes
+        SUCCESS = "200"
+        TEMPORARY_ERROR = "300"
+        AUTHENTICATION_FAILURE = "400"
+        INTERNAL_ERROR = "500"
+
+        ALL = [
+          SUCCESS,
+          TEMPORARY_ERROR,
+          AUTHENTICATION_FAILURE,
+          INTERNAL_ERROR
+        ]
+      end
+
+      include StatusCodes
+
+      # Crafts a new {Response} from a message.
+      #
+      # @param msg [CZTop::message] the message
+      # @return [Response] the response
+      # @raise [VersionMismatch] if the message contains an unsupported version
+      # @raise [TemporaryError] if the status code indicates a temporary error
+      # @raise [InternalError] if the status code indicates an internal error,
+      #   or the status code is invalid
+      def self.from_message(msg)
+        version,     # The version frame, which SHALL contain the three octets "1.0".
+        request_id,  # The request id, which MAY contain an opaque binary blob.
+        status_code, # The status code, which SHALL contain a string.
+        status_text, # The status text, which MAY contain a string.
+        user_id,     # The user id, which SHALL contain a string.
+        meta_data =  # The meta data, which MAY contain a blob.
+          msg.to_a
+
+        raise VersionMismatch if version != VERSION
+
+        case status_code
+        when SUCCESS, AUTHENTICATION_FAILURE
+          # valid codes, nothing to do
+        when TEMPORARY_ERROR
+          raise TemporaryError, status_text
+        when INTERNAL_ERROR
+          raise InternalError, status_text
+        else
+          raise InternalError, "invalid status code"
+        end
+
+        new(status_code).tap do |r|
+          r.version = version
+          r.request_id = request_id
+          r.status_code = status_code
+          r.status_text = status_text
+          r.user_id = user_id
+          r.meta_data = meta_data
+        end
+      end
+
+      # @return [String] ZAP version
+      attr_accessor :version
+
+      # @return [String] the original request ID
+      attr_accessor :request_id
+
+      # @return [String] status code
+      # @see StatusCodes
+      attr_accessor :status_code
+
+      # @return [String] status explanation
+      attr_accessor :status_text
+
+      # @return [String] meta data in ZMTP 3.0 format
+      attr_writer :meta_data
+
+      # @return [String] the user ID
+      attr_writer :user_id
+
+      # Initializes a new response.
+      #
+      # @param status_code [String, #to_s] ZAP status code
+      def initialize(status_code)
+        @status_code = status_code.to_s
+        raise ArgumentError unless ALL.include?(@status_code)
+        @version = VERSION
+      end
+
+      # @return [Boolean] whether the authentication was successful
+      def success?
+        @status_code == SUCCESS
+      end
+
+      # Returns the user ID, if authentication was successful.
+      # @return [String] the user ID of the authenticated user
+      # @return [nil] if authentication was unsuccessful
+      def user_id
+        return nil unless success?
+        @user_id
+      end
+
+      # Returns the meta data, if authentication was successful.
+      # @return [String] the meta data for the authenticated user
+      # @return [nil] if authentication was unsuccessful
+      def meta_data
+        return nil unless success?
+        @meta_data
+      end
+
+      # Creates a sendable message from this {Response}.
+      # @return [CZTop::Message} this request packed into a message
+      def to_msg
+        fields = [@version, @request_id, @status_code,
+                  @status_text, @user_id, @meta_data].map(&:to_s)
+        CZTop::Message.new(fields)
+      end
+    end
+  end
+end

data/lib/cztop/zsock_options.rb

@@ -64,7 +64,7 @@ module CZTop
 
       # @!endgroup
 
-      # @!group (CURVE) Security
+      # @!group Security Mechanisms
 
       # @return [Boolean] whether this zocket is a CURVE server
       def CURVE_server?() Zsock.curve_server(@zocket) > 0 end

data/lib/cztop.rb

@@ -16,6 +16,7 @@ require_relative 'cztop/actor'
 require_relative 'cztop/authenticator'
 require_relative 'cztop/beacon'
 require_relative 'cztop/certificate'
+require_relative 'cztop/cert_store'
 require_relative 'cztop/config'
 require_relative 'cztop/frame'
 require_relative 'cztop/message'
@@ -33,6 +34,7 @@ require_relative 'cztop/message/frames'
 require_relative 'cztop/socket/types'
 require_relative 'cztop/z85/padded'
 require_relative 'cztop/z85/pipe'
+require_relative 'cztop/zap'
 
 
 # make Ctrl-C work in case a low-level call hangs

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cztop
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Patrik Wenger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-25 00:00:00.000000000 Z
+date: 2016-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: czmq-ffi-gen
@@ -251,6 +251,7 @@ files:
 - lib/cztop/actor.rb
 - lib/cztop/authenticator.rb
 - lib/cztop/beacon.rb
+- lib/cztop/cert_store.rb
 - lib/cztop/certificate.rb
 - lib/cztop/config.rb
 - lib/cztop/config/comments.rb
@@ -271,6 +272,7 @@ files:
 - lib/cztop/z85.rb
 - lib/cztop/z85/padded.rb
 - lib/cztop/z85/pipe.rb
+- lib/cztop/zap.rb
 - lib/cztop/zsock_options.rb
 - perf/README.md
 - perf/inproc_lat.rb