Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZCERT(3)			  CZMQ Manual			      ZCERT(3)

NAME
       zcert - Class for work with CURVE security certificates

SYNOPSIS
       //  This	is a stable class, and may not change except for emergencies. It
       //  is provided in stable builds.
       //  This	class has draft	methods, which may change over time. They are not
       //  in stable releases, by default. Use --enable-drafts to enable.
       //  Create and initialize a new certificate in memory
       CZMQ_EXPORT zcert_t *
	   zcert_new (void);

       //  Accepts public/secret key pair from caller
       CZMQ_EXPORT zcert_t *
	   zcert_new_from (const byte *public_key, const byte *secret_key);

       //  Load	certificate from file
       CZMQ_EXPORT zcert_t *
	   zcert_load (const char *filename);

       //  Destroy a certificate in memory
       CZMQ_EXPORT void
	   zcert_destroy (zcert_t **self_p);

       //  Return public part of key pair as 32-byte binary string
       CZMQ_EXPORT const byte *
	   zcert_public_key (zcert_t *self);

       //  Return secret part of key pair as 32-byte binary string
       CZMQ_EXPORT const byte *
	   zcert_secret_key (zcert_t *self);

       //  Return public part of key pair as Z85 armored string
       CZMQ_EXPORT const char *
	   zcert_public_txt (zcert_t *self);

       //  Return secret part of key pair as Z85 armored string
       CZMQ_EXPORT const char *
	   zcert_secret_txt (zcert_t *self);

       //  Set certificate metadata from formatted string.
       CZMQ_EXPORT void
	   zcert_set_meta (zcert_t *self, const	char *name, const char *format,	...) CHECK_PRINTF (3);

       //  Get metadata	value from certificate;	if the metadata	value doesn't
       //  exist, returns NULL.
       CZMQ_EXPORT const char *
	   zcert_meta (zcert_t *self, const char *name);

       //  Get list of metadata	fields from certificate. Caller	is responsible for
       //  destroying list. Caller should not modify the values	of list	items.
       CZMQ_EXPORT zlist_t *
	   zcert_meta_keys (zcert_t *self);

       //  Save	full certificate (public + secret) to file for persistent storage
       //  This	creates	one public file	and one	secret file (filename +	"_secret").
       CZMQ_EXPORT int
	   zcert_save (zcert_t *self, const char *filename);

       //  Save	public certificate only	to file	for persistent storage
       CZMQ_EXPORT int
	   zcert_save_public (zcert_t *self, const char	*filename);

       //  Save	secret certificate only	to file	for persistent storage
       CZMQ_EXPORT int
	   zcert_save_secret (zcert_t *self, const char	*filename);

       //  Apply certificate to	socket,	i.e. use for CURVE security on socket.
       //  If certificate was loaded from public file, the secret key will be
       //  undefined, and this certificate will	not work successfully.
       CZMQ_EXPORT void
	   zcert_apply (zcert_t	*self, void *socket);

       //  Return copy of certificate; if certificate is NULL or we exhausted
       //  heap	memory,	returns	NULL.
       //  Caller owns return value and	must destroy it	when done.
       CZMQ_EXPORT zcert_t *
	   zcert_dup (zcert_t *self);

       //  Return true if two certificates have	the same keys
       CZMQ_EXPORT bool
	   zcert_eq (zcert_t *self, zcert_t *compare);

       //  Print certificate contents to stdout
       CZMQ_EXPORT void
	   zcert_print (zcert_t	*self);

       //  Self	test of	this class
       CZMQ_EXPORT void
	   zcert_test (bool verbose);

       #ifdef CZMQ_BUILD_DRAFT_API
       //  *** Draft method, for development use, may change without warning ***
       //  Accepts public/secret key text pair from caller
       CZMQ_EXPORT zcert_t *
	   zcert_new_from_txt (const char *public_txt, const char *secret_txt);

       //  *** Draft method, for development use, may change without warning ***
       //  Unset certificate metadata.
       CZMQ_EXPORT void
	   zcert_unset_meta (zcert_t *self, const char *name);

       #endif // CZMQ_BUILD_DRAFT_API
       Please add '@interface' section in './../src/zcert.c'.

DESCRIPTION
       The zcert class provides	a way to create	and work with security
       certificates for	the ZMQ	CURVE mechanism. A certificate contains	a
       public +	secret key pair, plus metadata.	It can be used as a temporary
       object in memory, or persisted to disk. On disk,	a certificate is
       stored as two files. One	is public and contains only the	public key.
       The second is secret and	contains both keys. The	two have the same
       filename, with the secret file adding "_secret".	To exchange
       certificates, send the public file via some secure route. Certificates
       are not signed but are text files that can be verified by eye.

       Certificates are	stored in the ZPL (ZMQ RFC 4) format. They have	two
       sections, "metadata" and	"curve". The first contains a list of name =
       value pairs, one	per line. Values may be	enclosed in quotes. The	curve
       section has a public-key	= keyvalue and,	for secret certificates, a
       secret-key = keyvalue line. The keyvalue	is a Z85-encoded CURVE key.

EXAMPLE
       From zcert_test method.

	   const char *SELFTEST_DIR_RW = "src/selftest-rw";

	   const char *testbasedir  = ".test_zcert";
	   const char *testfile	= "mycert.txt";
	   char	*basedirpath = NULL;   // subdir in a test, under SELFTEST_DIR_RW
	   char	*filepath = NULL;      // pathname to testfile in a test, in dirpath
	   char	*filepath_s = NULL;    // pathname to testfile+secret in a test, in dirpath

	   basedirpath = zsys_sprintf ("%s/%s",	SELFTEST_DIR_RW, testbasedir);
	   assert (basedirpath);
	   filepath = zsys_sprintf ("%s/%s", basedirpath, testfile);
	   assert (filepath);
	   filepath_s =	zsys_sprintf ("%s_secret", filepath);
	   assert (filepath_s);

	   // Make sure	old aborted tests do not hinder	us
	   zdir_t *dir = zdir_new (basedirpath,	NULL);
	   if (dir) {
	       zdir_remove (dir, true);
	       zdir_destroy (&dir);
	   }
	   zsys_file_delete (filepath);
	   zsys_dir_delete  (basedirpath);

	   //  Create temporary	directory for test files
	   zsys_dir_create (basedirpath);

	   //  Create a	simple certificate with	metadata
	   zcert_t *cert = zcert_new ();
	   assert (cert);
	   zcert_set_meta (cert, "email", "ph@imatix.com");
	   zcert_set_meta (cert, "name", "Pieter Hintjens");
	   zcert_set_meta (cert, "organization", "iMatix Corporation");
	   zcert_set_meta (cert, "version", "%d", 1);
	   zcert_set_meta (cert, "delete_me", "now");
	   zcert_unset_meta (cert, "delete_me");
	   assert (streq (zcert_meta (cert, "email"), "ph@imatix.com"));
	   zlist_t *keys = zcert_meta_keys (cert);
	   assert (zlist_size (keys) ==	4);
	   zlist_destroy (&keys);

	   //  Check the dup and eq methods
	   zcert_t *shadow = zcert_dup (cert);
	   assert (zcert_eq (cert, shadow));
	   zcert_destroy (&shadow);

	   //  Check we	can save and load certificate
	   zcert_save (cert, filepath);
	   assert (zsys_file_exists (filepath));
	   assert (zsys_file_exists (filepath_s));

	   //  Load certificate, will in fact load secret one
	   shadow = zcert_load (filepath);
	   assert (shadow);
	   assert (zcert_eq (cert, shadow));
	   zcert_destroy (&shadow);

	   //  Delete secret certificate, load public one
	   int rc = zsys_file_delete (filepath_s);
	   assert (rc == 0);
	   shadow = zcert_load (filepath);

	   //  32-byte null key	encodes	as 40 '0' characters
	   assert (streq (zcert_secret_txt (shadow), FORTY_ZEROES));

	   #ifdef CZMQ_BUILD_DRAFT_API
	   // test zcert_from_txt
	   zcert_t *cert2 = zcert_new_from_txt(cert->public_txt, cert->secret_txt);
	   assert (cert2);
	   assert (zcert_eq (cert, cert2));
	   zcert_destroy(&cert2);
	   #endif

	   zcert_destroy (&shadow);
	   zcert_destroy (&cert);

	   //  Delete all test files
	   dir = zdir_new (basedirpath,	NULL);
	   assert (dir);
	   zdir_remove (dir, true);
	   zdir_destroy	(&dir);

	   zstr_free (&basedirpath);
	   zstr_free (&filepath);
	   zstr_free (&filepath_s);

	   #if defined (__WINDOWS__)
	   zsys_shutdown();
	   #endif

AUTHORS
       The czmq	manual was written by the authors in the AUTHORS file.

RESOURCES
       Main web	site:

       Report bugs to the email	<zeromq-dev@lists.zeromq.org[1]>

COPYRIGHT
       Copyright (c) the Contributors as noted in the AUTHORS file. This file
       is part of CZMQ,	the high-level C binding for 0MQ:
       http://czmq.zeromq.org. This Source Code	Form is	subject	to the terms
       of the Mozilla Public License, v. 2.0. If a copy	of the MPL was not
       distributed with	this file, You can obtain one at
       http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
       distribution.

NOTES
	1. zeromq-dev@lists.zeromq.org
	   mailto:zeromq-dev@lists.zeromq.org

CZMQ 4.1.1			  08/10/2020			      ZCERT(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHORS | RESOURCES | COPYRIGHT | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zcert&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help