Функция CPCGetUserKey() обычно не требует предварительной аутентификации для получения дескриптора ключа. Однако, в случае получения симметричного ключа аутентификация необходима. Чтобы проверить наличие ключей в контейнере, не проводя аутентификацию, следует использовать параметр PP_CONTAINER_STATUS с флагом CRYPT_KEYSET_ENUM_FLAG функции CPCGetProvParam .
DWORD CPCAPI CPCGetUserKey( HCRYPTMODULE hCSP, HCRYPTPROV hProv, DWORD dwKeySpec, HCRYPTKEY * phUserKey );
Аргументы
- hCSP
- [in] Указатель на таблицу функций криптопровайдера. Получается при помощи функции CPCCreateProvider()
- hProv
- [in] Дескриптор криптопровайдера.
Получается при помощи функции CPCAcquireContext(). - dwKeySpec
- [in] Спецификация возвращаемого ключа. Следующие типы ключевых пар и ключей определены в настоящее время:
Значение Описание AT_KEYEXCHANGE Ключевая пара обмена AT_SIGNATURE Ключевая пара цифровой подписи AT_SYMMETRIC Симметричный ключ. AT_UECSYMMETRICKEY Симметричный ключ - мастерключ для систем аутентификации карт
Аргументы
- phUserKey
- [out] Адрес, по которому функция копирует дескриптор ключа.
Возвращаемые значения
При успешном завершении функция возвращает 0 (S_OK), в противном случае возвращается соответствующий код ошибки (см. таблицу).| Коды возврата | Описание |
|---|---|
| ERROR_INVALID_PARAMETER | Один из параметров содержит некорректное значение. Чаще всего это некорректный указатель. |
| NTE_NO_KEY | Ключ, указанный dwKeySpec параметром, не существует. |
| NTE_BAD_TYPE | Значение параметра dwKeySpec неизвестно. |
| SCARD_W_CANCELLED_BY_USER | Пользователь прервал операцию нажатием клавиши Cancel |
| SCARD_W_WRONG_CHV | Пользователь ввёл неправильный пароль или пароль, установленный функцией SetProvParam(), неправильный |
| SCARD_E_INVALID_CHV | Пользователь ввёл пароль с нарушением формата или пароль, установленный функцией SetProvParam(), имеет неправильный формат. Например, пароль имеет недопустимую длину или содержит недопустимые символы. |
| SCARD_W_CHV_BLOCKED | Ввод Pin-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток разрешенное картой для ввода. |
| ERROR_BAD_USERNAME | Введенный login доступа к ключевому сервису неверен. |
| ERROR_INVALID_PASSWORD | Введенный пароль доступа к ключевому сервису неверен. |
| NTE_SILENT_CONTEXT | Операция не может быть выполнена без пользовательского интерфейса. |
| SCARD_W_REMOVED_CARD | Носитель контейнера был удален из считывателя |
| SCARD_E_NO_KEY_CONTAINER | Попытка выполнения операции в контексте смарт-карты или токена, а не контейнера. |
| SCARD_W_SECURITY_VIOLATION | Фукции безопасности токена или смарт-карты работают некорректно. |
| ERROR_PASSWORD_EXPIRED | Пароль данного носителя истек, необходимо его сменить. |
| SCARD_E_READ_ONLY_CARD | Смарт-карта недоступна для использования из-за ограничений безопасности. |
Примечания
При перечислении ключей типа AT_UECSYMMETRICKEY производится считывание ключа из ключевого контейнера. В некоторых случаях это может приводить к вызову окна запроса пароля ключа.
Полученный дескриптор ключа должен в обязательном порядке быть удалён с помощью вызова функции CPCDestroyKey() до вызова функции CPCReleaseContext() для рабочего дескриптора криптопровайдера.
Требования:
Ядро AIX: 6/7.
Ядро FreeBSD: 11/12.
Ядро Linux: 2.6.x и выше.
Ядро Solaris: 10/11.
Ядро Windows: 7/8/8.1/10, Server 2008/2008R2/2012/2012R2/2016/2019.
См. также
CPCExportKey() ,CPCGenKey() ,CPGetUserKey в MS CSP 
,CryptGetUserKey в MS CryptoAPI 2.0