core: Fix expiration time handling when creating keys.

* NEWS: Update.
* doc/gpgme.texi (gpgme_op_createkey): Clarify the meaning of the
'expire' parameter.
(GPGME_CREATE_NOEXPIRE): Document new flag.
(gpgme_op_createsubkey): Clarify the meaning of the 'expire'
parameter.
* src/engine-gpg.c (gpg_add_algo_usage_expire): Fix handling of the
expiration time.
* src/gpgme.h.in (GPGME_CREATE_NOEXPIRE): New macro.
--

Previously, the documentation stated that the expiration time was an
absolute timestamp.  However, this value was passed using the
'seconds=N' syntax to GnuPG which specifies the expiration time in
seconds relative to the creation time.  Fix the documentation.

Furthermore, the documentation stated that using 0 results in keys
that do not expire.  This was communicated to GnuPG by using the
implicit default.  However, as of GnuPG 2.1.17, the default was
changed to create keys that expire within a reasonable timespan.

Fix this discrepancy by aligning the behavior with recent GnuPG
versions: 0 means use a reasonable default, and introduce a flag that
can be used to create keys that do not expire.  Communicate this
explicitly to GnuPG.

Signed-off-by: Justus Winter <[email protected]>

1 files changed, 19 insertions, 14 deletions

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index e058fba6..c088cfed 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -3612,13 +3612,14 @@ primary key plus a secondary key (subkey).
 
 @var{reserved} must be set to zero.
 
-@var{expires} can be set to the number of seconds since Epoch of the
-desired expiration date in UTC for the new key.   Using 0 does not
-set an expiration date.  Note that this parameter takes an unsigned long
-value and not a @code{time_t} to avoid problems on systems which use a
-signed 32 bit @code{time_t}.  Note further that the OpenPGP protocol
-uses 32 bit values for timestamps and thus can only encode dates up to
-the year 2106.
+@var{expires} specifies the expiration time in seconds.  If you supply
+0, a reasonable expiration time is chosen.  Use the flag
+@code{GPGME_CREATE_NOEXPIRE} to create keys that do not expire.  Note
+that this parameter takes an unsigned long value and not a
+@code{time_t} to avoid problems on systems which use a signed 32 bit
+@code{time_t}.  Note further that the OpenPGP protocol uses 32 bit
+values for timestamps and thus can only encode dates up to the year
+2106.
 
 @var{extrakey} is currently not used and must be set to @code{NULL}.
 A future version of GPGME may use this parameter to create X.509 keys.
@@ -3660,6 +3661,9 @@ The engine does not allow the creation of a key with a user ID
 already existing in the local key database.  This flag can be used to
 override this check.
 
+@item GPGME_CREATE_NOEXPIRE
+Request generation of keys that do not expire.
+
 @end table
 
 After the operation completed successfully, information about the
@@ -3719,13 +3723,14 @@ able to already handle such future algorithms.
 
 @var{reserved} must be set to zero.
 
-@var{expires} can be set to the number of seconds since Epoch of the
-desired expiration date in UTC for the new subkey.   Using 0 does not
-set an expiration date.  Note that this parameter takes an unsigned long
-value and not a @code{time_t} to avoid problems on systems which use a
-signed 32 bit @code{time_t}.  Note further that the OpenPGP protocol
-uses 32 bit values for timestamps and thus can only encode dates up to
-the year 2106.
+@var{expires} specifies the expiration time in seconds.  If you supply
+0, a reasonable expiration time is chosen.  Use the flag
+@code{GPGME_CREATE_NOEXPIRE} to create keys that do not expire.  Note
+that this parameter takes an unsigned long value and not a
+@code{time_t} to avoid problems on systems which use a signed 32 bit
+@code{time_t}.  Note further that the OpenPGP protocol uses 32 bit
+values for timestamps and thus can only encode dates up to the year
+2106.
 
 @var{flags} takes the same values as described above for
 @code{gpgme_op_createkey}.