lib/hdb/hdb.asn1

   1 -- $Id$
   2 HDB DEFINITIONS ::=
   3 BEGIN
   4
   5 IMPORTS EncryptionKey, KerberosTime, Principal FROM krb5;
   6
   7 hdb_db_format INTEGER ::= 2     -- format of database,
   8                                 -- update when making changes
   9
  10 -- these must have the same value as the pa-* counterparts
  11 hdb-pw-salt     INTEGER ::= 3
  12 hdb-afs3-salt   INTEGER ::= 10
  13
  14 Salt ::= SEQUENCE {
  15         type[0]         INTEGER (0..4294967295),
  16         salt[1]         OCTET STRING,
  17         opaque[2]       OCTET STRING OPTIONAL
  18 }
  19
  20 Key ::= SEQUENCE {
  21         mkvno[0]        INTEGER (0..4294967295) OPTIONAL, -- master key version number
  22         key[1]          EncryptionKey,
  23         salt[2]         Salt OPTIONAL
  24 }
  25
  26 Event ::= SEQUENCE {
  27         time[0]         KerberosTime,
  28         principal[1]    Principal OPTIONAL
  29 }
  30
  31 HDBFlags ::= BIT STRING {
  32         initial(0),                     -- require as-req
  33         forwardable(1),                 -- may issue forwardable
  34         proxiable(2),                   -- may issue proxiable
  35         renewable(3),                   -- may issue renewable
  36         postdate(4),                    -- may issue postdatable
  37         server(5),                      -- may be server
  38         client(6),                      -- may be client
  39         invalid(7),                     -- entry is invalid
  40         require-preauth(8),             -- must use preauth
  41         change-pw(9),                   -- change password service
  42         require-hwauth(10),             -- must use hwauth
  43         ok-as-delegate(11),             -- as in TicketFlags
  44         user-to-user(12),               -- may use user-to-user auth
  45         immutable(13),                  -- may not be deleted
  46         trusted-for-delegation(14),     -- Trusted to print forwardabled tickets
  47         allow-kerberos4(15),            -- Allow Kerberos 4 requests
  48         allow-digest(16),               -- Allow digest requests
  49         locked-out(17),                 -- Account is locked out,
  50                                         -- authentication will be denied
  51         require-pwchange(18),           -- require a passwd change
  52
  53         materialize(19),                -- store even if within virtual namespace
  54         virtual-keys(20),               -- entry     stored; keys mostly derived
  55         virtual(21),                    -- entry not stored; keys always derived
  56         synthetic(22),                  -- entry not stored; for PKINIT
  57         no-auth-data-reqd(23),          -- omit PAC from service tickets
  58         auth-data-reqd(24),             -- include PAC in service tickets
  59
  60         force-canonicalize(30),         -- force the KDC to return the canonical
  61                                         -- principal irrespective of the setting
  62                                         -- of the canonicalize KDC option
  63                                         -- (principals cannot have this flag
  64                                         -- set when stored into the HDB)
  65         do-not-store(31)                -- Not to be modified and stored in HDB
  66 }
  67
  68 GENERATION ::= SEQUENCE {
  69         time[0]         KerberosTime,                   -- timestamp
  70         usec[1]         INTEGER (0..4294967295),        -- microseconds
  71         gen[2]          INTEGER (0..4294967295)         -- generation number
  72 }
  73
  74 HDB-Ext-PKINIT-acl ::= SEQUENCE OF SEQUENCE {
  75         subject[0]      UTF8String,
  76         issuer[1]       UTF8String OPTIONAL,
  77         anchor[2]       UTF8String OPTIONAL
  78 }
  79
  80 HDB-Ext-PKINIT-hash ::= SEQUENCE OF SEQUENCE {
  81         digest-type[0] OBJECT IDENTIFIER,
  82         digest[1] OCTET STRING
  83 }
  84
  85 HDB-Ext-PKINIT-cert ::= SEQUENCE OF SEQUENCE {
  86         cert[0] OCTET STRING
  87 }
  88
  89 HDB-Ext-Constrained-delegation-acl ::= SEQUENCE OF Principal
  90
  91 -- hdb-ext-referrals ::= PA-SERVER-REFERRAL-DATA
  92
  93 HDB-Ext-Lan-Manager-OWF ::= OCTET STRING
  94
  95 HDB-Ext-Password ::= SEQUENCE {
  96         mkvno[0]        INTEGER (0..4294967295) OPTIONAL, -- master key version number
  97         password        OCTET STRING
  98 }
  99
 100 HDB-Ext-Aliases ::= SEQUENCE {
 101         case-insensitive[0]     BOOLEAN, -- case insensitive name allowed
 102         aliases[1]              SEQUENCE OF Principal -- all names, inc primary
 103 }
 104
 105 Keys ::= SEQUENCE OF Key
 106
 107 HDB_keyset ::= SEQUENCE {
 108         kvno[0]         INTEGER (0..4294967295),
 109         keys[1]         Keys,
 110         set-time[2]     KerberosTime OPTIONAL,  -- time this keyset was created/set
 111         ...
 112 }
 113
 114 HDB-Ext-KeySet ::= SEQUENCE OF HDB_keyset
 115
 116 --
 117 -- We need a function of current (or given, but it will always be current) time
 118 -- and a base hdb_entry or its HDB-Ext-KeyRotation and service ticket lifetime,
 119 -- that outputs a sequence of {kvno, set_time, max_life} representing past keys
 120 -- (up to one per past and current KeyRotation), current keys (for the current
 121 -- KeyRotation), up to one future key for the current KeyRotation, and up to
 122 -- one future key for the _next_ (future) KeyRotation if there is one.
 123 --
 124 -- We have to impose constraints on new KeyRotation elements of
 125 -- HDB-Ext-KeyRotation.
 126 --
 127 -- So virtual keysets (keytabs) will contain:
 128 --
 129 --  - up to one past   keyset for all KeyRotation periods that are "applicable"
 130 --  - the   current    keyset for all KeyRotation periods that are "applicable"
 131 --  - up to one future keyset for all KeyRotation periods that are "applicable"
 132 --
 133 -- An applicable KeyRotation period is:
 134 --
 135 --  - the KeyRotation whose `epoch` is a) in the past and b) nearest to the
 136 --    current time - we call this the current KeyRotation
 137 --  - a   KeyRotation whose `epoch` is nearest but in the past of the current
 138 --    one
 139 --  - a   KeyRotation whose `epoch` is nearest but in the future of the current
 140 --    one
 141 --
 142 -- A service principal's max ticket life will be bounded by half the current
 143 -- key rotation period.
 144 --
 145 -- Note: There can be more than one applicable past KeyRotation, and more than
 146 --       one applicable KeyRotation.  We might not want to permit this.
 147 --       However, it's probably easier to permit it, though we might not test
 148 --       end-to-end.
 149 --
 150 -- Testing:
 151 --
 152 --  - We should have standalone unit tests for all these pure functions.
 153 --
 154 --  - We should have a test that uses kadm5 and GSS to test against a KDC using
 155 --    small key rotation periods on the order of seconds, with back-off in case
 156 --    of losing a race condition.
 157 --
 158 KeyRotationFlags ::= BIT STRING {
 159         deleted(0),     -- if set on a materialized principal, this will mean
 160                         -- the principal does not exist
 161                         -- if set on a namespace, this will mean that
 162                         -- only materialized principal below it exist
 163         parent(1)       -- if set on a materialized principal, this will mean
 164                         -- that the keys for kvnos in this KeyRotation spec
 165                         -- will be derived from the parent's base keys and
 166                         -- corresponding KeyRotation spec
 167                         -- if set on a namespace, this flag will be ignored
 168                         -- (or we could support nested namespaces?)
 169 }
 170 KeyRotation ::= SEQUENCE {
 171         -- base-kvno is always computed at set time and set for the principal,
 172         -- and is never subject to admin choice.  The base-kvno is that of the
 173         -- current kvno at that period's `from` given the previous period.
 174         --
 175         -- Also, insertion of KeyRotation elements before existing ones (in
 176         -- time) is never permitted, and all new KeyRotation elements must be
 177         -- in the future relative to existing ones.
 178         --
 179         -- HDB-Ext-KeyRotation will always be sorted (as stored) by `from`, in
 180         -- descending order.
 181         --
 182         -- Max service ticket lifetime will be constrained to no more than half
 183         -- the period of the the applicable KeyRotation elements.
 184         --
 185         flags[0]        KeyRotationFlags,
 186         epoch[1]        KerberosTime,           -- start of this period
 187         period[2]       INTEGER(0..4294967295), -- key rotation seconds
 188         base-kvno[3]    INTEGER(0..4294967295), -- starting from this kvno
 189         base-key-kvno[4]INTEGER(0..4294967295), -- kvno of base-key
 190         ...
 191 }
 192
 193 HDB-Ext-KeyRotation ::= SEQUENCE SIZE (1..3) OF KeyRotation
 194
 195 HDB-extension ::= SEQUENCE {
 196         mandatory[0]    BOOLEAN,        -- kdc MUST understand this extension,
 197                                         --   if not the whole entry must
 198                                         --   be rejected
 199         data[1]          CHOICE {
 200                 pkinit-acl[0]                   HDB-Ext-PKINIT-acl,
 201                 pkinit-cert-hash[1]             HDB-Ext-PKINIT-hash,
 202                 allowed-to-delegate-to[2]       HDB-Ext-Constrained-delegation-acl,
 203 --              referral-info[3]                HDB-Ext-Referrals,
 204                 lm-owf[4]                       HDB-Ext-Lan-Manager-OWF,
 205                 password[5]                     HDB-Ext-Password,
 206                 aliases[6]                      HDB-Ext-Aliases,
 207                 last-pw-change[7]               KerberosTime,
 208                 pkinit-cert[8]                  HDB-Ext-PKINIT-cert,
 209                 hist-keys[9]                    HDB-Ext-KeySet,
 210                 hist-kvno-diff-clnt[10]         INTEGER (0..4294967295),
 211                 hist-kvno-diff-svc[11]          INTEGER (0..4294967295),
 212                 policy[12]                      UTF8String,
 213                 principal-id[13]                INTEGER(-9223372036854775808..9223372036854775807),
 214                 key-rotation[14]                HDB-Ext-KeyRotation,
 215                 krb5-config[15]                 OCTET STRING,
 216                 ...
 217         },
 218         ...
 219 }
 220
 221 HDB-extensions ::= SEQUENCE OF HDB-extension
 222
 223 -- Just for convenience, for encoding this as TL data in lib/kadm5
 224 HDB-EncTypeList ::= SEQUENCE OF INTEGER (0..4294967295)
 225
 226 HDB_entry ::= SEQUENCE {
 227         principal[0]    Principal  OPTIONAL, -- this is optional only
 228                                              -- for compatibility with libkrb5
 229         kvno[1]         INTEGER (0..4294967295),
 230         keys[2]         Keys,
 231         created-by[3]   Event,
 232         modified-by[4]  Event OPTIONAL,
 233         valid-start[5]  KerberosTime OPTIONAL,
 234         valid-end[6]    KerberosTime OPTIONAL,
 235         pw-end[7]       KerberosTime OPTIONAL,
 236         max-life[8]     INTEGER (0..4294967295) OPTIONAL,
 237         max-renew[9]    INTEGER (0..4294967295) OPTIONAL,
 238         flags[10]       HDBFlags,
 239         etypes[11]      HDB-EncTypeList OPTIONAL,
 240         generation[12]  GENERATION OPTIONAL,
 241         extensions[13]  HDB-extensions OPTIONAL
 242 }
 243
 244 HDB_entry_alias ::= [APPLICATION 0] SEQUENCE {
 245         principal[0]    Principal  OPTIONAL
 246 }
 247
 248 HDB-EntryOrAlias ::= CHOICE {
 249         entry       HDB_entry,
 250         alias       HDB_entry_alias
 251 }
 252
 253 END