Add API gpgme_op_random_bytes.

* src/genrandom.c: New.
* src/Makefile.am: Add new file.
* src/engine-backend.h (struct engine_ops): Add func ptr getdirect.
Adjust all engine_ops.
* src/engine-gpg.c (gpg_getdirect): New.
(_gpgme_engine_ops_gpg): Connect new handler.
* src/gpgme.h.in (gpgme_random_mode_t): New.
(GPGME_RANDOM_MODE_NORMAL): New.
(GPGME_RANDOM_MODE_ZBASE32): New.
(gpgme_op_random_bytes): New public function
* src/libgpgme.vers: Add function.
* src/gpgme.def: Add function.

* tests/run-genrandom.c: New.
* tests/Makefile.am: Add new file.
--

This is a first take on this the mode parameter allows to extend the
function if ever needed.  Due to the gpg calling and fd setup overhead
this function is not yet very fast but its purpose is to get
"approved" random bytes.  We might eventually extend it to keep a
small internal cache of random numbers and get for example 128 random
bytes directly from gpg and deliver only the few required.

GnuPG-bug-id: 6694

1 files changed, 56 insertions, 0 deletions

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 9add4ff4..a586631e 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -223,6 +223,7 @@ Crypto Operations
 * Decrypt and Verify::            Decrypting a signed ciphertext.
 * Sign::                          Creating a signature.
 * Encrypt::                       Encrypting a plaintext.
+* Random::                        Getting strong random bytes.
 
 Sign
 
@@ -5747,6 +5748,7 @@ An error code describing the reason why the key was found invalid.
 * Decrypt and Verify::            Decrypting a signed ciphertext.
 * Sign::                          Creating a signature.
 * Encrypt::                       Encrypting a plaintext.
+* Random::                        Getting strong random bytes.
 @end menu
 
 
@@ -7092,6 +7094,60 @@ backend engine.
 
 @end deftypefun
 
+@node Random
+@subsection Random
+@cindex random bytes
+@cindex cryptographic operation, random
+
+GPGME provides a simple interface to get cryptographic strong random
+numbers from Libgcrypt via the GPG engine.
+
+@menu
+* Getting Random::        How to get random bytes.
+@end menu
+
+
+@node Getting Random
+@subsubsection How to get random bytes
+
+@deftp {Data type} {enum gpgme_random_mode_t}
+@tindex gpgme_random_mode_t
+
+This enum ist used to select special modes of the random generator.
+
+@table @code
+@item GPGME_RANDOM_MODE_NORMAL
+This is the standard mode, you may also use 0 instead of this enum
+value.
+
+@item GPGME_RANDOM_MODE_ZBASE32
+This mode is used to tell the random function to return a 30 character
+string with random characters from the zBase32 set of characters.  The
+returned string will be terminated by a Nul.
+@end table
+@end deftp
+
+
+@deftypefun {gpgme_error_t} gpgme_op_random_bytes ( @
+            @w{gpgme_ctx_t @var{ctx}}, @
+            @w{gpgme_random_mode_t @var{mode}}, @
+            @w{char *@var{buffer}}, @
+            @w{size_t @var{bufsize}})
+
+@since{2.0.0}
+
+The function @code{gpgme_op_random_bytes} returns random bytes.
+@var{buffer} must be provided by the caller with a size of
+@var{BUFSIZE} and will on return be filled with random bytes retrieved
+from gpg.  However, if @var{mode} is @code{GPGME_RANDOM_MODE_ZBASE32}
+@var{bufsize} needs to be at least 31 and will be filled with a string
+of 30 ASCII characters followed by a Nul; the remainder of the buffer
+is not changed.  This function has a limit of 1024 bytes to avoid
+accidental overuse of the random generator
+
+@end deftypefun
+
+
 
 @node Miscellaneous
 @section Miscellaneous operations