CryptAcquireContextA-Funktion (wincrypt.h)
Diese Funktion versucht zunächst, einen CSP mit den in den parametern dwProvType und pszProvider beschriebenen Merkmalen zu finden. Wenn der CSP gefunden wird, versucht die Funktion, einen Schlüsselcontainer innerhalb des CSP zu finden, der dem durch den pszContainer-Parameter angegebenen Namen entspricht. Verwenden Sie CryptAcquireCertificatePrivateKey, um den Kontext und den Schlüsselcontainer eines privaten Schlüssels zu erwerben, der dem öffentlichen Schlüssel eines Zertifikats zugeordnet ist.
Mit der entsprechenden Einstellung von dwFlags kann diese Funktion auch Schlüsselcontainer erstellen und zerstören und den Zugriff auf einen CSP mit einem temporären Schlüsselcontainer ermöglichen, wenn der Zugriff auf einen privaten Schlüssel nicht erforderlich ist.
Syntax
BOOL CryptAcquireContextA(
[out] HCRYPTPROV *phProv,
[in] LPCSTR szContainer,
[in] LPCSTR szProvider,
[in] DWORD dwProvType,
[in] DWORD dwFlags
);
Parameter
[out] phProv
Ein Zeiger auf einen Handle eines CSP. Wenn Sie die Verwendung des CSP abgeschlossen haben, lassen Sie den Handle los, indem Sie die Funktion CryptReleaseContext aufrufen.
[in] szContainer
Der Schlüsselcontainername. Dies ist eine null-beendete Zeichenfolge, die den Schlüsselcontainer für den CSP identifiziert. Dieser Name ist unabhängig von der Methode, die zum Speichern der Schlüssel verwendet wird. Einige CSPs speichern ihre Schlüsselcontainer intern (in Hardware), einige verwenden die Systemregistrierung, und andere verwenden das Dateisystem. Wenn dwFlags in den meisten Fällen auf CRYPT_VERIFYCONTEXT festgelegt ist, muss pszContainer auf NULL festgelegt werden. Bei hardwarebasierten CSPs, z. B. einem Smartcard-CSP, kann jedoch auf öffentlich verfügbare Informationen im angegebenen Container zugegriffen werden.
Weitere Informationen zur Verwendung des pszContainer-Parameters finden Sie in den Hinweisen.
[in] szProvider
Eine null-beendete Zeichenfolge, die den Namen des zu verwendenden CSP enthält.
Wenn dieser Parameter NULL ist, wird der Benutzerstandardanbieter verwendet. Weitere Informationen finden Sie unter Kryptografiedienstanbieterkontexte. Eine Liste der verfügbaren kryptografischen Anbieter finden Sie unter Kryptografieanbieternamen.
Eine Anwendung kann den Namen des CSP abrufen, der verwendet wird, indem die Funktion CryptGetProvParam verwendet wird, um den PP_NAME CSP-Wert im dwParam-Parameter zu lesen.
Der Standard-CSP kann zwischen Betriebssystemversionen geändert werden. Um die Interoperabilität auf verschiedenen Betriebssystemplattformen sicherzustellen, sollte der CSP explizit mithilfe dieses Parameters festgelegt werden, anstatt den Standard-CSP zu verwenden.
[in] dwProvType
Gibt den Typ des zu erwerbenden Anbieters an. Definierte Anbietertypen werden in Kryptografieanbietertypen erläutert.
[in] dwFlags
Kennzeichenwerte. Dieser Parameter ist in der Regel auf Null festgelegt, einige Anwendungen legen jedoch mindestens eine der folgenden Flags fest.
| Wert | Bedeutung |
|---|---|
|
Diese Option ist für Anwendungen vorgesehen, die ephemerale Schlüssel verwenden, oder Anwendungen, die keinen Zugriff auf beibehaltene private Schlüssel erfordern, z. B. Anwendungen, die nur Hashing, Verschlüsselung und überprüfung digitaler Signaturen ausführen. Nur Anwendungen, die Signaturen erstellen oder Nachrichten entschlüsseln, benötigen Zugriff auf einen privaten Schlüssel. In den meisten Fällen sollte dieses Kennzeichen festgelegt werden.
Bei dateibasierten CSPs muss der PszContainer-Parameter auf NULL festgelegt werden. Die Anwendung hat keinen Zugriff auf die beibehaltenen privaten Schlüssel für öffentliche/private Schlüsselpaare. Wenn dieses Kennzeichen festgelegt ist, können temporäre öffentliche/private Schlüsselpaare erstellt werden, sie werden jedoch nicht beibehalten. Bei hardwarebasierten CSPs, z. B. einem Smartcard-CSP, wenn der PszContainer-ParameterNULL oder leer ist, bedeutet dieses Flag, dass kein Zugriff auf Schlüssel erforderlich ist, und dass dem Benutzer keine Benutzeroberfläche angezeigt werden soll. Dieses Formular wird verwendet, um eine Verbindung mit dem CSP herzustellen, um seine Funktionen abzufragen, aber nicht, um seine Schlüssel tatsächlich zu verwenden. Wenn der pszContainer-Parameter nicht NULL und nicht leer ist, bedeutet dieses Flag, dass nur der Zugriff auf die öffentlich verfügbaren Informationen innerhalb des angegebenen Containers erforderlich ist. Der CSP sollte keine PIN anfordern. Versuche, auf private Informationen zuzugreifen (z. B. die CryptSignHash-Funktion ), schlägt fehl. Wenn CryptAcquireContext aufgerufen wird, benötigen viele CSPs Eingaben vom eigenen Benutzer, bevor der Zugriff auf die privaten Schlüssel im Schlüsselcontainer gewährt wird. Beispielsweise können die privaten Schlüssel verschlüsselt werden, sodass ein Kennwort vom Benutzer benötigt wird, bevor sie verwendet werden können. Wenn jedoch das CRYPT_VERIFYCONTEXT Flag angegeben ist, ist der Zugriff auf die privaten Schlüssel nicht erforderlich, und die Benutzeroberfläche kann umgangen werden. |
|
Erstellt einen neuen Schlüsselcontainer mit dem durch pszContainer angegebenen Namen. Wenn pszContainerNULL ist, wird ein Schlüsselcontainer mit dem Standardnamen erstellt. |
|
Standardmäßig werden Schlüssel und Schlüsselcontainer als Benutzerschlüssel gespeichert. Bei Basisanbietern bedeutet dies, dass Benutzerschlüsselcontainer im Profil des Benutzers gespeichert werden. Auf einen schlüsselcontainer, der ohne dieses Kennzeichen durch einen Administrator erstellt wurde, kann nur durch den Benutzer zugegriffen werden, der den Schlüsselcontainer und einen Benutzer mit Administratorrechten erstellt hat.
Windows XP: Ein schlüsselcontainer, der ohne dieses Kennzeichen durch einen Administrator erstellt wurde, kann nur vom Benutzer aufgerufen werden, der den Schlüsselcontainer und das lokale Systemkonto erstellt hat. Ein Schlüsselcontainer, der ohne dieses Kennzeichen durch einen Benutzer erstellt wurde, auf den kein Administrator ist, kann nur vom Benutzer zugegriffen werden, der den Schlüsselcontainer und das lokale Systemkonto erstellt hat. Das CRYPT_MACHINE_KEYSET-Kennzeichen kann mit allen anderen Flags kombiniert werden, um anzugeben, dass der Schlüsselcontainer von Interesse ein Computerschlüsselcontainer ist und der CSP es als solche behandelt. Bei Basisanbietern bedeutet dies, dass die Schlüssel lokal auf dem Computer gespeichert werden, auf dem der Schlüsselcontainer erstellt wurde. Wenn ein Schlüsselcontainer ein Computercontainer sein soll, muss das CRYPT_MACHINE_KEYSET Flag mit allen Aufrufen von CryptAcquireContext verwendet werden, die auf den Computercontainer verweisen. Der schlüsselcontainer, der mit CRYPT_MACHINE_KEYSET von einem Administrator erstellt wurde, kann nur von seinem Ersteller und von einem Benutzer mit Administratorrechten zugegriffen werden, es sei denn, Zugriffsberechtigungen für den Container werden mithilfe von CryptSetProvParam gewährt. Windows XP: Der schlüsselcontainer, der mit CRYPT_MACHINE_KEYSET von einem Administrator erstellt wurde, kann nur von seinem Ersteller und vom lokalen Systemkonto zugegriffen werden, es sei denn, Zugriffsberechtigungen für den Container werden mithilfe von CryptSetProvParam gewährt. Der Schlüsselcontainer, der mit CRYPT_MACHINE_KEYSET von einem Benutzer erstellt wurde, der kein Administrator ist, kann nur von seinem Ersteller und vom lokalen Systemkonto zugegriffen werden, es sei denn, Zugriffsberechtigungen für den Container werden mithilfe von CryptSetProvParam gewährt. Das CRYPT_MACHINE_KEYSET Flag ist nützlich, wenn der Benutzer über einen Dienst oder ein Benutzerkonto zugreift, das sich nicht interaktiv angemeldet hat. Wenn Schlüsselcontainer erstellt werden, erstellen die meisten CSPs keine öffentlichen/privaten Schlüsselpaare. Diese Schlüssel müssen als separater Schritt mit der CryptGenKey-Funktion erstellt werden. |
|
Löschen Sie den schlüsselcontainer , der von pszContainer angegeben wird. Wenn pszContainerNULL ist, wird der Schlüsselcontainer mit dem Standardnamen gelöscht. Alle Schlüsselpaare im Schlüsselcontainer werden ebenfalls zerstört.
Wenn dieses Flag festgelegt ist, wird der in phProv zurückgegebene Wert nicht definiert, und daher muss die CryptReleaseContext-Funktion danach nicht aufgerufen werden. |
|
Die Anwendung fordert an, dass der CSP keine Benutzeroberfläche (Ui) für diesen Kontext anzeigt. Wenn der CSP die Benutzeroberfläche anzeigen muss, schlägt der Aufruf fehl, und der NTE_SILENT_CONTEXT Fehlercode wird als letzter Fehler festgelegt. Wenn Aufrufe an CryptGenKey mit dem CRYPT_USER_PROTECTED Flag mit einem Kontext vorgenommen werden, der mit dem CRYPT_SILENT-Flag abgerufen wurde, schlagen die Aufrufe fehl, und der CSP legt NTE_SILENT_CONTEXT fest.
CRYPT_SILENT ist für die Verwendung mit Anwendungen vorgesehen, für die die Benutzeroberfläche nicht vom CSP angezeigt werden kann. |
|
Ruft einen Kontext für einen Smartcard-CSP ab, der für Hashing- und symmetrische Schlüsselvorgänge verwendet werden kann, kann jedoch nicht für jeden Vorgang verwendet werden, der eine Authentifizierung für eine Smartcard mit einer PIN erfordert. Dieser Kontexttyp wird am häufigsten verwendet, um Vorgänge auf einer leeren Smartcard auszuführen, z. B. das Festlegen der PIN mithilfe von CryptSetProvParam. Dieses Kennzeichen kann nur mit Smartcard-CSPs verwendet werden.
Windows Server 2003 und Windows XP: Dieses Flag wird nicht unterstützt. |
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero (TRUE) zurück.
Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie getLastError für erweiterte Fehlerinformationen auf.
Die von NTE vorgestellten Fehlercodes werden vom verwendeten CSP generiert. Einige mögliche Fehlercodes, die in Winerror.h definiert sind, folgen.
| Rückgabecode/-wert | BESCHREIBUNG |
|---|---|
|
Einige CSPs legen diesen Fehler fest, wenn der CRYPT_DELETEKEYSET Flagwert festgelegt ist und ein anderer Thread oder Prozess diesen Schlüsselcontainer verwendet. |
|
Das Profil des Benutzers wird nicht geladen und kann nicht gefunden werden. Dies geschieht, wenn die Anwendung einen Benutzer beschreibt, z. B. das IUSR_ComputerName-Konto . |
|
Eine der Parameter enthält einen Wert, der ungültig ist. Dies ist am häufigsten ein Zeiger, der nicht gültig ist. |
|
Das Betriebssystem wurde während des Vorgangs aus dem Arbeitsspeicher ausgeführt. |
|
Der dwFlags-Parameter weist einen Wert auf, der ungültig ist. |
|
Das Benutzerkennwort wurde geändert, da die privaten Schlüssel verschlüsselt wurden. |
|
Der Schlüsselcontainer konnte nicht geöffnet werden. Eine häufige Ursache dieses Fehlers ist, dass der Schlüsselcontainer nicht vorhanden ist. Um einen Schlüsselcontainer zu erstellen, rufen Sie CryptAcquireContext mithilfe des CRYPT_NEWKEYSET-Flags auf. Dieser Fehlercode kann auch angeben, dass der Zugriff auf einen vorhandenen Schlüsselcontainer verweigert wird. Zugriffsrechte für den Container können vom Schlüsselsatz-Creator mithilfe von CryptSetProvParam gewährt werden. |
|
Der pszContainer- oder pszProvider-Parameter wird auf einen Wert festgelegt, der ungültig ist. |
|
Der Wert des dwProvType-Parameters ist außerhalb des Bereichs. Alle Anbietertypen müssen von 1 bis 999 inklusive sein. |
|
Die DLL-Signatur des Anbieters konnte nicht überprüft werden. Entweder die DLL oder die digitale Signatur wurde manipuliert. |
|
Der dwFlags-Parameter ist CRYPT_NEWKEYSET, aber der Schlüsselcontainer ist bereits vorhanden. |
|
Der pszContainer-Schlüsselcontainer wurde gefunden, ist jedoch beschädigt. |
|
Der angeforderte Anbieter ist nicht vorhanden. |
|
Der CSP wurde während des Vorgangs aus dem Arbeitsspeicher ausgeführt. |
|
Die DLL-Datei des Anbieters ist nicht vorhanden oder befindet sich nicht im aktuellen Pfad. |
|
Der von dwProvType angegebene Anbietertyp ist beschädigt. Dieser Fehler kann sich auf die Standard-CSP-Liste des Benutzers oder die Standard-CSP-Liste des Computers beziehen. |
|
Der von dwProvType angegebene Anbietertyp entspricht nicht dem gefundenen Anbietertyp. Beachten Sie, dass dieser Fehler nur auftreten kann, wenn pszProvider einen tatsächlichen CSP-Namen angibt. |
|
Es gibt keinen Eintrag für den von dwProvType angegebenen Anbietertyp. |
|
Die DLL-Datei des Anbieters konnte nicht geladen oder nicht initialisiert werden. |
|
Fehler beim Laden des DLL-Dateiimages, bevor Sie die Signatur überprüfen. |
Bemerkungen
Der pszContainer-Parameter gibt den Namen des Containers an, der zum Halten des Schlüssels verwendet wird. Jeder Container kann einen Schlüssel enthalten. Wenn Sie den Namen eines vorhandenen Containers beim Erstellen von Schlüsseln angeben, überschreibt der neue Schlüssel eine vorherige.
Die Kombination aus dem CSP-Namen und dem Schlüsselcontainernamen identifiziert eindeutig einen einzelnen Schlüssel im System. Wenn eine Anwendung versucht, einen Schlüsselcontainer zu ändern, während eine andere Anwendung es verwendet, kann das unvorhersehbare Verhalten auftreten.
Wenn Sie den pszContainer-Parameter auf NULL festlegen, wird der Standardcontainername verwendet. Wenn die Microsoft-Software-CSPs auf diese Weise aufgerufen werden, wird jedes Mal ein neuer Container erstellt, wenn die Funktion "CryptAcquireContext " aufgerufen wird. Verschiedene CSPs können sich jedoch in dieser Hinsicht anders verhalten. Insbesondere kann ein CSP über einen einzigen Standardcontainer verfügen, der von allen Anwendungen auf den CSP freigegeben wird. Daher dürfen Anwendungen den Standardschlüsselcontainer nicht verwenden, um private Schlüssel zu speichern. Verhindern Sie stattdessen den Schlüsselspeicher, indem Sie das CRYPT_VERIFYCONTEXT-Flag im dwFlags-Parameter übergeben oder einen anwendungsspezifischen Container verwenden, der nicht von einer anderen Anwendung verwendet werden soll.
Eine Anwendung kann den Namen des Schlüsselcontainers abrufen, der verwendet wird, indem sie die Funktion "CryptGetProvParam " verwenden, um den PP_CONTAINER Wert zu lesen.
Aus Leistungsgründen empfiehlt es sich, den pszContainer-Parameter auf NULL und den dwFlags-Parameter auf CRYPT_VERIFYCONTEXT in allen Situationen festzulegen, in denen Sie keinen beibehaltenen Schlüssel benötigen. Berücksichtigen Sie insbesondere das Festlegen des pszContainer-Parameters auf NULL und den dwFlags-Parameter , um CRYPT_VERIFYCONTEXT für die folgenden Szenarien zu CRYPT_VERIFYCONTEXT :
- Sie erstellen einen Hash.
- Sie generieren einen symmetrischen Schlüssel, um Daten zu verschlüsseln oder zu entschlüsseln.
- Sie leiten einen symmetrischen Schlüssel von einem Hash ab, um Daten zu verschlüsseln oder zu entschlüsseln.
- Sie überprüfen eine Signatur. Es ist möglich, einen öffentlichen Schlüssel aus einem PUBLICKEYBLOB oder aus einem Zertifikat mithilfe von CryptImportKey oder CryptImportPublicKeyInfo zu importieren. Ein Kontext kann mithilfe des CRYPT_VERIFYCONTEXT-Flags erworben werden, wenn Sie nur den öffentlichen Schlüssel importieren möchten.
- Sie planen, einen symmetrischen Schlüssel zu exportieren, aber nicht innerhalb der Lebensdauer des Kryptokontexts zu importieren. Ein Kontext kann mithilfe des CRYPT_VERIFYCONTEXT-Flags erworben werden, wenn Sie nur den öffentlichen Schlüssel für die letzten beiden Szenarien importieren möchten.
- Sie führen private Schlüsselvorgänge aus, verwenden jedoch keinen beibehaltenen privaten Schlüssel, der in einem Schlüsselcontainer gespeichert ist.
Beispiele
Im folgenden Beispiel wird der Erwerb eines kryptografischen Kontexts und des Zugriffs auf öffentliche/private Schlüsselpaare in einem Schlüsselcontainer gezeigt. Wenn der angeforderte Schlüsselcontainer nicht vorhanden ist, wird er erstellt.
Ein Beispiel, das den vollständigen Kontext für dieses Beispiel enthält, finden Sie unter Beispiel C-Programm: Erstellen eines Schlüsselcontainers und Generieren von Schlüsseln. Weitere Beispiele finden Sie unter Beispiel C-Programm: Verwenden von CryptAcquireContext.
//-------------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv = NULL; // handle for a cryptographic
// provider context
LPCSTR UserName = "MyKeyContainer"; // name of the key container
// to be used
//-------------------------------------------------------------------
// Attempt to acquire a context and a key
// container. The context will use the default CSP
// for the RSA_FULL provider type. DwFlags is set to zero
// to attempt to open an existing key container.
if(CryptAcquireContext(
&hCryptProv, // handle to the CSP
UserName, // container name
NULL, // use the default provider
PROV_RSA_FULL, // provider type
0)) // flag values
{
printf("A cryptographic context with the %s key container \n",
UserName);
printf("has been acquired.\n\n");
}
else
{
//-------------------------------------------------------------------
// An error occurred in acquiring the context. This could mean
// that the key container requested does not exist. In this case,
// the function can be called again to attempt to create a new key
// container. Error codes are defined in Winerror.h.
if (GetLastError() == NTE_BAD_KEYSET)
{
if(CryptAcquireContext(
&hCryptProv,
UserName,
NULL,
PROV_RSA_FULL,
CRYPT_NEWKEYSET))
{
printf("A new key container has been created.\n");
}
else
{
printf("Could not create a new key container.\n");
exit(1);
}
}
else
{
printf("A cryptographic service handle could not be "
"acquired.\n");
exit(1);
}
} // End of else.
//-------------------------------------------------------------------
// A cryptographic context and a key container are available. Perform
// any functions that require a cryptographic provider handle.
//-------------------------------------------------------------------
// When the handle is no longer needed, it must be released.
if (CryptReleaseContext(hCryptProv,0))
{
printf("The handle has been released.\n");
}
else
{
printf("The handle could not be released.\n");
}
Hinweis
Der wincrypt.h-Header definiert CryptAcquireContext als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstanten automatisch auswählt. Das Mischen der Verwendung des Codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann dazu führen, dass keine Übereinstimmungen auftreten, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [Nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wincrypt.h |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |