Функция DRMEnumerateLicense (msdrm.h)

Статья
03/08/2023

[Пакет SDK ДЛЯ AD RMS с функциональными возможностями, предоставляемыми

клиент в Msdrm.dll доступен для использования в Windows Server 2008, Windows Vista, Windows Server 2008 R2, Windows 7, Windows Server 2012 и Windows 8. Он может быть изменен или

недоступно в последующих версиях. Вместо этого используйте пакет SDK 2.1 служб Active Directory Rights Management.

который использует функциональные возможности, предоставляемые клиентом в Msipc.dll.]

Функция DRMEnumerateLicense перечисляет действительные лицензии, сертификаты компьютеров или сертификаты учетной записи прав, списки отзыва для текущего пользователя или шаблоны лицензий выдачи.

Синтаксис

DRMEXPORT HRESULT UDAPICALL DRMEnumerateLicense(
  [in]      DRMHSESSION hSession,
  [in]      UINT        uFlags,
  [in]      UINT        uIndex,
  [in, out] BOOL        *pfSharedFlag,
  [in, out] UINT        *puCertificateDataLen,
  [out]     PWSTR       wszCertificateData
);

Параметры

[in] hSession

Дескриптор для сеанса хранения данных клиента или лицензий. Тип сеанса, передаваемого в hSession , зависит от типа перечисляемого элемента. Для перечисления лицензий конечных пользователей используйте сеанс хранилища лицензий, созданный с помощью функции DRMCreateLicenseStorageSession . Для перечисления сертификатов компьютеров, учетных записей прав, сертификатов лицензиара клиента или шаблонов лицензий на выдачу используйте сеанс клиента, созданный с помощью функции DRMCreateClientSession . Используйте любой тип дескриптора для перечисления списков отзыва.

[in] uFlags

Содержит одно или несколько следующих значений, указывающих, какие типы элементов следует перечислить, и другие параметры.

Следующий флаг можно объединить с другими флагами для указания дополнительных параметров перечисления.

DRM_EL_EXPIRED

Используйте это значение с флагами, используемыми для перечисления идентификаторов, таких как DRM_EL_GROUPIDENTITY_LID, для перечисления просроченных элементов указанного типа. Это упрощает удаление просроченных элементов из хранилища лицензий, сохранение небольшого размера хранилища и повышение производительности.

Следующие флаги используются для перечисления лицензий конечных пользователей.

DRM_EL_EUL

Перечисление лицензий конечных пользователей для текущего сеанса хранилища лицензий.

DRM_EL_EUL_LID

Перечисление идентификаторов лицензий конечных пользователей для текущего сеанса хранилища лицензий. Идентификатор каждой лицензии конечного пользователя возвращается в параметре wszCertificateData .

Следующие флаги используются для перечисления сертификатов лицензиара клиента. Эти флаги позволяют приложению перечислять через лицензиаров в лицензиях, доступных текущему пользователю.

DRM_EL_CLIENTLICENSOR

Перечисление всех сертификатов лицензиара клиента в хранилище сертификатов .

DRM_EL_CLIENTLICENSOR_LID

Перечисление идентификаторов сертификатов лицензиара клиента для переданного сеанса клиента. Идентификатор сертификата лицензиара клиента возвращается в параметре wszCertificateData .

DRM_EL_SPECIFIED_CLIENTLICENSOR

Возвращает сертификат лицензиара клиента , соответствующий адресу электронной почты в сеансе клиента.

Следующий флаг используется для перечисления сертификатов компьютера.

DRM_EL_MACHINE

Перечисление выбранного сертификата компьютера.

У каждого пользователя есть два сертификата компьютера. Допустимое значение индекса для сертификатов компьютеров равно нулю или единице.

Примечание Из-за обновлений для включения режима шифрования 2 DRMActivate(machine) запишет два сертификата компьютера в хранилище. Если приложение не выполняет прямые вызовы веб-метода сертификации на сервере RMS, вызывающей приложению не нужно различать два сертификата компьютера. будет использоваться сертификат компьютера, соответствующий режиму шифрования сервера.

Дополнительные сведения см. в статье Длина ключа RSA увеличена до 2048 бит для AD RMS в Windows 7 или Windows Server 2008 R2.

Если метод hSession был создан путем вызова DRMCreateClientSession, возвращаемый сертификат будет получен из хранилища сертификатов для каждого пользователя, а значение, на которое указывает pfSharedFlag , имеет значение FALSE. Если метод hSession был создан путем вызова DRMCreateLicenseStorageSession, значение, на которое указывает pfSharedFlag , является его исходным значением.

Windows Server 2008 R2, Windows 7, Windows Server 2008 с пакетом обновления 2 (SP2), Windows Vista с пакетом обновления 2 (SP2) или Rights Management Services 1.0: Для служб Rights Management Services 1.0 полученный сертификат находится из хранилища компьютера, а значение, на которое указывает pfSharedFlag , имеет значение TRUE; Значение uIndex должно быть равно нулю.

Компьютер необходимо активировать перед указанием этого флага. Если компьютер не активирован, функция вернет E_DRM_NEEDS_MACHINE_ACTIVATION.

Следующие флаги используются для перечисления сертификатов учетной записи прав.

DRM_EL_GROUPIDENTITY

Перечисление сертификатов учетной записи прав для текущего пользователя, выполнившего вход. Сюда входят как общие, так и ограниченные пользователи.

DRM_EL_GROUPIDENTITY_LID

Перечисление идентификаторов сертификатов учетной записи прав для текущего пользователя, выполнившего вход. Сюда входят как общие, так и ограниченные пользователи. Идентификатор сертификатов учетной записи прав будет возвращен в параметре wszCertificateData .

DRM_EL_GROUPIDENTITY_NAME

Перечисление имен учетных записей прав для текущего пользователя.

DRM_EL_SPECIFIED_GROUPIDENTITY

Возвращает сертификаты учетной записи прав для указанного пользователя при создании сеанса клиента с помощью функции DRMCreateClientSession .

Следующие флаги используются для перечисления списков отзыва.

Все сертификаты могут содержать списки отзыва, поэтому вы можете передать сеанс хранения клиента или лицензии в эту функцию. Переданный дескриптор сеанса клиента получает списки отзыва для сертификатов учетной записи прав или сертификатов лицензиара клиента. Переданный дескриптор сеанса хранилища лицензий будет получать списки отзывадля лицензий конечных пользователей.

DRM_EL_REVOCATIONLIST

Перечисление списков отзыва.

DRM_EL_REVOCATIONLIST_LID

Перечисление идентификаторов списка отзыва . Идентификатор списка отзыва будет возвращен в параметре wszCertificateData .

Следующий флаг можно использовать для получения отображаемого имени издателя.

DRM_EL_ISSUERNAME

Этот флаг нельзя использовать с флагом DRM_EL_EXPIRED и должен использоваться с одним из следующих флагов:

DRM_EL_CLIENTLICENSOR
DRM_EL_GROUPIDENTITY
DRM_EL_SPECIFIED_CLIENTLICENSOR
DRM_EL_SPECIFIED_GROUPIDENTITY

Следующие флаги можно использовать для перечисления шаблонов.

DRM_EL_ISSUANCELICENSE_TEMPLATE

Перечисление шаблонов лицензий на выдачу. Этот флаг доступен начиная с Windows Vista с пакетом обновления 1 (SP1) и Windows Server 2008.

DRM_EL_ISSUANCELICENSE_TEMPLATE_LID

Перечисление идентификаторов шаблонов лицензий на выдачу (GUID). Этот флаг доступен начиная с Windows Vista с пакетом обновления 1 (SP1) и Windows Server 2008.

[in] uIndex

Номер индекса извлекаемого сертификата или лицензии. Чтобы начать перечисление, передайте ноль для этого параметра. Чтобы получить последующие лицензии, увеличьте это значение, пока функция не вернет E_DRM_NO_MORE_DATA. Дополнительные сведения см. в подразделе "Примечания".

[in, out] pfSharedFlag

Указатель на значение BOOL , которое получает один (1), если полученная лицензия является общей, или ноль (0), если полученная лицензия не является общей.

[in, out] puCertificateDataLen

Указатель на значение UINT, которое в записи содержит размер буфера wszCertificateData . Этот размер включает завершающий символ NULL. После возврата функции это значение содержит количество символов, скопированных в буфер, включая завершающий пустой символ.

Чтобы получить необходимый размер буфера, передайте значение NULL для wszCertificateData. В это значение будет помещено необходимое количество символов, включая завершающий пустой символ.

[out] wszCertificateData

Указатель на строку Юникода, завершающуюся значением NULL, которая получает лицензию, идентификатор или шаблон в зависимости от того, какие флаги были установлены.

Чтобы получить необходимый размер этого буфера, передайте значение NULL для wszCertificateData. Необходимое количество символов, включая завершающий пустой символ, будет помещено в puCertificateDataLen.

Возвращаемое значение

Если функция завершается успешно, функция возвращает S_OK.

Если функция завершается сбоем, она возвращает значение HRESULT , указывающее на ошибку. Возможные значения включают, помимо прочего, значения из следующего списка. Список распространенных кодов ошибок см. в разделе Общие значения HRESULT.

По умолчанию эта функция перечисляет только неисполненые лицензии, как определено путем сравнения элемента VALIDITYTIME в каждой лицензии с временем создания объекта сеанса. Чтобы включить в перечисление просроченные лицензии, объедините параметр uFlags с DRM_EL_EXPIRED.

Кроме того, если элемент ID в элементе ISSUEDPRINCIPALS лицензии не соответствует идентификатору пользователя, связанному с объектом сеанса, или идентификатор пользователя сеанса не совпадает с идентификатором пользователя, вошедшего в систему, эта функция завершится ошибкой. Дополнительные сведения см. в разделе DRMCreateClientSession.

В следующих разделах рассматривается перечисление различных типов лицензий. При переборе коллекции можно проверить каждую полученную лицензию, вручную проанализировав строку XrML или, в некоторых случаях, привязав к лицензии и используя функции DRMGetBoundLicense* .

Выполните следующие действия, чтобы перечислить лицензию конечного пользователя.

Вызовите DRMCreateLicenseStorageSession, передавая подписанную лицензию на выдачу.
Задайте для параметра uIndex нулевое значение, а для параметра uFlags— DRM_EL_EUL и вызовите DRMEnumerateLicense. Клиент AD RMS получает первый действительный EUL, идентификатор содержимого которого совпадает с идентификатором содержимого лицензии на выдачу, используемой для создания сеанса хранилища лицензий. Однако если лицензия на выдачу была повторно опубликована с тем же идентификатором содержимого, но с разными правами, возвращенное лицензионное соглашение может быть не запрошенным. Если это не так, увеличьте параметр uIndex и снова вызовите DRMEnumerateLicense . Вы можете продолжать итерацию, пока не найдете правильный EUL или функция не вернет E_DRM_NO_MORE_DATA.

Выполните следующие действия, чтобы перечислить сертификат компьютера:

Вызовите DRMCreateClientSession или DRMCreateLicenseStorageSession , чтобы создать объект сеанса. Тип созданного сеанса определяет характер значения, возвращаемого в параметре pfSharedFlag . Дополнительные сведения см. в разделе константы DRM_EL_MACHINE в параметре uFlags .
Задайте для параметра uIndex значение zero или one, а для параметра uFlags— DRM_EL_MACHINE и вызовите DRMEnumerateLicense.

Выполните следующие действия для перечисления сертификатов учетной записи прав (RAC):

Вызовите DRMCreateClientSession , чтобы создать сеанс клиента.
Задайте для параметра uIndex нулевое значение, а для параметра uFlags— DRM_EL_GROUPIDENTITY и вызовите DRMEnumerateLicense.
Проверьте возвращенный RAC. Если он не запрошен, увеличьте uIndex и вызовите DRMEnumerateLicense еще раз. Вы можете продолжать итерацию, пока не найдете правильный RAC или функция не вернет E_DRM_NO_MORE_DATA.

Выполните следующие действия, чтобы перечислить сертификаты лицензиара клиента (CLC):

Вызовите DRMCreateClientSession , чтобы создать сеанс клиента.
Задайте для параметра uIndex нулевое значение, а для параметра uFlags— DRM_EL_CLIENTLICENSOR и вызовите DRMEnumerateLicense.
Проверьте возвращенный CLC. Если он не запрошен, увеличьте uIndex и вызовите DRMEnumerateLicense еще раз. Вы можете продолжать итерацию, пока не найдете правильный CLC или функция не вернет E_DRM_NO_MORE_DATA.

Выполните следующие действия, чтобы перечислить шаблоны лицензий на выдачу.

Вызовите DRMCreateClientSession , чтобы создать сеанс клиента.
Задайте для параметра uIndex нулевое значение, а для параметра uFlags— DRM_EL_ISSUANCELICENSE_TEMPLATE и вызовите DRMEnumerateLicense.
Изучите шаблон. Если он не запрошен, увеличьте uIndex и вызовите DRMEnumerateLicense еще раз. Вы можете продолжать итерацию, пока не найдете правильный шаблон или функция не вернет E_DRM_NO_MORE_DATA.

Выполните следующие действия, чтобы перечислить списки отзыва.

Вызовите DRMCreateClientSession или DRMCreateLicenseStorageSession , чтобы создать объект сеанса. Используйте дескриптор сеанса клиента для получения списков отзыва для сертификатов учетной записи или лицензиара клиента. Используйте дескриптор сеанса хранилища лицензий, чтобы получить списки отзыва для лицензий конечных пользователей.
Задайте для параметра uIndex нулевое значение, а для параметра uFlags— DRM_EL_REVOCATIONLIST и вызовите DRMEnumerateLicense.
Если список отзыва не является запрошенным, увеличьте uIndex и вызовите DRMEnumerateLicense еще раз. Вы можете продолжать итерацию, пока не найдете правильный список или функция не вернет E_DRM_NO_MORE_DATA.

Чтобы получить одну лицензию, необходимо дважды вызвать DRMEnumerateLicense . При первом вызове присвойте wszCertificateDataзначение NULL , чтобы получить требуемый размер буфера. Выделите память и снова вызовите DRMEnumerateLicense . Это иллюстрируется в следующем примере.

// Call DRMEnumerateLicense with the wszCertificateData parameter set
// to NULL.
hr = DRMEnumerateLicense( 
         hClient,                          // Client session handle
         DRM_EL_SPECIFIED_CLIENTLICENSOR,  // Flags
         0,                                // Index
         &fShared,                         // Shared license
         &uiClientLicensorCertLength,      // Certificate length
         NULL                              // Certificate
         );

if ( FAILED( hr ) && ( E_DRM_NO_MORE_DATA != hr ) )
{
   goto e_Exit;
}

// There are no client licensor certificates. Acquire one.
else if ( E_DRM_NO_MORE_DATA == hr )
{
    // TODO: Acquire a client licensor certificate.
}

// A client licensor certificate was found. Allocate memory and
// call DRMEnumerateLicense again.
else
{

   wszClientLicensorCert = new WCHAR[ uiClientLicensorCertLength ];
   if ( NULL == wszClientLicensorCert )
   {
      hr = E_OUTOFMEMORY;
      goto e_Exit;
   }

   hr = DRMEnumerateLicense( 
         hClient,                          // Client session handle
         DRM_EL_SPECIFIED_CLIENTLICENSOR,  // Flags
         0,                                // Index
         &fShared,                         // Shared license
         &uiClientLicensorCertLength,      // Certificate length
         wszClientLicensorCert             // Certificate
         );

   if ( FAILED( hr ) )
   {
      goto e_Exit;
   }
}

e_Exit:

    if ( NULL != hClient )
    {
        hr = DRMCloseSession( hClient );
    }

    if ( NULL != wszUserId )
    {
        delete [] wszUserId;
    }


    if ( NULL != wszLicensingSvr )
    {
        delete [] wszLicensingSvr;
    }

    if ( NULL != wszClientLicensorCert )
    {
        delete [] wszClientLicensorCert;
    }

    return hr;

Требования

Требование	Значение
Целевая платформа	Windows
Header	msdrm.h
Библиотека	Msdrm.lib
DLL	Msdrm.dll

См. также раздел

Функции AD RMS

OfflineSigning_GetCertificate.cpp