CryptSignCertificate-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CryptSignCertificate-Funktion signiert die "zu signierten" Informationen im codierten signierten Inhalt.

Syntax

BOOL CryptSignCertificate(
  [in]      BCRYPT_KEY_HANDLE           hBCryptKey,
  [in]      DWORD                       dwKeySpec,
  [in]      DWORD                       dwCertEncodingType,
  [in]      const BYTE                  *pbEncodedToBeSigned,
  [in]      DWORD                       cbEncodedToBeSigned,
  [in]      PCRYPT_ALGORITHM_IDENTIFIER pSignatureAlgorithm,
  [in]      const void                  *pvHashAuxInfo,
  [out]     BYTE                        *pbSignature,
  [in, out] DWORD                       *pcbSignature
);

Parameter

[in] hBCryptKey

Handle des CSP , der die Signatur ausführt. Bei diesem Handle muss es sich um ein HCRYPTPROV-Handle sein, das mithilfe der CryptAcquireContext-Funktion oder eines NCRYPT_KEY_HANDLE-Handle erstellt wurde, das mithilfe der NCryptOpenKey-Funktion erstellt wurde. Neue Anwendungen sollten immer im NCRYPT_KEY_HANDLE Handle eines CNG-CSP übergeben werden.

[in] dwKeySpec

Gibt den privaten Schlüssel an, der aus dem Container des Anbieters verwendet werden soll. Es kann AT_KEYEXCHANGE oder AT_SIGNATURE sein. Dieser Parameter wird ignoriert, wenn ein NCRYPT_KEY_HANDLE im hCryptProvOrNCryptKey-Parameter verwendet wird.

[in] dwCertEncodingType

Gibt den verwendeten Codierungstyp an. Es ist immer akzeptabel, sowohl den Zertifikat- als auch den Nachrichtencodierungstyp anzugeben, indem sie mit einem bitweisen OR-Vorgang kombiniert werden, wie im folgenden Beispiel gezeigt:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Derzeit definierte Codierungstypen sind:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] pbEncodedToBeSigned

Ein Zeiger auf den codierten Inhalt, der signiert werden soll.

[in] cbEncodedToBeSigned

Die Größe des codierten Inhalts in Bytes , pbEncodedToBeSigned.

[in] pSignatureAlgorithm

Ein Zeiger auf eine CRYPT_ALGORITHM_IDENTIFIER-Struktur , bei der ein pszObjId-Member auf einen der folgenden Elemente festgelegt ist:

szOID_RSA_MD5RSA
szOID_RSA_SHA1RSA
szOID_X957_SHA1DSA
szOID_RSA_SSA_PSS
szOID_ECDSA_SPECIFIED

Wenn der Signaturalgorithmus ein Hashalgorithmus ist, enthält die Signatur nur die nicht verschlüsselten Hash oktette. Ein privater Schlüssel wird nicht verwendet, um den Hash zu verschlüsseln. dwKeySpec wird nicht verwendet, und hCryptProvOrNCryptKey kann NULL sein, wenn ein entsprechender Standard-CSP für das Hashing verwendet werden kann.

[in] pvHashAuxInfo

Derzeit nicht verwendet. Muss NULL sein.

[out] pbSignature

Ein Zeiger auf einen Puffer, um den signierten Hash des Inhalts zu empfangen.

Dieser Parameter kann NULL sein, um die Größe dieser Informationen für Speicherzuordnungszwecke festzulegen. Weitere Informationen finden Sie unter Abrufen von Daten unbekannter Länge.

[in, out] pcbSignature

Ein Zeiger auf ein DWORD , das die Größe des Puffers in Bytes enthält, auf den der pbSignature-Parameter verweist. Wenn die Funktion zurückgibt, enthält das DWORD die Anzahl der im Puffer gespeicherten oder zu speichernden Bytes.

Hinweis Bei der Verarbeitung der im Puffer zurückgegebenen Daten müssen Anwendungen die tatsächliche Größe der zurückgegebenen Daten verwenden. Die tatsächliche Größe kann etwas kleiner sein als die Größe des Puffers, der bei der Eingabe angegeben wird. (Bei der Eingabe werden Puffergrößen normalerweise groß genug angegeben, um sicherzustellen, dass die größtmöglichen Ausgabedaten in den Puffer passen.) Bei der Ausgabe wird die Variable aktualisiert, auf die dieser Parameter verweist, um die tatsächliche Größe der in den Puffer kopierten Daten widerzuspiegeln.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert nonzero (TRUE).

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Hinweis Fehler aus den aufgerufenen Funktionen CryptCreateHash, CryptSignHash und CryptHashData können an diese Funktion weitergegeben werden.

Diese Funktion weist die folgenden Fehlercodes auf.

Rückgabecode	Beschreibung
ERROR_MORE_DATA	Wenn der vom pbSignature-Parameter angegebene Puffer nicht groß genug ist, um die zurückgegebenen Daten aufzunehmen, legt die Funktion den ERROR_MORE_DATA Code fest und speichert die erforderliche Puffergröße in Bytes in der Variablen, auf die von pcbSignature verwiesen wird.
NTE_BAD_ALGID	Der Objektbezeichner (Object Identifier, OID) des Signaturalgorithmus wird keinem bekannten oder unterstützten Hashalgorithmus zugeordnet.

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	Crypt32.lib
DLL	Crypt32.dll

Weitere Informationen

CryptSignAndEncodeCertificate

Datenverwaltung-Funktionen

Freigeben über