vendor/krb5/1.16vendor/krb5

3 files changed, 48 insertions, 0 deletions

diff --git a/doc/appdev/gssapi.rst b/doc/appdev/gssapi.rst
index 0258f793b99b..c39bbddb9738 100644
--- a/doc/appdev/gssapi.rst
+++ b/doc/appdev/gssapi.rst
@@ -312,6 +312,25 @@ issue a ticket from the client to the target service.  The GSSAPI
 library will then use this ticket to authenticate to the target
 service.
 
+If an application needs to find out whether a credential it holds is a
+proxy credential and the name of the intermediate service, it can
+query the credential with the **GSS_KRB5_GET_CRED_IMPERSONATOR** OID
+(new in release 1.16, declared in ``<gssapi/gssapi_krb5.h>``) using
+the gss_inquire_cred_by_oid extension (declared in
+``<gssapi/gssapi_ext.h>``)::
+
+    OM_uint32 gss_inquire_cred_by_oid(OM_uint32 *minor_status,
+                                      const gss_cred_id_t cred_handle,
+                                      gss_OID desired_object,
+                                      gss_buffer_set_t *data_set);
+
+If the call succeeds and *cred_handle* is a proxy credential,
+*data_set* will be set to a single-element buffer set containing the
+unparsed principal name of the intermediate service.  If *cred_handle*
+is not a proxy credential, *data_set* will be set to an empty buffer
+set.  If the library does not support the query,
+gss_inquire_cred_by_oid will return **GSS_S_UNAVAILABLE**.
+
 
 AEAD message wrapping
 ---------------------
diff --git a/doc/appdev/index.rst b/doc/appdev/index.rst
index 3d62045ca870..961bb1e9e23a 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 000000000000..bc4122dad0a4
--- /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.