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)] 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 unknown; /* This might be the length of a key that is rarely or never present. */
  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                 nstring domain_name; /* DNS name of the domain which generated the key. */
  49                 nstring forest_name; /* DNS name of the forest which generated the key. */
  50         } KeyEnvelope;
  51
  52         typedef [public] struct {
  53                 uint32 version; /* The version (msKds-Version) of the root key ADM element. */
  54                 [value(0x4b53444b)] uint32 magic; /* ‘KDSK’ */
  55                 EnvelopeFlags flags;
  56                 uint32 l0_index;
  57                 [range(0, 31)] uint32 l1_index;
  58                 [range(0, 31)] uint32 l2_index;
  59                 GUID root_key_id;
  60                 [value(2 * ndr_charset_length(kdf_algorithm, CH_UTF16))] uint32 kdf_algorithm_len;
  61                 uint32 kdf_parameters_len;
  62                 [value(2 * ndr_charset_length(secret_agreement_algorithm, CH_UTF16))] uint32 secret_agreement_algorithm_len;
  63                 uint32 secret_agreement_parameters_len;
  64                 uint32 private_key_len;
  65                 uint32 public_key_len;
  66                 uint32 l1_key_len;
  67                 uint32 l2_key_len;
  68                 [value(2 * ndr_charset_length(domain_name, CH_UTF16))] uint32 domain_name_len;
  69                 [value(2 * ndr_charset_length(forest_name, CH_UTF16))] uint32 forest_name_len;
  70                 nstring kdf_algorithm;
  71                 uint8 kdf_parameters[kdf_parameters_len];
  72                 nstring secret_agreement_algorithm;
  73                 uint8 secret_agreement_parameters[secret_agreement_parameters_len];
  74                 nstring domain_name; /* DNS name of the domain which generated the key. */
  75                 nstring forest_name; /* DNS name of the forest which generated the key. */
  76                 [flag(NDR_SECRET)] uint8 l1_key[l1_key_len];
  77                 [flag(NDR_SECRET)] uint8 l2_key[l2_key_len];
  78         } GroupKeyEnvelope;
  79
  80         typedef [public] struct {
  81                 [value(0)] uint32 padding_0;
  82                 [value(1)] uint32 padding_1;
  83                 [value(2 * ndr_charset_length(hash_algorithm, CH_UTF16))] uint32 hash_algorithm_len;
  84                 [value(0)] uint32 padding_2;
  85                 nstring hash_algorithm;
  86         } KdfParameters;
  87
  88         typedef [public] struct {
  89                 /*
  90                  * Twelve bytes account for the length, magic number, and key
  91                  * length; the remaining bytes cover the two arrays of
  92                  * ‘key_length’ bytes each.
  93                  */
  94                 [value(12 + 2 * key_length)] uint32 length;
  95                 [value(0x4d504844)] uint32 magic; /* ‘DHPM’ */
  96                 uint32 key_length;
  97                 uint8 field_order[key_length];
  98                 uint8 generator[key_length];
  99         } FfcDhParameters;
 100
 101         HRESULT gkdi_GetKey(
 102                 [in] uint32 target_sd_len,
 103                 [in] [size_is(target_sd_len)] [ref] char *target_sd,
 104                 [in] [unique] GUID* root_key_id,
 105                 [in] int32 l0_key_id,
 106                 [in] int32 l1_key_id,
 107                 [in] int32 l2_key_id,
 108                 [out] uint32 *out_len,
 109                 [out] [size_is(,*out_len)] uint8** out
 110         );
 111 }