zyre 0.1.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5946a8a32c3932017f3c6fc60d6a54e3a2196a5e193a769975a1c4b47cbb405e
-  data.tar.gz: 5e51339b1fbc508dd0de7f3abc921aa7c2912cc243fda3a059d9057648c6acb9
+  metadata.gz: 8f9955065b8a5747d69568a305961f021969233ef249a1159ec419f81de9cf10
+  data.tar.gz: 382479e094fe5beb93ec78f1a3b1e2cc7dc9bf2ad6a1516fe6828a946942223e
 SHA512:
-  metadata.gz: 5177153a30ea6f2f28ebfb7372e3055a51ec793ea5a5bd51c3afde8b41ba1909b88a5daae334ab5fd52db9858e10b1f0184e7a4f566f7f8ee7240311748e1ab4
-  data.tar.gz: 61057878f14e360a57bf233ee5649dec9659686090d20f72461fcb955e387fa204e1afdcbadb8b5112e517a64547a27df5aa18eeea2706a9d65221724fbc89a5
+  metadata.gz: dcd9a759228bc18f5192066b1638dbc529b615e829ffd143001d9611c6e9e10ce1fc376fa2d10ad3bf6515a209d4724af4e82dc823f404e1991433c235a51f46
+  data.tar.gz: 6601536d2ede57eb152b7908839435334d936cd3cd116e4ca1805aed97fe65724c927f3252950435ff0ac094dd6e4cd017a4cb7855a3fb5a3801178a002f6521

checksums.yaml.gz.sig

@@ -1,2 +1,3 @@
-b��
-��ˑ�}�d��ܐk���B܆����le��Kt��'���J�~�	�����Bf�4�xIЛ
x�(�Z9�s�L�a��f��|cу��)�'�}w���Ij�v
+F
+�z1�)ȍ�\�f�@^��a�u���.D��̅�\�v;%��0��I���-Y;&��YN�W��(�{g���X��>�u"�5A����:�Ļ� <p�]V����D��P��t��rG���㾎?DOx�uJp��ɒ+M�~�m��K�؈�9�t{�GԾ��V����DNY�����p���}�b�l"Y�tk���*�p\qi���a͢�^fsg�zǒ�A��(���ye芣�]�9��k6)gM*=��&�אfaG�[F�]���,�z��[9V��`��ZI��
�?�,�?o%�M��ϥދ�J)��W$i���XL�
+n3��K�/DXZԚ�B8��ۤ����G4>4s���[Q����u��)r�;ձ�]�=�G�N

data/Authentication.md

@@ -0,0 +1,30 @@
+# Authenticated \Zyre
+
+Note that authentication requires API that is still in Draft, so it requires
+that your libzyre be built with --enable-drafts. Also, since draft APIs are
+subject to change, this documentation may be out of date. A good place to check
+for the latest info is the built-in test suites in the Zyre source itself.
+
+Authentication isn't done yet, but when it is it'll look something like:
+
+    cert = Zyre::Cert.new
+    cert.save( "/usr/local/var/certs/server" )
+
+    Zyre.allow( "127.0.0.1", "10.0.12.2" )
+    Zyre.start_authenticator( :CURVE, "/usr/local/var/certs" )
+
+    node = Zyre::Node.new
+    node.zap_domain = 'application_name'
+    node.zcert = cert
+    node.start
+
+    # later...
+
+    node.stop
+    Zyre.stop_authenticator
+
+
+## References
+
+- ZAP (ZeroMQ Authentication Protocol) - https://rfc.zeromq.org/spec/27/
+- Using ZeroMQ Security (Part 2) - https://jaxenter.com/using-zeromq-security-part-2-119353.html

data/History.md

@@ -1,6 +1,42 @@
 # Release History for zyre
 
 ---
+## v0.4.1 [2021-03-16] Michael Granger <ged@faeriemud.org>
+
+Bugfixes:
+
+- Add a missing library file to the manifest.
+
+
+## v0.4.0 [2021-02-19] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add partial support for draft APIs
+- Add a singleton method for disabling CZMQ's default SIGINT/TERM handler.
+
+
+## v0.3.1 [2020-11-23] Michael Granger <ged@faeriemud.org>
+
+Bugfixes:
+
+- Use cast String in rzyre_add_frames_to_zmsg()
+
+
+## v0.3.0 [2020-11-16] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Fixed use of binary data in event frames.
+
+
+## v0.2.0 [2020-11-09] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add multipart messaging.
+- Allow positional args for testing factory SHOUTs and WHISPERs
+
 
 ## v0.1.0 [2020-11-05] Michael Granger <ged@faeriemud.org>
 

data/README.md

@@ -21,20 +21,84 @@ reliable group messaging over local area networks, an implementation of [the Zer
 
 ### Examples
 
-    # Join the Zyre network on the network associated with the given interface
-    # and dump events from the 'global' group to stderr.
+Zyre is a P2P library which has two modes: pub/sub and direct messaging. To use it, you create a node, optionally join some groups (subscribing), and start it. Then you can send broadcast messages to all other nodes in a group, or direct messages to a particular node.
+
+This example joins the Zyre network and dumps messages it sees in the 'global' group to stderr:
+
     node = Zyre::Node.new
-    node.interface = 'igb0'
+    node.join( 'global' )
     node.start
     
-    while event = node.recv
+    node.each_event do |event|
       event.print
     end
 
+To send a direct message to a different node you need to know its `UUID`. There are number of ways to discover this:
+
+    # The UUIDs of all connected peers
+    node.peers
+    # The UUIDs of all the peers which have joined the `general` group
+    node.peers_by_group( 'general' )
+    # The UUID of the peer that sent the event
+    received_event.peer_uuid
+
+You read events from the network with the Zyre::Node#recv method, but it blocks until an event arrives:
+
+    event = node.recv
+
+You can also iterate over arriving events:
+
+    node.each do |event|
+        ...
+    end
+
+or use Zyre::Node#each as an Enumerator:
+
+    five_events = node.each_event.take( 5 )
+
+You can also wait for a certain type of event:
+
+    event = node.wait_for( :SHOUT )
+
+and time out if it doesn't arrive within a certain length of time:
+
+    event = node.wait_for( :ENTER, timeout: 2.0 ) or
+        raise "No one else on the network!"
+
+You can join a group with Zyre::Node#join:
+
+    node.join( 'alerts' )
+
+and you can detect other nodes joining one of your groups by looking for JOIN events (Zyre::Event::Join objects):
+
+    node.wait_for( :JOIN )
+
+You can publish a message to all nodes in a group with Zyre::Node#shout:
+
+    node.shout( "group1", "This is a message." )
+
+and read it:
+
+    event = other_node.recv
+    event.is_multipart?  # => false
+    event.msg            # => "This is a message."
+    event.multipart_msg  # => ["This is a message."]
+
+
+Or publish a message with multiple parts:
+
+    node.shout( "group1", 'message.type', "This is a message." )
+
+and read it:
+
+    event = other_node.recv
+    event.is_multipart?  # => true
+    event.msg            # => "message.type"
+    event.multipart_msg  # => ["message.type", "This is a message."]
+
 
 ### To-Do
 
-* Implement Zyre::Node#peer_groups and Zyre::Node#peer_address
 * Implement the draft API methods on Zyre::Node
 * Hook up logging via `zsys_set_logsender`
 * Add richer matching to Zyre::Event#match.
@@ -71,7 +135,7 @@ development.
 
 ## License
 
-Copyright (c) 2020, Ravn Group
+Copyright (c) 2020-2021, Ravn Group
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/ext/zyre_ext/cert.c

@@ -0,0 +1,504 @@
+/*
+ *  cert.c - A curve certificate for use with Zyre.
+ *  $Id$
+ *
+ *  Authors:
+ *    * Michael Granger <ged@FaerieMUD.org>
+ *
+ */
+
+#include "zyre_ext.h"
+
+VALUE rzyre_cZyreCert;
+
+// Forward declarations
+static void rzyre_cert_free( void *ptr );
+
+
+static const rb_data_type_t rzyre_cert_t = {
+	.wrap_struct_name = "Zyre::Cert",
+	.function = {
+		.dmark = NULL,
+		.dfree = rzyre_cert_free,
+	},
+	.data = NULL,
+	.flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+
+/*
+ * Free function
+ */
+static void
+rzyre_cert_free( void *ptr )
+{
+	if ( ptr ) {
+		zcert_destroy( (zcert_t **)&ptr );
+	}
+}
+
+
+/*
+ * Alloc function
+ */
+static VALUE
+rzyre_cert_alloc( VALUE klass )
+{
+	return TypedData_Wrap_Struct( klass, &rzyre_cert_t, NULL );
+}
+
+
+/*
+ * Fetch the data pointer and check it for sanity.
+ */
+inline zcert_t *
+rzyre_get_cert( VALUE self )
+{
+	zcert_t *ptr;
+
+	if ( !IsZyreCert(self) ) {
+		rb_raise( rb_eTypeError, "wrong argument type %s (expected Zyre::Cert)",
+			rb_class2name(CLASS_OF( self )) );
+	}
+
+	ptr = DATA_PTR( self );
+	assert( ptr );
+
+	return ptr;
+}
+
+
+/*
+ * call-seq:
+ *   Zyre::Cert.from( public_key, secret_key )    -> cert
+ *
+ * Create a certificate from the +public_key+ and +secret_key+.
+ *
+ */
+static VALUE
+rzyre_cert_s_from( VALUE class, VALUE public_key, VALUE secret_key )
+{
+	VALUE self = rzyre_cert_alloc( class );
+	zcert_t *ptr = NULL;
+	const char *pub_str = StringValuePtr( public_key ),
+		*sec_str = StringValuePtr( secret_key );
+
+	if ( RSTRING_LEN(public_key) == 32 && RSTRING_LEN(secret_key) == 32 ) {
+		ptr = zcert_new_from( (const byte *)pub_str, (const byte *)sec_str );
+	} else if ( RSTRING_LEN(public_key) == 40 && RSTRING_LEN(secret_key) == 40 ) {
+#ifdef CZMQ_BUILD_DRAFT_API
+		ptr = zcert_new_from_txt( pub_str, sec_str );
+#else
+		rb_raise( rb_eNotImpError,
+			"can't create a key from encoded keys: Czmq was not built with Draft APIs!" );
+#endif
+	}
+
+	if ( !ptr ) {
+		rb_raise( rb_eArgError, "invalid key pair" );
+	}
+
+	RTYPEDDATA_DATA( self ) = ptr;
+
+	return self;
+}
+
+
+/*
+ * call-seq:
+ *   Zyre::Cert.load( filename )    -> cert
+ *
+ * Create a certificate from a saved certificate in the specified
+ * +filename+.
+ *
+ */
+static VALUE
+rzyre_cert_s_load( VALUE class, VALUE filename )
+{
+	VALUE self = rzyre_cert_alloc( class );
+	zcert_t *ptr = zcert_load( StringValueCStr(filename) );
+
+	if ( !ptr ) {
+		rb_raise( rb_eArgError, "failed to load cert from %s", RSTRING_PTR(filename) );
+	}
+
+	RTYPEDDATA_DATA( self ) = ptr;
+
+	return self;
+}
+
+
+/*
+ * call-seq:
+ *    Zyre::Cert.new   -> cert
+ *
+ * Create a new certificate.
+ *
+ */
+static VALUE
+rzyre_cert_initialize( VALUE self )
+{
+	zcert_t *ptr;
+
+	TypedData_Get_Struct( self, zcert_t, &rzyre_cert_t, ptr );
+	if ( !ptr ) {
+		RTYPEDDATA_DATA( self ) = ptr = zcert_new();
+		assert( ptr );
+	}
+
+	return self;
+}
+
+
+/*
+ * call-seq:
+ *    cert.public_key   -> key_data
+ *
+ * Return public part of key pair as 32-byte binary string
+ *
+ */
+static VALUE
+rzyre_cert_public_key( VALUE self )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const byte *key = zcert_public_key( ptr );
+	VALUE rval = rb_enc_str_new( (const char *)key, 32, rb_ascii8bit_encoding() );
+
+	return rval;
+}
+
+
+/*
+ * call-seq:
+ *    cert.secret_key   -> key_data
+ *
+ * Return secret part of key pair as 32-byte binary string
+ *
+ */
+static VALUE
+rzyre_cert_secret_key( VALUE self )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const byte *key = zcert_secret_key( ptr );
+	VALUE rval = rb_enc_str_new( (const char *)key, 32, rb_ascii8bit_encoding() );
+
+	return rval;
+}
+
+
+/*
+ * call-seq:
+ *    cert.public_txt   -> key_text
+ *
+ * Return public part of key pair as Z85 armored string
+ *
+ */
+static VALUE
+rzyre_cert_public_txt( VALUE self )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const char *key = zcert_public_txt( ptr );
+	VALUE rval = rb_usascii_str_new( key, 40 );
+
+	return rval;
+}
+
+
+/*
+ * call-seq:
+ *    cert.secret_txt   -> key_text
+ *
+ * Return secret part of key pair as Z85 armored string
+ *
+ */
+static VALUE
+rzyre_cert_secret_txt( VALUE self )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const char *key = zcert_secret_txt( ptr );
+	VALUE rval = rb_usascii_str_new( key, 40 );
+
+	return rval;
+}
+
+
+/*
+ * call-seq:
+ *    cert.set_meta( name, value )
+ *
+ * Set certificate metadata +name+ to +value+.
+ *
+ */
+static VALUE
+rzyre_cert_set_meta( VALUE self, VALUE name, VALUE val )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const char *key_str = StringValueCStr( name ),
+		*val_str = StringValueCStr( val );
+
+#ifdef CZMQ_BUILD_DRAFT_API
+	zcert_unset_meta( ptr, key_str );
+#endif
+
+	zcert_set_meta( ptr, key_str, "%s", val_str );
+
+	return val;
+}
+
+
+/*
+ * call-seq:
+ *    cert.meta( name )   -> string
+ *
+ * Return the metadata value for +name+ from certificate; if the metadata
+ * value doesn't exist, returns +nil+.
+ *
+ */
+static VALUE
+rzyre_cert_meta( VALUE self, VALUE name )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	VALUE rval = Qnil;
+	const char *name_str = StringValuePtr( name );
+	const char *value = zcert_meta( ptr, name_str );
+
+	if ( value ) rval = rb_str_new_cstr( value );
+
+	return rval;
+}
+
+
+/*
+ * call-seq:
+ *    cert.keys   -> array
+ *
+ * Return an Array of metadata field names that belong to the receiver.
+ *
+ */
+static VALUE
+rzyre_cert_meta_keys( VALUE self )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	zlist_t *keys = zcert_meta_keys( ptr );
+	VALUE rary = rb_ary_new();
+	char *item;
+
+	assert( keys );
+
+	item = zlist_first( keys );
+	while ( item ) {
+		rb_ary_push( rary, rb_str_new_cstr(item) );
+		item = zlist_next( keys );
+	}
+
+	zlist_destroy( &keys );
+
+	return rary;
+}
+
+
+/*
+ * call-seq:
+ *    cert.unset_meta( name )
+ *
+ * Unset certificate metadata value for the given +name.
+ *
+ * Note: this is a draft method for development use, may change without warning.
+ *
+ */
+static VALUE
+rzyre_cert_unset_meta( VALUE self, VALUE name )
+{
+#ifdef CZMQ_BUILD_DRAFT_API
+	zcert_t *ptr = rzyre_get_cert( self );
+	const char *name_str = StringValueCStr( name );
+
+	zcert_unset_meta( ptr, name_str );
+
+	return Qtrue;
+#else
+	rb_raise( rb_eNotImpError, "Czmq was not built with Draft APIs!" );
+#endif // CZMQ_BUILD_DRAFT_API
+}
+
+
+/*
+ * call-seq:
+ *    cert.save( filename )
+ *
+ * Save the full certificate (public + secret) to the specified +filename+.
+ * This creates one public file and one secret file (filename + "_secret").
+ *
+ */
+static VALUE
+rzyre_cert_save( VALUE self, VALUE filename )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const char *filename_str = StringValueCStr( filename );
+	int result;
+
+	result = zcert_save( ptr, filename_str );
+
+	if ( result != 0 )
+		rb_raise( rb_eRuntimeError, "failed to save cert to %s", filename_str );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    cert.save_public( filename )
+ *
+ * Save the public certificate only to the specified +filename+.
+ *
+ */
+static VALUE
+rzyre_cert_save_public( VALUE self, VALUE filename )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const char *filename_str = StringValueCStr( filename );
+	int result;
+
+	result = zcert_save_public( ptr, filename_str );
+
+	if ( result != 0 )
+		rb_raise( rb_eRuntimeError, "failed to save public cert to %s", filename_str );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    cert.save_secret( filename )
+ *
+ * Save the secret certificate only to the specified +filename+.
+ *
+ */
+static VALUE
+rzyre_cert_save_secret( VALUE self, VALUE filename )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	const char *filename_str = StringValueCStr( filename );
+	int result;
+
+	result = zcert_save_secret( ptr, filename_str );
+
+	if ( result != 0 )
+		rb_raise( rb_eRuntimeError, "failed to save secret cert to %s", filename_str );
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    cert.dup   -> cert
+ *
+ * Return a copy of the certificate.
+ *
+ */
+static VALUE
+rzyre_cert_dup( VALUE self )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+	zcert_t *other_ptr;
+	VALUE other = rb_call_super( 0, NULL );
+
+	RTYPEDDATA_DATA( other ) = other_ptr = zcert_dup( ptr );
+
+	if ( !other_ptr )
+		rb_raise( rb_eRuntimeError, "couldn't duplicate the cert" );
+
+	return other;
+}
+
+
+/*
+ * call-seq:
+ *    cert.eql?( other_cert )   -> true or false
+ *
+ * Return true if the +other_cert+ has the same keys.
+ *
+ */
+static VALUE
+rzyre_cert_eql_p( VALUE self, VALUE other )
+{
+	zcert_t *ptr = rzyre_get_cert( self ),
+		*other_ptr = rzyre_get_cert( other );
+	bool equal = zcert_eq( ptr, other_ptr );
+
+	return equal ? Qtrue : Qfalse;
+}
+
+
+/*
+ * call-seq:
+ *    cert.print
+ *
+ * Print certificate contents to stdout.
+ *
+ */
+static VALUE
+rzyre_cert_print( VALUE self )
+{
+	zcert_t *ptr = rzyre_get_cert( self );
+
+	zcert_print( ptr );
+
+	return Qtrue;
+}
+
+
+
+/*
+ * Initialize the Cert class.
+ */
+void
+rzyre_init_cert( void ) {
+
+#ifdef FOR_RDOC
+	rb_cData = rb_define_class( "Data" );
+	rzyre_mZyre = rb_define_module( "Zyre" );
+#endif
+
+	/*
+	 * Document-class: Zyre::Cert
+	 *
+	 * A certificate for Zyre curve authentication.
+	 *
+	 * Refs:
+	 * - http://api.zeromq.org/czmq4-0:zcert
+	 *
+	 */
+	rzyre_cZyreCert = rb_define_class_under( rzyre_mZyre, "Cert", rb_cObject );
+
+	rb_define_alloc_func( rzyre_cZyreCert, rzyre_cert_alloc );
+
+	rb_define_singleton_method( rzyre_cZyreCert, "from", rzyre_cert_s_from, 2 );
+	rb_define_singleton_method( rzyre_cZyreCert, "load", rzyre_cert_s_load, 1 );
+
+	rb_define_protected_method( rzyre_cZyreCert, "initialize", rzyre_cert_initialize, 0 );
+
+	rb_define_method( rzyre_cZyreCert, "public_key", rzyre_cert_public_key, 0 );
+	rb_define_method( rzyre_cZyreCert, "secret_key", rzyre_cert_secret_key, 0 );
+	rb_define_method( rzyre_cZyreCert, "public_txt", rzyre_cert_public_txt, 0 );
+	rb_define_method( rzyre_cZyreCert, "secret_txt", rzyre_cert_secret_txt, 0 );
+
+	rb_define_method( rzyre_cZyreCert, "set_meta", rzyre_cert_set_meta, 2 );
+	rb_define_method( rzyre_cZyreCert, "meta", rzyre_cert_meta, 1 );
+	rb_define_method( rzyre_cZyreCert, "meta_keys", rzyre_cert_meta_keys, 0 );
+	rb_define_method( rzyre_cZyreCert, "unset_meta", rzyre_cert_unset_meta, 1 ); // DRAFT
+
+	rb_define_method( rzyre_cZyreCert, "save", rzyre_cert_save, 1 );
+	rb_define_method( rzyre_cZyreCert, "save_public", rzyre_cert_save_public, 1 );
+	rb_define_method( rzyre_cZyreCert, "save_secret", rzyre_cert_save_secret, 1 );
+
+	rb_define_method( rzyre_cZyreCert, "dup", rzyre_cert_dup, 0 );
+	rb_define_method( rzyre_cZyreCert, "eql?", rzyre_cert_eql_p, 1 );
+	rb_define_method( rzyre_cZyreCert, "print", rzyre_cert_print, 0 );
+
+	rb_require( "zyre/cert" );
+}
+