librpc/idl/gkdi.idl

   1 /*
   2  * Type definitions for Group Key Distribution Service
   3  *
   4  * The below was initially obtained from MS-GKDI which is copyright © 2021
   5  * Microsoft Corporation as permitted by the Open Specifications terms
   6  * reproduced in IDL_LICENCE.txt.
   7  *
   8  * Only GetKey() was provided as IDL. The definitions of GroupKeyEnvelope,
   9  * KdfParameters, and FfcDhParameters were derived from structure diagrams.
  10  * KeyEnvelope was undocumented.
  11  */
  12
  13 #include "idl_types.h"
  14
  15 import "misc.idl";
  16
  17 [
  18   uuid("b9785960-524f-11df-8b6d-83dcded72085"),
  19   endpoint("ncacn_np:[\\pipe\\lsass]", "ncacn_ip_tcp:", "ncalrpc:"),
  20   version(1.0),
  21   pointer_default(unique),
  22   helpstring("Active Directory Group Key Distribution Service")
  23 ]
  24 interface gkdi
  25 {
  26         /* Public structures. */
  27
  28         typedef [bitmap32bit] bitmap {
  29                 ENVELOPE_FLAG_TRANSPORTING_PUBLIC_KEY = 0x00000001,
  30                 ENVELOPE_FLAG_KEY_MAY_ENCRYPT_NEW_DATA = 0x00000002
  31         } EnvelopeFlags;
  32
  33         /*
  34          * This is an undocumented type. It is similar to GroupKeyEnvelope, but
  35          * with some fields omitted.
  36          */
  37         typedef [public] struct {
  38                 uint32 version;
  39                 [value(0x4b53444b), range(0x4b53444b, 0x4b53444b)] uint32 magic; /* ‘KDSK’ */
  40                 EnvelopeFlags flags;
  41                 uint32 l0_index;
  42                 [range(0, 31)] uint32 l1_index;
  43                 [range(0, 31)] uint32 l2_index;
  44                 GUID root_key_id;
  45                 uint32 additional_info_len;
  46                 [value(2 * ndr_charset_length(domain_name, CH_UTF16))] uint32 domain_name_len;
  47                 [value(2 * ndr_charset_length(forest_name, CH_UTF16))] uint32 forest_name_len;
  48                 /*
  49                  * https://lists.samba.org/archive/cifs-protocol/2023-December/004170.html
  50                  * This is the public key blob of an ephemeral public key used in secret
  51                  * agreement, or a random number used in deriving a symmetric key.
  52                  */
  53                 [flag(NDR_SECRET)] uint8 additional_info[additional_info_len];
  54                 nstring domain_name; /* DNS name of the domain which generated the key. */
  55                 nstring forest_name; /* DNS name of the forest which generated the key. */
  56         } KeyEnvelope;
  57
  58         typedef [public] struct {
  59                 uint32 version; /* The version (msKds-Version) of the root key ADM element. */
  60                 [value(0x4b53444b), range(0x4b53444b, 0x4b53444b)] uint32 magic; /* ‘KDSK’ */
  61                 EnvelopeFlags flags;
  62                 uint32 l0_index;
  63                 [range(0, 31)] uint32 l1_index;
  64                 [range(0, 31)] uint32 l2_index;
  65                 GUID root_key_id;
  66                 [value(2 * ndr_charset_length(kdf_algorithm, CH_UTF16))] uint32 kdf_algorithm_len;
  67                 uint32 kdf_parameters_len;
  68                 [value(2 * ndr_charset_length(secret_agreement_algorithm, CH_UTF16))] uint32 secret_agreement_algorithm_len;
  69                 uint32 secret_agreement_parameters_len;
  70                 uint32 private_key_len;
  71                 uint32 public_key_len;
  72                 uint32 l1_key_len;
  73                 uint32 l2_key_len;
  74                 [value(2 * ndr_charset_length(domain_name, CH_UTF16))] uint32 domain_name_len;
  75                 [value(2 * ndr_charset_length(forest_name, CH_UTF16))] uint32 forest_name_len;
  76                 nstring kdf_algorithm;
  77                 uint8 kdf_parameters[kdf_parameters_len];
  78                 nstring secret_agreement_algorithm;
  79                 uint8 secret_agreement_parameters[secret_agreement_parameters_len];
  80                 nstring domain_name; /* DNS name of the domain which generated the key. */
  81                 nstring forest_name; /* DNS name of the forest which generated the key. */
  82                 [flag(NDR_SECRET)] uint8 l1_key[l1_key_len];
  83                 [flag(NDR_SECRET)] uint8 l2_key[l2_key_len];
  84         } GroupKeyEnvelope;
  85
  86         typedef [public] struct {
  87                 [value(0)] uint32 padding_0;
  88                 [value(1)] uint32 padding_1;
  89                 [value(2 * ndr_charset_length(hash_algorithm, CH_UTF16))] uint32 hash_algorithm_len;
  90                 [value(0)] uint32 padding_2;
  91                 nstring hash_algorithm;
  92         } KdfParameters;
  93
  94         typedef [public] struct {
  95                 /*
  96                  * Twelve bytes account for the length, magic number, and key
  97                  * length; the remaining bytes cover the two arrays of
  98                  * ‘key_length’ bytes each.
  99                  */
 100                 [value(12 + 2 * key_length)] uint32 length;
 101                 [value(0x4d504844), range(0x4d504844, 0x4d504844)] uint32 magic; /* ‘DHPM’ */
 102                 uint32 key_length;
 103                 uint8 field_order[key_length];
 104                 uint8 generator[key_length];
 105         } FfcDhParameters;
 106
 107         typedef [public] struct {
 108                 GUID guid;
 109                 int32 l0_idx;
 110                 int32 l1_idx;
 111                 int32 l2_idx;
 112                 [flag(NDR_REMAINING)] DATA_BLOB target_security_descriptor;
 113         } GkdiDerivationCtx;
 114
 115         HRESULT gkdi_GetKey(
 116                 [in] uint32 target_sd_len,
 117                 [in] [size_is(target_sd_len)] [ref] char *target_sd,
 118                 [in] [unique] GUID* root_key_id,
 119                 [in] int32 l0_key_id,
 120                 [in] int32 l1_key_id,
 121                 [in] int32 l2_key_id,
 122                 [out] uint32 *out_len,
 123                 [out] [size_is(,*out_len)] uint8** out
 124         );
 125 }