qpid_proton 0.9.0 → 0.10

data/lib/core/ssl.rb

@@ -0,0 +1,164 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+module Qpid::Proton
+
+  # The SSL support for Transport.
+  #
+  # A Transport may be configured ot use SLL for encryption and/or
+  # authentication. A Transport can be configured as either the SSL
+  # client or the server. An SSL client is the party that proctively
+  # establishes a connection to an SSL server. An SSL server is the
+  # party that accepts a connection request from the remote SSL client.
+  #
+  # If either the client or the server needs to identify itself with the
+  # remote node, it must have its SSL certificate configured.
+  #
+  # @see SSLDomain#credentials For setting the SSL certificate.
+  #
+  # If either the client or the server needs to verify the identify of the
+  # remote node, it must have its database of trusted CAs configured.
+  #
+  # @see SSLDomain#trusted_ca_db Setting the CA database.
+  #
+  # An SSL server connection may allow the remote client to connect without
+  # SS (i.e., "in the clear").
+  #
+  # @see SSLDomain#allow_unsecured_client Allowing unsecured clients.
+  #
+  # The level of verification required of the remote may be configured.
+  #
+  # @see SSLDomain#peer_authentication Setting peer authentication.
+  #
+  # Support for SSL client session resume is provided as well.
+  #
+  # @see SSLDomain
+  # @see #resume_status
+  #
+  class SSL
+
+    # Session resume state is unkonnwn or not supported.
+    RESUME_UNKNOWN = Cproton::PN_SSL_RESUME_UNKNOWN
+    # Session renegotiated and not resumed.
+    RESUME_NEW = Cproton::PN_SSL_RESUME_NEW
+    # Session resumed from the previous session.
+    RESUME_REUSED = Cproton::PN_SSL_RESUME_REUSED
+
+    # @private
+    include Util::SwigHelper
+
+    # @private
+    PROTON_METHOD_PREFIX = "pn_ssl"
+
+    # @private
+    include Util::ErrorHandler
+
+    can_raise_error :peer_hostname=, :error_class => SSLError
+
+    # Returns whether SSL is supported.
+    #
+    # @return [Boolean] True if SSL support is available.
+    #
+    def self.present?
+      Cproton.pn_ssl_present
+    end
+
+    # @private
+    def self.create(transport, domain, session_details = nil)
+      result = nil
+      # like python, make sure we're not creating a different SSL
+      # object for a transport with an existing SSL object
+      if transport.ssl?
+        transport.instance_eval { result = @ssl }
+        if ((!domain.nil? && (result.domain != domain)) ||
+            (!session_details.nil? && (result.session_details != session_details)))
+          raise SSLException.new("cannot re-configure existing SSL object")
+        end
+      else
+        impl = Cproton.pn_ssl(transport.impl)
+        session_id = nil
+        session_id = session_details.session_id unless session_details.nil?
+        result = SSL.new(impl, domain, session_details, session_id)
+      end
+      return result
+    end
+
+    private
+
+    def initialize(impl, domain, session_details, session_id)
+      @impl = impl
+      @domain = domain.impl unless domain.nil?
+      @session_details = session_details
+      @session_id = session_id
+      Cproton.pn_ssl_init(@impl, @domain, @session_id)
+    end
+
+    public
+
+    # Returns the cipher name that is currently in used.
+    #
+    # Gets the text description of the cipher that is currently active, or
+    # returns nil if SSL is not active. Note that the cipher in use my change
+    # over time due to renegotiation or other changes to the SSL layer.
+    #
+    # @return [String, nil] The cipher name.
+    #
+    def cipher_name
+      rc, name = Cproton.pn_ssl_get_cipher_name(@impl, 128)
+      return name if rc
+      nil
+    end
+
+    # Returns the name of the SSL protocol that is currently active, or
+    # returns nil if SSL is nota ctive. Not that the protocol may change over
+    # time due to renegotation.
+    #
+    # @return [String, nil] The protocol name.
+    #
+    def protocol_name
+      rc, name = Cproton.pn_ssl_get_protocol_name(@impl, 128)
+      retur name if rc
+      nil
+    end
+
+    # Checks whether or not the state has resumed.
+    #
+    # Used for client session resume. When called on an active session, it
+    # indicates wehther the state has been resumed from a previous session.
+    #
+    # *NOTE:* This is a best-effort service - there is no guarantee that the
+    # remote server will accept the resumed parameters. The remote server may
+    # choose to ignore these parameters, and request a renegotation instead.
+    #
+    def resume_status
+      Cproton.pn_ssl_resume_status(@impl)
+    end
+
+    # Gets the peer hostname.
+    #
+    # @return [String] The peer hostname.
+    def peer_hostname
+      (error, name) = Cproton.pn_ssl_get_peer_hostname(@impl, 1024)
+      raise SSLError.new if error < 0
+      return name
+    end
+
+  end
+
+end

data/lib/{qpid_proton/version.rb → core/ssl_details.rb}

@@ -17,15 +17,16 @@
 # under the License.
 #++
 
-module Qpid # :nodoc:
+module Qpid::Proton
 
-  module Proton # :nodoc:
+  # @private
+  class SSLSessionDetails
 
-    # The major version for the underlying Proton library.
-    VERSION_MAJOR = Cproton::PN_VERSION_MAJOR
+    attr_reader :session_id
 
-    # The minor version for the underlying Proton library.
-    VERSION_MINOR = Cproton::PN_VERSION_MINOR
+    def initialize(session_id)
+      @session_id = session_id
+    end
 
   end
 

data/lib/core/ssl_domain.rb

@@ -0,0 +1,156 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+module Qpid::Proton
+
+  # The top-level object that stores the configuration used by one or more
+  # SSL sessions.
+  #
+  # @see SSL
+  #
+  class SSLDomain
+
+    # The local connection endpoint is an SSL client.
+    # @private
+    MODE_CLIENT = Cproton::PN_SSL_MODE_CLIENT
+    # The local connection endpoint is an SSL server.
+    # @private
+    MODE_SERVER = Cproton::PN_SSL_MODE_SERVER
+
+    # Require the peer to provide a valid identifying certificate.
+    VERIFY_PEER = Cproton::PN_SSL_VERIFY_PEER
+    # Do no require a certificate nor a cipher authorization.
+    ANONYMOUS_PEER = Cproton::PN_SSL_ANONYMOUS_PEER
+    # Require a valid certficate and matching name.
+    VERIFY_PEER_NAME = Cproton::PN_SSL_VERIFY_PEER_NAME
+
+    # @private
+    include Util::ErrorHandler
+
+    can_raise_error :credentials, :error_class => Qpid::Proton::SSLError
+    can_raise_error :trusted_ca_db, :error_class => Qpid::Proton::SSLError
+    can_raise_error :peer_authentication, :error_class => Qpid::Proton::SSLError
+    can_raise_error :allow_unsecured_client, :error_class => Qpid::Proton::SSLError
+
+    # @private
+    attr_reader :impl
+
+    # @private
+    def initialize(mode)
+      @impl = Cproton.pn_ssl_domain(mode)
+      raise SSLUnavailable.new if @impl.nil?
+    end
+
+    # Set the certificate that identifies the local node to the remote.
+    #
+    # This certificate establishes the identity for thelocal node for all SSL
+    # sessions created from this domain. It will be sent to the remote if the
+    # remote needs to verify the dientify of this node. This may be used for
+    # both SSL servers and SSL clients (if client authentication is required by
+    # the server).
+    #
+    # *NOTE:* This setting affects only those instances of SSL created *after*
+    # this call returns. SSL objects created before invoking this method will
+    # use the domain's previous settings.
+    #
+    # @param cert_file [String] The filename containing the identify
+    #  certificate. For OpenSSL users, this is a PEM file. For Windows SChannel
+    #  users, this is the PKCS\#12 file or system store.
+    # @param key_file [String] An option key to access the identifying
+    #  certificate. For OpenSSL users, this is an optional PEM file containing
+    #  the private key used to sign the certificate. For Windows SChannel users,
+    #  this is the friendly name of the self-identifying certficate if there are
+    #  multiple certfificates in the store.
+    # @param password [String] The password used to sign the key, or *nil* if
+    #  the key is not protected.
+    #
+    # @raise [SSLError] If an error occurs.
+    #
+    def credentials(cert_file, key_file, password)
+      Cproton.pn_ssl_domain_set_credentials(@impl,
+                                            cert_file, key_file, password)
+    end
+
+    # Configures the set of trusted CA certificates used by this domain to
+    # verify peers.
+    #
+    # If the local SSL client/server needs to verify the identify of the remote,
+    # it must validate the signature of the remote's certificate. This function
+    # sets the database of trusted CAs that will be used to verify the signature
+    # of the remote's certificate.
+    #
+    # *NOTE:# This setting affects only those SSL instances created *after* this
+    # call returns. SSL objects created before invoking this method will use the
+    # domain's previous setting.
+    #
+    # @param certificate_db [String] The filename for the databse of trusted
+    #   CAs, used to authenticate the peer.
+    #
+    # @raise [SSLError] If an error occurs.
+    #
+    def trusted_ca_db(certificate_db)
+      Cproton.pn_ssl_domain_set_trusted_ca_db(@impl, certificate_db)
+    end
+
+    # Configures the level of verification used on the peer certificate.
+    #
+    # This method congtrols how the peer's certificate is validated, if at all.
+    # By default, neither servers nor clients attempt to verify their peers
+    # (*ANONYMOUS_PEER*). Once certficates and trusted CAs are configured, peer
+    # verification can be enabled.
+    #
+    # *NOTE:* In order to verify a peer, a trusted CA must be configured.
+    #
+    # *NOTE:* Servers must provide their own certficate when verifying a peer.
+    #
+    # *NOTE:* This setting affects only those SSL instances created after this
+    # call returns. SSL instances created before invoking this method will use
+    # the domain's previous setting.
+    #
+    # @param verify_mode [Fixnum] The level of validation to apply to the peer.
+    # @param trusted_CAs [String] The path to a database of trusted CAs that
+    #   the server will advertise to the peer client if the server has been
+    #   configured to verify its peer.
+    #
+    # @see VERIFY_PEER
+    # @see ANONYMOUS_PEER
+    # @see VERIFY_PEER_NAME
+    #
+    # @raise [SSLError] If an error occurs.
+    #
+    def peer_authentication(verify_mode, trusted_CAs = nil)
+      Cproton.pn_ssl_domain_set_peer_authentication(@impl,
+                                                    verify_mode, trusted_CAs)
+    end
+
+    # Permit a server to accept connection requests from non-SSL clients.
+    #
+    # This configures the server to "sniff" the incomfing client data stream and
+    # dynamically determine whether SSL/TLS is being used. This option is
+    # disabled by default: only clients using SSL/TLS are accepted by default.
+    #
+    # @raise [SSLError] If an error occurs.
+    #
+    def allow_unsecured_client
+      Cproton.pn_ssl_domain_allow_unsecured_client(@impl);
+    end
+
+  end
+
+end

data/lib/core/terminus.rb

@@ -0,0 +1,218 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+module Qpid::Proton
+
+  # Represents an endpoint for an AMQP connection..
+  #
+  # An AMQP terminus acts as either a source or a target for messages,
+  # but never as both. Every Link is associated iwth both a source and
+  # a target Terminus that is negotiated during link establishment.
+  #
+  # A terminus is composed of an AMQP address along with a number of
+  # other properties defining the quality of service and behavior of
+  # the Link.
+  #
+  class Terminus
+
+    # Indicates a non-existent source or target terminus.
+    UNSPECIFIED = Cproton::PN_UNSPECIFIED
+    # Indicates a source for messages.
+    SOURCE = Cproton::PN_SOURCE
+    # Indicates a target for messages.
+    TARGET = Cproton::PN_TARGET
+    # A special target identifying a transaction coordinator.
+    COORDINATOR = Cproton::PN_COORDINATOR
+
+    # The terminus is orphaned when the parent link is closed.
+    EXPIRE_WITH_LINK = Cproton::PN_EXPIRE_WITH_LINK
+    # The terminus is orphaned whent he parent sessio is closed.
+    EXPIRE_WITH_SESSION = Cproton::PN_EXPIRE_WITH_SESSION
+    # The terminus is orphaned when the parent connection is closed.
+    EXPIRE_WITH_CONNECTION = Cproton::PN_EXPIRE_WITH_CONNECTION
+    # The terminus is never considered orphaned.
+    EXPIRE_NEVER = Cproton::PN_EXPIRE_NEVER
+
+    # Indicates a non-durable Terminus.
+    NONDURABLE = Cproton::PN_NONDURABLE
+    # Indicates a Terminus with durably held configuration, but
+    # not the delivery state.
+    CONFIGURATION = Cproton::PN_CONFIGURATION
+    # Indicates a Terminus with both durably held configuration and
+    # durably held delivery states.
+    DELIVERIES = Cproton::PN_DELIVERIES
+
+    # The behavior is defined by the nod.e
+    DIST_MODE_UNSPECIFIED = Cproton::PN_DIST_MODE_UNSPECIFIED
+    # The receiver gets all messages.
+    DIST_MODE_COPY = Cproton::PN_DIST_MODE_COPY
+    # The receives compete for messages.
+    DIST_MODE_MOVE = Cproton::PN_DIST_MODE_MOVE
+
+    # @private
+    include Util::SwigHelper
+
+    # @private
+    PROTON_METHOD_PREFIX = "pn_terminus"
+
+    # @!attribute type
+    #
+    # @return [Fixnum] The terminus type.
+    #
+    # @see SOURCE
+    # @see TARGET
+    # @see COORDINATOR
+    #
+    proton_accessor :type
+
+    # @!attribute address
+    #
+    # @return [String] The terminus address.
+    #
+    proton_accessor :address
+
+    # @!attribute durability
+    #
+    # @return [Fixnum] The durability mode of the terminus.
+    #
+    # @see NONDURABLE
+    # @see CONFIGURATION
+    # @see DELIVERIES
+    #
+    proton_accessor :durability
+
+    # @!attribute expiry_policy
+    #
+    # @return [Fixnum] The expiry policy.
+    #
+    # @see EXPIRE_WITH_LINK
+    # @see EXPIRE_WITH_SESSION
+    # @see EXPIRE_WITH_CONNECTION
+    # @see EXPIRE_NEVER
+    #
+    proton_accessor :expiry_policy
+
+    # @!attribute timeout
+    #
+    # @return [Fixnum] The timeout period.
+    #
+    proton_accessor :timeout
+
+    # @!attribute dynamic?
+    #
+    # @return [Boolean] True if the terminus is dynamic.
+    #
+    proton_accessor :dynamic, :is_or_get => :is
+
+    # @!attribute distribution_mode
+    #
+    # @return [Fixnum] The distribution mode.
+    #
+    # @see DIST_MODE_UNSPECIFIED
+    # @see DIST_MODE_COPY
+    # @see DIST_MODE_MOVE
+    #
+    proton_accessor :distribution_mode
+
+    # @private
+    include Util::ErrorHandler
+
+    can_raise_error [:type=, :address=, :durability=, :expiry_policy=,
+                          :timeout=, :dynamic=, :distribution_mode=, :copy],
+                    :error_class => Qpid::Proton::LinkError
+
+    # @private
+    attr_reader :impl
+
+    # @private
+    def initialize(impl)
+      @impl = impl
+    end
+
+    # Access and modify the AMQP properties data for the Terminus.
+    #
+    # This operation will return an instance of Data that is valid until the
+    # Terminus is freed due to its parent being freed. Any data contained in
+    # the object will be sent as the AMQP properties for the parent Terminus
+    # instance.
+    #
+    # NOTE: this MUST take the form of a symbol keyed map to be valid.
+    #
+    # @return [Data] The terminus properties.
+    #
+    def properties
+      Data.new(Cproton.pn_terminus_properties(@impl))
+    end
+
+    # Access and modify the AMQP capabilities data for the Terminus.
+    #
+    # This operation will return an instance of Data that is valid until the
+    # Terminus is freed due to its parent being freed. Any data contained in
+    # the object will be sent as the AMQP properties for the parent Terminus
+    # instance.
+    #
+    # NOTE: this MUST take the form of a symbol keyed map to be valid.
+    #
+    # @return [Data] The terminus capabilities.
+    #
+    def capabilities
+      Data.new(Cproton.pn_terminus_capabilities(@impl))
+    end
+
+    # Access and modify the AMQP outcomes for the Terminus.
+    #
+    # This operaiton will return an instance of Data that is valid until the
+    # Terminus is freed due to its parent being freed. Any data contained in
+    # the object will be sent as the AMQP properties for the parent Terminus
+    # instance.
+    #
+    # NOTE: this MUST take the form of a symbol keyed map to be valid.
+    #
+    # @return [Data] The terminus outcomes.
+    #
+    def outcomes
+      Data.new(Cproton.pn_terminus_outcomes(@impl))
+    end
+
+    # Access and modify the AMQP filter set for the Terminus.
+    #
+    # This operation will return an instance of Data that is valid until the
+    # Terminus is freed due to its parent being freed. Any data contained in
+    # the object will be sent as the AMQP properties for the parent Terminus
+    # instance.
+    #
+    # NOTE: this MUST take the form of a symbol keyed map to be valid.
+    #
+    # @return [Data] The terminus filter.
+    #
+    def filter
+      Data.new(Cproton.pn_terminus_filter(@impl))
+    end
+
+    # Copy another Terminus into this instance.
+    #
+    # @param source [Terminus] The source instance.
+    #
+    def copy(source)
+      Cproton.pn_terminus_copy(@impl,source.impl)
+    end
+
+  end
+
+end