КриптоПро CSP  

CPGetUserKey

Функция CPGetUserKey() возвращает дескриптор одной из долговременных ключевых пар в ключевом контейнере, или симметричный ключ, если он сохранен в контейнере.

Функция CPGetUserKey() обычно не требует предварительной аутентификации для получения дескриптора ключа. Однако, в случае получения симметричного ключа аутентификация необходима. Чтобы проверить наличие ключей в контейнере, не проводя аутентификацию, следует использовать параметр PP_CONTAINER_STATUS с флагом CRYPT_KEYSET_ENUM_FLAG функции CPGetProvParam .

BOOL WINAPI CPGetUserKey(
  HCRYPTPROV hProv,
  DWORD dwKeySpec,
  HCRYPTKEY * phUserKey
);

Аргументы

hProv
[in] Дескриптор криптопровайдера.
Получается при помощи функции CPAcquireContext().
dwKeySpec
[in] Спецификация возвращаемого ключа. Следующие типы ключевых пар и ключей определены в настоящее время:
Значение Описание
AT_KEYEXCHANGE Ключевая пара обмена
AT_SIGNATURE Ключевая пара цифровой подписи
AT_SYMMETRIC Симметричный ключ.
AT_UECSYMMETRICKEY Симметричный ключ - мастерключ для систем аутентификации карт

Аргументы

phUserKey
[out] Адрес, по которому функция копирует дескриптор ключа.

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

При успешном завершении функция возвращает TRUE, в противном случае возвращается FALSE. Если возвращается FALSE, соответствующий код ошибки (см. таблицу) может быть получен через функцию GetLastError().
Коды возвратаОписание
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-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток разрешенное картой для ввода.
NTE_SILENT_CONTEXTОперация не может быть выполнена без пользовательского интерфейса.
SCARD_W_REMOVED_CARDНоситель контейнера был удален из считывателя
SCARD_E_NO_KEY_CONTAINERКонтекст открыт с флагом CRYPT_DEFAULT_CONTAINER_OPTIONAL, и не связан ни с одним контейнером, поэтому выполнение данной операции недоступно.

Примечания

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

Полученный дескриптор ключа должен в обязательном порядке быть удалён с помощью вызова функции CPDestroyKey()  до вызова функции CPReleaseContext() для рабочего дескриптора криптопровайдера.

Требования:

AIX: 6/7.
FreeBSD: 11/12, pfSense 2.x.
Linux: LSB 4.x (RHEL 5/6/7/8, SuSE 11SP4/12/15, Oracle Linux 5/6/7/8, CentOS 6/7/8, Ubuntu 14.04/16.04/18.04/19.10, Linux Mint 18/19, Fedora 28/29/30/31, Debian 8/9/10 и др.).
Solaris: 10/11.
Mac OS X: 10.9/10.10/10.11/10.12/10.13/10.14/10.15.
iOS: 8/9/10/11/12/13.
Sailfish: 2/3.
Windows: 7/8/8.1/10, Server 2008/2008R2/2012/2012R2/2016/2019.
Файл описания: Прототип описан в файле wincsp.h.
Ядро ОС: Вместо неё используется аналогичная функция CPCGetUserKey .

См. также

CPExportKey() ,CPGenKey() ,CPGetUserKey в MS CSP World Wide Web link ,CryptGetUserKey в MS CryptoAPI 2.0 World Wide Web link