Функция CertSetCertificateContextProperty (wincrypt.h)

Статья
03/15/2023

Функция CertSetCertificateContextProperty задает расширенное свойство для указанного контекста сертификата.

Синтаксис

BOOL CertSetCertificateContextProperty(
  [in] PCCERT_CONTEXT pCertContext,
  [in] DWORD          dwPropId,
  [in] DWORD          dwFlags,
  [in] const void     *pvData
);

Параметры

[in] pCertContext

Указатель на структуру CERT_CONTEXT .

[in] dwPropId

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

Обратите вниманиеCRYPT_HASH_BLOB и CRYPT_DATA_BLOB описаны в разделе CRYPT_INTEGER_BLOB .

CERT_ACCESS_STATE_PROP_ID

Тип данных pvData: указатель на значение DWORD .

Возвращает значение DWORD , указывающее, сохраняются ли операции записи в сертификат. Значение DWORD не задано, если сертификат находится в хранилище памяти или в хранилище на основе реестра, открытое как доступное только для чтения.

CERT_AIA_URL_RETRIEVED_PROP_ID

Этот идентификатор зарезервирован.

CERT_ARCHIVED_KEY_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_HASH_BLOB .

Это свойство сохраняет зашифрованный хэш ключа для контекста сертификата.

CERT_ARCHIVED_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Указывает, что сертификат пропускается во время перечисления. Сертификат с этим набором свойств по-прежнему обнаруживается с помощью явных операций поиска, таких как поиск сертификата с определенным хэшом или определенным серийным номером. Для этого свойства можно задать пустой большой двоичный объект , {0,NULL}.

CERT_AUTHORITY_INFO_ACCESS_PROP_ID

Этот идентификатор зарезервирован.

CERT_AUTO_ENROLL_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Свойство, которое задается после регистрации сертификата с помощью автоматической регистрации. Структура CRYPT_DATA_BLOB , на которую указывает pvData, включает в себя завершающееся null имя Юникода типа сертификата, для которого сертификат был автоматически зарегистрирован. Все последующие вызовы автоматической регистрации сертификата проверяют наличие этого свойства, чтобы определить, был ли сертификат зарегистрирован.

CERT_AUTO_ENROLL_RETRY_PROP_ID

Этот идентификатор зарезервирован.

CERT_BACKED_UP_PROP_ID

Этот идентификатор зарезервирован.

CERT_CA_DISABLE_CRL_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Отключает получение списка отзыва сертификатов (CRL) для сертификатов, используемых центром сертификации (ЦС). Если сертификат ЦС содержит это свойство, он также должен содержать свойство CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID .

CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Содержит список URL-адресов протокола OCSP, используемых для сертификатов, выданных сертификатом ЦС. Содержимое массива представляет собой байты, закодированные в абстрактном синтаксисе (ASN.1) структуры X509_AUTHORITY_INFO_ACCESS , где для pszAccessMethod задано значение szOID_PKIX_OCSP.

CERT_CROSS_CERT_DIST_POINTS_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Задает расположение кросс-сертификатов. Это значение применимо только к сертификатам, а не к спискам отзыва сертификатов (CRL) или спискам доверия сертификатов (CCL). Структура CRYPT_DATA_BLOB содержит абстрактную синтаксическую нотацию 1 (ASN.1) CROSS_CERT_DIST_POINTS_INFO структуру, которая закодирована с помощью функции CryptEncodeObject с X509_CROSS_CERT_DIST_POINTS значением для параметра lpszStuctType .

CERT_CTL_USAGE_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Структура CRYPT_DATA_BLOB содержит структуру CTL_USAGE в кодировке ASN.1. Эта структура кодируется с помощью функции CryptEncodeObject с заданным значением X509_ENHANCED_KEY_USAGE.

CERT_DATE_STAMP_PROP_ID

Тип данных pvData: указатель на структуру FILETIME .

Это свойство задает время добавления сертификата в хранилище.

CERT_DESCRIPTION_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Свойство, которое задается и отображается в пользовательском интерфейсе сертификата. Это свойство позволяет пользователю описывать использование сертификата.

CERT_EFS_PROP_ID

Этот идентификатор зарезервирован.

CERT_ENHKEY_USAGE_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Свойство , указывающее, что параметр pvData указывает на CRYPT_DATA_BLOB структуру, содержащую структуру CERT_ENHKEY_USAGE в кодировке ASN.1. Эта структура кодируется с помощью функции CryptEncodeObject с заданным значением X509_ENHANCED_KEY_USAGE.

CERT_ENROLLMENT_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Сведения о регистрации ожидающего запроса, содержащего RequestID, CADNSName, CAName и DisplayName. Формат данных определяется следующим образом.

Байты	Содержимое
Первые 4 байта	Идентификатор ожидающего запроса
Следующие 4 байта	Размер CADNSName в символах, включая завершающий символ NULL, за которым следует строка CADNSName с завершающим символом NULL.
Следующие 4 байта	Размер CAName в символах, включая завершающий символ NULL, за которым следует строка CAName с завершающим символом NULL.
Следующие 4 байта	Размер DisplayName в символах, включая завершающий символ NULL, за которым следует строка DisplayName с завершающим символом NULL.

CERT_EXTENDED_ERROR_INFO_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство задает строку, содержащую расширенные сведения об ошибке для контекста сертификата.

CERT_FORTEZZA_DATA_PROP_ID

Этот идентификатор зарезервирован.

CERT_FRIENDLY_NAME_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Структура CRYPT_DATA_BLOB содержит отображаемое имя сертификата.

CERT_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство неявно задается вызовом функции CertGetCertificateContextProperty .

CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID

Тип данных pvData: указатель на HCRYPTPROV_OR_NCRYPT_KEY_HANDLE тип данных.

Это свойство вызывает NCryptIsKeyHandle , чтобы определить, является ли это NCRYPT_KEY_HANDLE. Для NCRYPT_KEY_HANDLE задает CERT_NCRYPT_KEY_HANDLE_PROP_ID; В противном случае он задает CERT_KEY_PROV_HANDLE_PROP_ID.

CERT_HCRYPTPROV_TRANSFER_PROP_ID

Задает дескриптор ключа CAPI, связанного с сертификатом.

CERT_IE30_RESERVED_PROP_ID

Этот идентификатор зарезервирован.

CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

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

CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Структура CRYPT_DATA_BLOB содержит хэш MD5 имени издателя и серийный номер из этого сертификата.

CERT_KEY_CONTEXT_PROP_ID

Тип данных pvData: указатель на структуру CERT_KEY_CONTEXT .

Структура указывает закрытый ключ сертификата. Он содержит спецификацию HCRYPTPROV и ключа для закрытого ключа. Дополнительные сведения о параметрах элемента hCryptProv и dwFlags см. в разделе CERT_KEY_PROV_HANDLE_PROP_ID далее в этом разделе.

Примечание Для этого свойства можно добавить дополнительные CERT_KEY_CONTEXT элементы структуры. Если это так, значение члена cbSize будет скорректировано соответствующим образом. Член cbSize должен иметь размер структуры CERT_KEY_CONTEXT .

CERT_KEY_IDENTIFIER_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство обычно неявно задается вызовом функции CertGetCertificateContextProperty .

CERT_KEY_PROV_HANDLE_PROP_ID

Тип данных pvData: значение HCRYPTPROV .

Задан дескриптор HCRYPTPROV для закрытого ключа сертификата. Элемент hCryptProvструктуры CERT_KEY_CONTEXT обновляется, если он существует. Если он не существует, он создается с помощью dwKeySpec и инициализируется CERT_KEY_PROV_INFO_PROP_ID. Если CERT_STORE_NO_CRYPT_RELEASE_FLAG не задано, значение hCryptProv неявно освобождается, если свойству присвоено значение NULL или при окончательном освобождении структуры CERT_CONTEXT .

CERT_KEY_PROV_INFO_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_KEY_PROV_INFO .

Структура указывает закрытый ключ сертификата.

CERT_KEY_SPEC_PROP_ID

Тип данных pvData: указатель на значение DWORD .

Значение DWORD , указывающее закрытый ключ. Член dwKeySpecструктуры CERT_KEY_CONTEXT обновляется, если он существует. В противном случае он создается с параметром hCryptProv , равным нулю.

CERT_MD5_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_HASH_BLOB .

Это свойство неявно задается вызовом функции CertGetCertificateContextProperty .

CERT_NCRYPT_KEY_HANDLE_PROP_ID

Тип данных pvData: указатель на NCRYPT_KEY_HANDLE тип данных.

Это свойство задает NCRYPT_KEY_HANDLE для закрытого ключа сертификата и задает параметру dwKeySpecзначение CERT_NCRYPT_KEY_SPEC.

CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID

Задает дескриптор ключа CNG, связанного с сертификатом.

CERT_NEW_KEY_PROP_ID

Этот идентификатор зарезервирован.

CERT_NEXT_UPDATE_LOCATION_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Структура CRYPT_DATA_BLOB содержит структуру CERT_ALT_NAME_INFO в кодировке ASN.1, которая закодирована с помощью функции CryptEncodeObject с заданным значением X509_ALTERNATE_NAME.

CERT_NEXT_UPDATE_LOCATION_PROP_ID в настоящее время используется только с CCL.

CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID

Этот идентификатор зарезервирован.

CERT_OCSP_CACHE_PREFIX_PROP_ID

Этот идентификатор зарезервирован.

CERT_OCSP_RESPONSE_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство задает закодированный ответ протокола OCSP от CERT_SERVER_OCSP_RESPONSE_CONTEXT для этого сертификата.

CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство неявно задается путем вызова функции CertGetCertificateContextProperty .

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот идентификатор не поддерживается.

CERT_PUBKEY_ALG_PARA_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство используется с открытыми ключами, поддерживающими наследование параметров алгоритма. Большой двоичный объект данных содержит параметры алгоритма PublicKey в кодировке ASN.1. Для DSS это параметры, закодированные с помощью функции CryptEncodeObject . Используется только в том случае, если определен CMS_PKCS7.

CERT_PUBKEY_HASH_RESERVED_PROP_ID

Этот идентификатор зарезервирован.

CERT_PVK_FILE_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Структура CRYPT_DATA_BLOB указывает имя файла, содержащего закрытый ключ, связанный с открытым ключом сертификата. Внутри структуры CRYPT_DATA_BLOB элемент pbData является указателем на строку с широкими символами Юникода, завершаемую null, а член cbData указывает длину строки.

CERT_RENEWAL_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство задает хэш обновленного сертификата.

CERT_REQUEST_ORIGINATOR_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Структура CRYPT_DATA_BLOB содержит строку Юникода, завершающуюся null, которая содержит dns-имя компьютера для создания запроса контекста сертификата.

CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Возвращает указатель на закодированную структуру CERT_POLICIES_INFO , содержащую политики приложения корневого сертификата для контекста. Это свойство можно декодировать с помощью функции CryptDecodeObject с параметром lpszStructType , равным X509_CERT_POLICIES , а параметру dwCertEncodingType присвоено сочетание X509_ASN_ENCODING побитового илиPKCS_7_ASN_ENCODING.

CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID

Этот идентификатор зарезервирован.

CERT_SIGN_HASH_CNG_ALG_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство неявно задается путем вызова функции CertGetCertificateContextProperty .

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот идентификатор не поддерживается.

CERT_SHA1_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_HASH_BLOB .

Это свойство неявно задается вызовом функции CertGetCertificateContextProperty .

CERT_SIGNATURE_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_HASH_BLOB .

Если хэш подписи не существует, он вычисляется с помощью функции CryptHashToBeSigned . pvData указывает на существующий или вычисляемый хэш. Обычно длина хэша составляет 20 байт для SHA и 16 для MD5.

CERT_SMART_CARD_DATA_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство задает свойство данных смарт-карта контекста сертификата смарт-карта.

CERT_SMART_CARD_ROOT_INFO_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство задает свойство сведений смарт-карта контекст корневого сертификата.

CERT_SOURCE_LOCATION_PROP_ID

Этот идентификатор зарезервирован.

CERT_SOURCE_URL_PROP_ID

Этот идентификатор зарезервирован.

CERT_SUBJECT_DISABLE_CRL_PROP_ID

Этот идентификатор зарезервирован.

CERT_SUBJECT_INFO_ACCESS_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство задает расширение доступа к информации субъекта контекста сертификата в виде закодированной структуры CERT_SUBJECT_INFO_ACCESS .

CERT_SUBJECT_NAME_MD5_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Возвращает md5-хэш закодированного имени субъекта контекста сертификата.

CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

Этот идентификатор зарезервирован.

CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство неявно задается путем вызова функции CertGetCertificateContextProperty .

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот идентификатор не поддерживается.

CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_DATA_BLOB .

Это свойство задает хэш MD5 открытого ключа этого сертификата.

pvData — это указатель на структуру CRYPT_DATA_BLOB .

Пользователь может определить дополнительные типы dwPropId , используя значения DWORD из CERT_FIRST_USER_PROP_IDв CERT_LAST_USER_PROP_ID. Для всех определяемых пользователем типов dwPropIdpvData указывает на закодированную структуру CRYPT_DATA_BLOB .

[in] dwFlags

CERT_STORE_NO_CRYPT_RELEASE_FLAG можно задать для свойств dwPropId CERT_KEY_PROV_HANDLE_PROP_ID или CERT_KEY_CONTEXT_PROP_ID.

Если задано значение CERT_SET_PROPERTY_IGNORE_PERSIST_ERROR_FLAG, все ошибки записи поставщика игнорируются, а свойства кэшированного контекста всегда задаются.

Если задано CERT_SET_PROPERTY_INHIBIT_PERSIST_FLAG, все наборы свойств контекста не сохраняются.

[in] pvData

Указатель на тип данных, определяемый значением dwPropId.

Примечание Для любого dwPropId при установке параметра pvData значения NULL свойство удаляется.

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

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

Если функция завершается сбоем, функция возвращает значение FALSE. Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. Ниже приведен один из возможных кодов ошибки.

Код возврата	Описание
E_INVALIDARG	Недопустимое свойство. Указанный идентификатор был больше 0x0000FFFF или для свойства CERT_KEY_CONTEXT_PROP_ID в структуре CERT_KEY_CONTEXT указан недопустимый член cbSize.

Код может использовать макрос для оценки класса хэша для контекста сертификата. Заголовок Wincrypt.h определяет следующие макросы для этой цели. Эти макросы используются внутри функции CertSetCertificateContextProperty .

IS_CERT_HASH_PROP_ID(X)IS_PUBKEY_HASH_PROP_ID(X)IS_CHAIN_HASH_PROP_ID(X) Каждый макрос принимает значение dwPropId (X) в качестве входных данных и вычисляет логическое значение. В следующей таблице показаны значения dwPropId , которые имеют значение TRUE для каждого макроса.

Макрос	Возвращает значение TRUE , если dwPropId имеет значение .
IS_CERT_HASH_PROP_ID(dwPropId)	CERT_SHA1_HASH_PROP_ID, CERT_MD5_HASH_PROP_ID или CERT_SIGNATURE_HASH_PROP_ID
IS_PUBKEY_HASH_PROP_ID(dwPropId)	CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID или CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID
IS_CHAIN_HASH_PROP_ID(dwPropId)	CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID, CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID, CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID или CERT_SUBJECT_NAME_MD5_HASH_PROP_ID

Макрос IS_STRONG_SIGN_PROP_ID(x) принимает значение TRUE, если свойства CERT_SIGN_HASH_CNG_ALG_PROP_ID, CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID или CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID заданы в параметре dwPropId.

Примеры

Пример использования этой функции см. в разделе Пример программы C: получение и настройка свойств сертификата.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	wincrypt.h
Библиотека	Crypt32.lib
DLL	Crypt32.dll