CryptAcquireContextA-Funktion (wincrypt.h)
Diese Funktion versucht zunächst, einen CSP mit den in den Parametern dwProvType und szProvider beschriebenen Merkmalen zu finden. Wenn der CSP gefunden wird, versucht die Funktion, einen Schlüsselcontainer innerhalb des CSP zu finden, der mit dem durch den szContainer-Parameter angegebenen Namen übereinstimmt. Verwenden Sie zum Abrufen des Kontexts und des Schlüsselcontainers eines privaten Schlüssels , der dem öffentlichen Schlüssel eines Zertifikats zugeordnet ist, CryptAcquireCertificatePrivateKey.
Mit der entsprechenden Einstellung von dwFlags kann diese Funktion auch Schlüsselcontainer erstellen und zerstören und zugriff auf einen CSP mit einem temporären Schlüsselcontainer gewähren, wenn kein Zugriff auf einen privaten Schlüssel 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 ein Handle eines CSP. Wenn Sie die Verwendung des CSP abgeschlossen haben, geben Sie das Handle frei, indem Sie die CryptReleaseContext-Funktion aufrufen.
[in] szContainer
Der Schlüsselcontainername. Dies ist eine NULL-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), andere verwenden die Systemregistrierung und andere das Dateisystem. Wenn dwFlags auf CRYPT_VERIFYCONTEXT festgelegt ist, muss szContainer in den meisten Fällen auf NULL festgelegt werden. Für hardwarebasierte CSPs, z. B. einen Smartcard-CSP, kann jedoch auf öffentlich verfügbare Informationen im angegebenen Container zugegriffen werden.
Weitere Informationen zur Verwendung des szContainer-Parameters finden Sie unter Hinweise.
[in] szProvider
Eine NULL-Zeichenfolge, die den Namen des zu verwendenden CSP enthält.
Wenn dieser Parameter NULL ist, wird der Standardanbieter des Benutzers verwendet. Weitere Informationen finden Sie unter Kryptografiedienstanbieterkontexte. Eine Liste der verfügbaren Kryptografieanbieter finden Sie unter Namen von Kryptografieanbietern.
Eine Anwendung kann den Namen des verwendeten CSP abrufen, indem die CryptGetProvParam-Funktion 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 anstelle des Standard-CSP festgelegt werden.
[in] dwProvType
Gibt den Typ des anbieters an, der abgerufen werden soll. Definierte Anbietertypen werden unter Kryptografieanbietertypen erläutert.
[in] dwFlags
Flagwerte. Dieser Parameter wird in der Regel auf 0 (null) festgelegt, aber einige Anwendungen legen mindestens eins der folgenden Flags fest.
| Wert | Bedeutung |
|---|---|
|
Diese Option ist für Anwendungen vorgesehen, die kurzlebige Schlüssel verwenden, oder Für Anwendungen, die keinen Zugriff auf persistente private Schlüssel benötigen, 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 Flag festgelegt werden.
Wenn dieses Flag für dateibasierte CSPs festgelegt ist, muss der parameter szContainer auf NULL festgelegt werden. Die Anwendung hat keinen Zugriff auf die beibehaltenen privaten Schlüssel von Öffentlichen/Privaten Schlüsselpaaren. Wenn dieses Flag festgelegt ist, können temporäre Öffentliche/private Schlüsselpaare erstellt werden, aber sie werden nicht beibehalten. Wenn der szContainer-Parameter bei hardwarebasierten CSPs, z. B. einem Smartcard-CSP, NULL oder leer ist, bedeutet dieses Flag, dass kein Zugriff auf Schlüssel erforderlich ist und dem Benutzer keine Benutzeroberfläche angezeigt werden sollte. 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 szContainer-Parameter nicht NULL und nicht leer ist, impliziert dieses Flag, dass nur 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 ), schlagen fehl. Wenn CryptAcquireContext aufgerufen wird, benötigen viele CSPs eingaben vom besitzenden Benutzer, bevor sie Zugriff auf die privaten Schlüssel im Schlüsselcontainer gewähren. Beispielsweise können die privaten Schlüssel verschlüsselt werden, sodass ein Kennwort vom Benutzer erforderlich ist, bevor sie verwendet werden können. Wenn jedoch das flag CRYPT_VERIFYCONTEXT angegeben ist, ist kein Zugriff auf die privaten Schlüssel erforderlich, und die Benutzeroberfläche kann umgangen werden. |
|
Erstellt einen neuen Schlüsselcontainer mit dem durch szContainer angegebenen Namen. Wenn szContainerNULL ist, wird ein Schlüsselcontainer mit dem Standardnamen erstellt. |
|
Standardmäßig werden Schlüssel und Schlüsselcontainer als Benutzerschlüssel gespeichert. Für Basisanbieter bedeutet dies, dass Benutzerschlüsselcontainer im Profil des Benutzers gespeichert werden. Auf einen Schlüsselcontainer, der ohne dieses Flag von einem Administrator erstellt wurde, kann nur der Benutzer, der den Schlüsselcontainer erstellt, und ein Benutzer mit Administratorrechten zugreifen.
Windows XP: Auf einen Schlüsselcontainer, der ohne dieses Flag von einem Administrator erstellt wurde, kann nur der Benutzer zugreifen, der den Schlüsselcontainer und das lokale Systemkonto erstellt. Auf einen Schlüsselcontainer, der ohne dieses Flag von einem Benutzer erstellt wurde, der kein Administrator ist, kann nur der Benutzer zugreifen, der den Schlüsselcontainer und das lokale Systemkonto erstellt. Das flag CRYPT_MACHINE_KEYSET kann mit allen anderen Flags kombiniert werden, um anzugeben, dass der schlüsselspezifische Container ein Computerschlüsselcontainer ist und der CSP ihn als solchen behandelt. Für Basisanbieter bedeutet dies, dass die Schlüssel lokal auf dem Computer gespeichert werden, der den Schlüsselcontainer erstellt hat. Wenn ein Schlüsselcontainer ein Computercontainer sein soll, muss das flag CRYPT_MACHINE_KEYSET für alle Aufrufe von CryptAcquireContext verwendet werden, die auf den Computercontainer verweisen. Auf den Schlüsselcontainer, der mit CRYPT_MACHINE_KEYSET von einem Administrator erstellt wurde, kann nur der Ersteller und ein Benutzer mit Administratorrechten zugreifen, es sei denn, die Zugriffsrechte für den Container werden mithilfe von CryptSetProvParam erteilt. Windows XP: Auf den Schlüsselcontainer, der mit CRYPT_MACHINE_KEYSET erstellt wurde, kann nur der Ersteller und das lokale Systemkonto zugreifen, es sei denn, die Zugriffsrechte für den Container werden mithilfe von CryptSetProvParam erteilt. Auf den Schlüsselcontainer, der mit CRYPT_MACHINE_KEYSET von einem Benutzer erstellt wurde, der kein Administrator ist, kann nur der Ersteller und das lokale Systemkonto zugreifen, es sei denn, die Zugriffsrechte für den Container werden mithilfe von CryptSetProvParam erteilt. Das CRYPT_MACHINE_KEYSET-Flag ist nützlich, wenn der Benutzer von einem Dienst oder Benutzerkonto aus zugreift, der sich nicht interaktiv angemeldet hat. Wenn Schlüsselcontainer erstellt werden, erstellen die meisten CSPs nicht automatisch öffentliche /private Schlüsselpaare. Diese Schlüssel müssen als separater Schritt mit der CryptGenKey-Funktion erstellt werden. |
|
Löschen Sie den durch szContainer angegebenen Schlüsselcontainer. Wenn szContainerNULL 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, ist der in phProv zurückgegebene Wert undefiniert, sodass die CryptReleaseContext-Funktion danach nicht aufgerufen werden muss. |
|
Die Anwendung fordert an, dass der CSP keine Benutzeroberfläche (UI) für diesen Kontext anzeigt. Wenn der CSP die Benutzeroberfläche für den Betrieb anzeigen muss, schlägt der Aufruf fehl, und der NTE_SILENT_CONTEXT Fehlercode wird als letzter Fehler festgelegt. Wenn Aufrufe von CryptGenKey mit dem flag CRYPT_USER_PROTECTED mit einem Kontext erfolgen, der mit dem flag CRYPT_SILENT 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 vom CSP nicht angezeigt werden kann. |
|
Ruft einen Kontext für einen Smartcard-CSP ab, der für Hashing- und Symmetric Key-Vorgänge verwendet werden kann, aber nicht für Vorgänge verwendet werden kann, die eine Authentifizierung bei einer Smartcard mithilfe einer PIN erfordern. 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 Flag 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 ungleich null (TRUE) zurück.
Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Die von NTE vorangestellten Fehlercodes werden vom jeweiligen verwendeten CSP generiert. Es folgen einige mögliche Fehlercodes, die in Winerror.h definiert sind.
| 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 die Identität eines Benutzers angibt, z. B. das konto IUSR_ComputerName . |
|
Einer der Parameter enthält einen ungültigen Wert. Dies ist in den meisten Fällen ein ungültiger Zeiger. |
|
Beim Betriebssystem ist während des Vorgangs nicht mehr genügend Arbeitsspeicher vorhanden. |
|
Der dwFlags-Parameter hat einen ungültigen Wert. |
|
Das Benutzerkennwort wurde geändert, seit die privaten Schlüssel verschlüsselt wurden. |
|
Der Schlüsselcontainer konnte nicht geöffnet werden. Eine häufige Ursache für diesen Fehler ist, dass der Schlüsselcontainer nicht vorhanden ist. Um einen Schlüsselcontainer zu erstellen, rufen Sie CryptAcquireContext mit dem flag CRYPT_NEWKEYSET auf. Dieser Fehlercode kann auch angeben, dass der Zugriff auf einen vorhandenen Schlüsselcontainer verweigert wird. Zugriffsrechte für den Container können vom Ersteller des Schlüsselsatzes mithilfe von CryptSetProvParam gewährt werden. |
|
Der szContainer - oder szProvider-Parameter wird auf einen ungültigen Wert festgelegt. |
|
Der Wert des dwProvType-Parameters liegt außerhalb des Bereichs. Alle Anbietertypen müssen zwischen 1 und einschließlich 999 liegen. |
|
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 Schlüsselcontainer szContainer wurde gefunden, ist aber beschädigt. |
|
Der angeforderte Anbieter ist nicht vorhanden. |
|
Während des Vorgangs war für den CSP der Arbeitsspeicher nicht mehr vorhanden. |
|
Die Anbieter-DLL-Datei ist nicht vorhanden oder befindet sich nicht im aktuellen Pfad. |
|
Der von dwProvType angegebene Anbietertyp ist beschädigt. Dieser Fehler kann sich entweder auf die Standard-CSP-Liste des Benutzers oder die Standard-CSP-Liste des Computers beziehen. |
|
Der von dwProvType angegebene Anbietertyp stimmt nicht mit dem gefundenen Anbietertyp überein. Beachten Sie, dass dieser Fehler nur auftreten kann, wenn szProvider einen tatsächlichen CSP-Namen angibt. |
|
Für den von dwProvType angegebenen Anbietertyp ist kein Eintrag vorhanden. |
|
Die Anbieter-DLL-Datei konnte nicht geladen werden oder konnte nicht initialisiert werden. |
|
Fehler beim Laden des DLL-Dateiimages vor der Überprüfung der Signatur. |
Hinweise
Der szContainer-Parameter gibt den Namen des Containers an, der zum Halten des Schlüssels verwendet wird. Jeder Container kann einen Schlüssel enthalten. Wenn Sie beim Erstellen von Schlüsseln den Namen eines vorhandenen Containers angeben, überschreibt der neue Schlüssel einen vorherigen.
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 ihn verwendet, kann unvorhersehbares Verhalten auftreten.
Wenn Sie den szContainer-Parameter auf NULL festlegen, wird der Standardname des Schlüsselcontainers verwendet. Wenn die Microsoft-Software-CSPs auf diese Weise aufgerufen werden, wird bei jedem Aufruf der CryptAcquireContext-Funktion ein neuer Container erstellt. Verschiedene CSPs können sich in dieser Hinsicht jedoch unterschiedlich verhalten. Insbesondere kann ein CSP über einen einzelnen Standardcontainer verfügen, der von allen Anwendungen gemeinsam genutzt wird, die auf den CSP zugreifen. Daher dürfen Anwendungen den Standardschlüsselcontainer nicht zum Speichern privater Schlüssel verwenden. Verhindern Sie stattdessen die Schlüsselspeicherung, indem Sie das CRYPT_VERIFYCONTEXT-Flag im dwFlags-Parameter übergeben, oder verwenden Sie einen anwendungsspezifischen Container, der wahrscheinlich nicht von einer anderen Anwendung verwendet wird.
Eine Anwendung kann den Namen des verwendeten Schlüsselcontainers abrufen, indem sie die CryptGetProvParam-Funktion zum Lesen des PP_CONTAINER Werts verwendet.
Aus Leistungsgründen empfiehlt es sich, den szContainer-Parameter auf NULL und den dwFlags-Parameter auf CRYPT_VERIFYCONTEXT in allen Situationen festzulegen, in denen Sie keinen dauerhaften Schlüssel benötigen. Erwägen Sie insbesondere das Festlegen des szContainer-Parameters auf NULL und des dwFlags-Parameters auf CRYPT_VERIFYCONTEXT für die folgenden Szenarien:
- Sie erstellen einen Hash.
- Sie generieren einen symmetrischen Schlüssel zum Verschlüsseln oder Entschlüsseln von Daten.
- Sie leiten einen symmetrischen Schlüssel aus 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 abgerufen werden, wenn Sie nur den öffentlichen Schlüssel importieren möchten.
- Sie planen, einen symmetrischen Schlüssel zu exportieren, ihn jedoch nicht innerhalb der Lebensdauer des Kryptokontexts zu importieren. Ein Kontext kann mithilfe des CRYPT_VERIFYCONTEXT-Flags abgerufen werden, wenn Sie den öffentlichen Schlüssel nur für die letzten beiden Szenarien importieren möchten.
- Sie führen Vorgänge mit privaten Schlüsseln aus, verwenden jedoch keinen dauerhaften privaten Schlüssel, der in einem Schlüsselcontainer gespeichert ist.
Beispiele
Das folgende Beispiel zeigt das Abrufen eines kryptografischen Kontexts und des Zugriffs auf öffentliche/private Schlüsselpaare in einem Schlüsselcontainer. 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äprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| 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 |