krb5 commit: Add y2038 documentation

[Greg Hudson]

https://github.com/krb5/krb5/commit/85d64c43dbf7a7faa56a1999494cdfa49e8bd2c9
commit 85d64c43dbf7a7faa56a1999494cdfa49e8bd2c9
Author: Greg Hudson <ghudson at mit.edu>
Date:   Thu May 4 17:03:35 2017 -0400

    Add y2038 documentation
    
    ticket: 8352

 doc/appdev/index.rst |    1 +
 doc/appdev/y2038.rst |   28 ++++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 0 deletions(-)

diff --git a/doc/appdev/index.rst b/doc/appdev/index.rst
index 3d62045..961bb1e 100644
--- a/doc/appdev/index.rst
+++ b/doc/appdev/index.rst
@@ -5,6 +5,7 @@ For application developers
    :maxdepth: 1
 
    gssapi.rst
+   y2038.rst
    h5l_mit_apidiff.rst
    init_creds.rst
    princ_handle.rst
diff --git a/doc/appdev/y2038.rst b/doc/appdev/y2038.rst
new file mode 100644
index 0000000..bc4122d
--- /dev/null
+++ b/doc/appdev/y2038.rst
@@ -0,0 +1,28 @@
+Year 2038 considerations for uses of krb5_timestamp
+===================================================
+
+POSIX time values, which measure the number of seconds since January 1
+1970, will exceed the maximum value representable in a signed 32-bit
+integer in January 2038.  This documentation describes considerations
+for consumers of the MIT krb5 libraries.
+
+Applications or libraries which use libkrb5 and consume the timestamps
+included in credentials or other structures make use of the
+:c:type:`krb5_timestamp` type.  For historical reasons, krb5_timestamp
+is a signed 32-bit integer, even on platforms where a larger type is
+natively used to represent time values.  To behave properly for time
+values after January 2038, calling code should cast krb5_timestamp
+values to uint32_t, and then to time_t::
+
+    (time_t)(uint32_t)timestamp
+
+Used in this way, krb5_timestamp values can represent time values up
+until February 2106, provided that the platform uses a 64-bit or
+larger time_t type.  This usage will also remain safe if a later
+version of MIT krb5 changes krb5_timestamp to an unsigned 32-bit
+integer.
+
+The GSSAPI only uses representations of time intervals, not absolute
+times.  Callers of the GSSAPI should require no changes to behave
+correctly after January 2038, provided that they use MIT krb5 release
+1.16 or later.