doc/html/_sources/formats/ccache_file_format.txt

   1 .. _ccache_file_format:
   2
   3 Credential cache file format
   4 ============================
   5
   6 There are four versions of the file format used by the FILE credential
   7 cache type.  The first byte of the file always has the value 5, and
   8 the value of the second byte contains the version number (1 through
   9 4).  Versions 1 and 2 of the file format use native byte order for integer
  10 representations.  Versions 3 and 4 always use big-endian byte order.
  11
  12 After the two-byte version indicator, the file has three parts: the
  13 header (in version 4 only), the default principal name, and a sequence
  14 of credentials.
  15
  16
  17 Header format
  18 -------------
  19
  20 The header appears only in format version 4.  It begins with a 16-bit
  21 integer giving the length of the entire header, followed by a sequence
  22 of fields.  Each field consists of a 16-bit tag, a 16-bit length, and
  23 a value of the given length.  A file format implementation should
  24 ignore fields with unknown tags.
  25
  26 At this time there is only one defined header field.  Its tag value is
  27 1, its length is always 8, and its contents are two 32-bit integers
  28 giving the seconds and microseconds of the time offset of the KDC
  29 relative to the client.  Adding this offset to the current time on the
  30 client should give the current time on the KDC, if that offset has not
  31 changed since the initial authentication.
  32
  33
  34 .. _cache_principal_format:
  35
  36 Principal format
  37 ----------------
  38
  39 The default principal is marshalled using the following informal
  40 grammar::
  41
  42     principal ::=
  43         name type (32 bits) [omitted in version 1]
  44         count of components (32 bits) [includes realm in version 1]
  45         realm (data)
  46         component1 (data)
  47         component2 (data)
  48         ...
  49
  50     data ::=
  51         length (32 bits)
  52         value (length bytes)
  53
  54 There is no external framing on the default principal, so it must be
  55 parsed according to the above grammar in order to find the sequence of
  56 credentials which follows.
  57
  58
  59 .. _ccache_credential_format:
  60
  61 Credential format
  62 -----------------
  63
  64 The credential format uses the following informal grammar (referencing
  65 the ``principal`` and ``data`` types from the previous section)::
  66
  67     credential ::=
  68         client (principal)
  69         server (principal)
  70         keyblock (keyblock)
  71         authtime (32 bits)
  72         starttime (32 bits)
  73         endtime (32 bits)
  74         renew_till (32 bits)
  75         is_skey (1 byte, 0 or 1)
  76         ticket_flags (32 bits)
  77         addresses (addresses)
  78         authdata (authdata)
  79         ticket (data)
  80         second_ticket (data)
  81
  82     keyblock ::=
  83         enctype (16 bits) [repeated twice in version 3]
  84         data
  85
  86     addresses ::=
  87         count (32 bits)
  88         address1
  89         address2
  90         ...
  91
  92     address ::=
  93         addrtype (16 bits)
  94         data
  95
  96     authdata ::=
  97         count (32 bits)
  98         authdata1
  99         authdata2
 100         ...
 101
 102     authdata ::=
 103         ad_type (16 bits)
 104         data
 105
 106 There is no external framing on a marshalled credential, so it must be
 107 parsed according to the above grammar in order to find the next
 108 credential.  There is also no count of credentials or marker at the
 109 end of the sequence of credentials; the sequence ends when the file
 110 ends.
 111
 112
 113 Credential cache configuration entries
 114 --------------------------------------
 115
 116 Configuration entries are encoded as credential entries.  The client
 117 principal of the entry is the default principal of the cache.  The
 118 server principal has the realm ``X-CACHECONF:`` and two or three
 119 components, the first of which is ``krb5_ccache_conf_data``.  The
 120 server principal's second component is the configuration key.  The
 121 third component, if it exists, is a principal to which the
 122 configuration key is associated.  The configuration value is stored in
 123 the ticket field of the entry.  All other entry fields are zeroed.
 124
 125 Programs using credential caches must be aware of configuration
 126 entries for several reasons:
 127
 128 * A program which displays the contents of a cache should not
 129   generally display configuration entries.
 130
 131 * The ticket field of a configuration entry is not (usually) a valid
 132   encoding of a Kerberos ticket.  An implementation must not treat the
 133   cache file as malformed if it cannot decode the ticket field.
 134
 135 * Configuration entries have an endtime field of 0 and might therefore
 136   always be considered expired, but they should not be treated as
 137   unimportant as a result.  For instance, a program which copies
 138   credentials from one cache to another should not omit configuration
 139   entries because of the endtime.
 140
 141 The following configuration keys are currently used in MIT krb5:
 142
 143 fast_avail
 144     The presence of this key with a non-empty value indicates that the
 145     KDC asserted support for FAST (see :rfc:`6113`) during the initial
 146     authentication, using the negotiation method described in
 147     :rfc:`6806` section 11.  This key is not associated with any
 148     principal.
 149
 150 pa_config_data
 151     The value of this key contains a JSON object representation of
 152     parameters remembered by the preauthentication mechanism used
 153     during the initial authentication.  These parameters may be used
 154     when refreshing credentials.  This key is associated with the
 155     server principal of the initial authentication (usually the local
 156     krbtgt principal of the client realm).
 157
 158 pa_type
 159     The value of this key is the ASCII decimal representation of the
 160     preauth type number used during the initial authentication.  This
 161     key is associated with the server principal of the initial
 162     authentication.
 163
 164 proxy_impersonator
 165     The presence of this key indicates that the cache is a synthetic
 166     delegated credential for use with S4U2Proxy.  The value is the
 167     name of the intermediate service whose TGT can be used to make
 168     S4U2Proxy requests for target services.  This key is not
 169     associated with any principal.
 170
 171 refresh_time
 172     The presence of this key indicates that the cache was acquired by
 173     the GSS mechanism using a client keytab.  The value is the ASCII
 174     decimal representation of a timestamp at which the GSS mechanism
 175     should attempt to refresh the credential cache from the client
 176     keytab.