Freigeben über

CertStrToNameA-Funktion (wincrypt.h)

  • Artikel

Die CertStrToName--Funktion wandelt eine mit Null beendete X.500- zeichenfolge in einen codierten Zertifikatnamen um.

Syntax

BOOL CertStrToNameA(
  [in]            DWORD  dwCertEncodingType,
  [in]            LPCSTR pszX500,
  [in]            DWORD  dwStrType,
  [in, optional]  void   *pvReserved,
  [out]           BYTE   *pbEncoded,
  [in, out]       DWORD  *pcbEncoded,
  [out, optional] LPCSTR *ppszError
);

Parameter

[in] dwCertEncodingType

Der Zertifikatcodierungstyp, der zum Codieren der Zeichenfolge verwendet wurde. Der Nachrichtencodierungstyp Bezeichners, der in der hohen WORD- dieses Werts enthalten ist, wird von dieser Funktion ignoriert.

Dieser Parameter kann der folgende aktuell definierte Zertifikatcodierungstyp sein.

Wert Bedeutung
X509_ASN_ENCODING
1 (0x1)
 Gibt X.509 Zertifikatcodierung an.

[in] pszX500

Ein Zeiger auf die X.500-Zeichenfolge, die null beendet wird, wird konvertiert. Das Format dieser Zeichenfolge wird durch den dwStrType-Parameter angegeben.

Diese Zeichenfolge wird voraussichtlich mit der Ausgabe der CertNameToStr--Funktion formatiert.

[in] dwStrType

Dieser Parameter gibt den Typ der Zeichenfolge an. Dieser Parameter gibt auch weitere Optionen für den Inhalt der Zeichenfolge an.

Wenn keine Kennzeichnungen mit dem Zeichenfolgentypbezeichner kombiniert werden, kann die Zeichenfolge ein Komma (,) oder ein Semikolon (;) als Trennzeichen in der relativen Distinguished Name (RDN) und ein Pluszeichen (+) als Trennzeichen in mehreren RDN-Werten enthalten.

Anführungszeichen ("") werden unterstützt. Ein Anführungszeichen kann in einen Anführungszeichenwert eingeschlossen werden, indem zwei Anführungszeichen verwendet werden, z. B. CN="User ""one"""".

Ein Wert, der mit einem Zahlenzeichen (#) beginnt, wird als ASCII- hexadezimal behandelt und in eine CERT_RDN_OCTET_STRINGkonvertiert. Eingebettetes Leerzeichen wird ignoriert. Beispielsweise ist 1.2.3 = # AB CD 01 identisch mit 1.2.3=#ABCD01.

Leerzeichen, die die Schlüssel, Objektbezeichner und Werte umgeben, werden ignoriert.

Dieser Parameter kann einer der folgenden Werte sein:

Wert Bedeutung
CERT_SIMPLE_NAME_STR
1
 Dieser Zeichenfolgentyp wird nicht unterstützt.
CERT_OID_NAME_STR
2
 Überprüft, ob der Zeichenfolgentyp unterstützt wird. Die Zeichenfolge kann entweder ein Objektbezeichner (OID) oder ein X.500-Name sein.
CERT_X500_NAME_STR
3
 Identisch mit CERT_OID_NAME_STR. Überprüft, ob der Zeichenfolgentyp unterstützt wird. Die Zeichenfolge kann entweder ein Objektbezeichner (OID) oder ein X.500-Name sein.
 

Die folgenden Optionen können auch mit dem obigen Wert kombiniert werden, um zusätzliche Optionen für die Zeichenfolge anzugeben.

Wert Bedeutung
CERT_NAME_STR_COMMA_FLAG
0x04000000
 Nur ein Komma (,) wird als RDN-Trennzeichen unterstützt.
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Nur ein Semikolon (;) wird als RDN-Trennzeichen unterstützt.
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Nur ein umgekehrter Schrägstrich r (\r) oder umgekehrter Schrägstrich n (\n) wird als RDN-Trennzeichen unterstützt.
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Das Pluszeichen (+) wird als Trennzeichen ignoriert, und mehrere Werte pro RDN werden nicht unterstützt.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Die Quotierung wird nicht unterstützt.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 Die Reihenfolge der RDNs in einem distinguished-Namen wird vor der Codierung umgekehrt. Diese Kennzeichnung ist standardmäßig nicht festgelegt.
CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000
 Der CERT_RDN_T61_STRING codierte Werttyp wird anstelle von CERT_RDN_UNICODE_STRINGverwendet. Dieses Kennzeichen kann verwendet werden, wenn alle Unicode-Zeichen kleiner oder gleich 0xFF sind.
CERT_NAME_STR_ENABLE_UTF8_UNICODE_FLAG
0x00040000
 Der CERT_RDN_UTF8_STRING codierte Werttyp wird anstelle von CERT_RDN_UNICODE_STRINGverwendet.
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
 Erzwingt die Codierung des X.500-Schlüssels als UTF-8-Zeichenfolge (CERT_RDN_UTF8_STRING) und nicht als druckbare Unicode-Zeichenfolge (CERT_RDN_PRINTABLE_STRING). Dies ist der Standardwert für Microsoft-Zertifizierungsstellen ab Windows Server 2003.
CERT_NAME_STR_DISABLE_UTF8_DIR_STR_FLAG
0x00100000
 Verhindert, dass ein druckbarer Unicode-Schlüssel (CERT_RDN_PRINTABLE_STRING) X.500 mithilfe von UTF-8 (CERT_RDN_UTF8_STRING) codiert wird. Wird verwendet, um die Codierung von X.500-Schlüsseln als Unicode-Werte zu aktivieren, wenn CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG festgelegt ist.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Wenn die Zeichenfolge einen E-Mail-RDN-Wert enthält und die E-Mail-Adresse Unicode-Zeichen außerhalb des ASCII-Zeichensatzes enthält, wird der Hostnamenteil der E-Mail-Adresse in Punycode codiert. Die resultierende E-Mail-Adresse wird dann als IA5String- Zeichenfolge codiert. Die Punycode-Codierung des Hostnamens wird auf Bezeichnungsbasis ausgeführt.

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

[in, optional] pvReserved

Reserviert für die zukünftige Verwendung und muss NULL-sein.

[out] pbEncoded

Ein Zeiger auf einen Puffer, der die codierte Struktur empfängt.

Die Größe dieses Puffers wird im pcbEncoded Parameter angegeben.

Dieser Parameter kann NULL- sein, um die erforderliche Größe des Puffers für Speicherzuweisungszwecke abzurufen. Weitere Informationen finden Sie unter Abrufen von Daten unbekannter Länge.

[in, out] pcbEncoded

Ein Zeiger auf eine DWORD-, die vor dem Aufrufen der Funktion die Größe des Puffers in Bytes enthält, auf den der pbEncoded-Parameter verweist. Wenn die Funktion zurückgegeben wird, enthält die DWORD- die Anzahl der im Puffer gespeicherten Bytes.

Wenn pbEncoded-NULL-ist, empfängt die DWORD- die Größe in Bytes, die für den Puffer erforderlich ist.

[out, optional] ppszError

Ein Zeiger auf einen Zeichenfolgenzeiger, der zusätzliche Fehlerinformationen zu einer ungültigen Eingabezeichenfolge empfängt.

Wenn die pszX500 Zeichenfolge ungültig ist, wird ppszError von dieser Funktion aktualisiert, um auf den Anfang der ungültigen Zeichensequenz zu verweisen. Wenn in der Eingabezeichenfolge keine Fehler erkannt werden, wird ppszError- auf NULL-festgelegt.

Wenn diese Informationen nicht erforderlich sind, übergeben Sie NULL- für diesen Parameter.

Dieser Parameter wird für die folgenden Fehlercodes aktualisiert, die von GetLastErrorzurückgegeben werden.

CRYPT_E_INVALID_X500_STRING

CRYPT_E_INVALID_NUMERIC_STRING

CRYPT_E_INVALID_PRINTABLE_STRING

CRYPT_E_INVALID_IA5_STRING

Rückgabewert

Gibt "nonzero" zurück, wenn dies erfolgreich oder null ist.

Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.

Bemerkungen

Die folgende Tabelle enthält die unterstützten X.500-Schlüssel, deren entsprechende Objektbezeichnerzeichenfolge, Zeichenfolgenbezeichner (von Wincrypt.h) und Werttypen.

Schlüssel Objektbezeichnerzeichenfolge Zeichenfolgenbezeichner RDN-Werttypen
CN 2.5.4.3 szOID_COMMON_NAME Druckbar

T61
L 2.5.4.7 szOID_LOCALITY_NAME Druckbar

T61
O 2.5.4.10 szOID_ORGANIZATION_NAME Druckbar

T61
OU 2.5.4.11 szOID_ORGANIZATIONAL_UNIT_NAME Druckbar

T61
E

E-Mail

 1.2.840.113549.1.9.1 szOID_RSA_emailAddr IA5
C 2.5.4.6 szOID_COUNTRY_NAME Druckbar
S

ST

 2.5.4.8 szOID_STATE_OR_PROVINCE_NAME Druckbar

T61
STRAßE 2.5.4.9 szOID_STREET_ADDRESS Druckbar

T61
T

Titel

 2.5.4.12 szOID_TITLE Druckbar

T61
G

GivenName

 2.5.4.42 szOID_GIVEN_NAME Druckbar

T61
Ich

Initialen

 2.5.4.43 szOID_INITIALS Druckbar

T61
SN 2.5.4.4 szOID_SUR_NAME Druckbar

T61
GLEICHSTROM 0.9.2342.19200300.100.1.25 szOID_DOMAIN_COMPONENT IA5

UTF8
 

Wenn entweder "Druckbar" oder "T61" als RDN-Werttyp für den Schlüssel zulässig ist, wird "Drucken" automatisch ausgewählt, wenn die Namenszeichenfolgenkomponente ein Element der folgenden Zeichensätze ist:

  • A, B, ..., Z
  • a, b, ..., z
  • 0, 1, …, 9
  • (Leerzeichen) ' ( ) + , - . / : = ?

Die T61-Typen sind UTF8-codiert.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Konvertieren von Namen aus Zertifikaten in ASN.1 und zurück.

Anmerkung

Der wincrypt.h-Header definiert CertStrToName 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
mindestens unterstützte Client- Windows XP [Desktop-Apps | UWP-Apps]
mindestens unterstützte Server- Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform- Fenster
Header- wincrypt.h
Library Crypt32.lib
DLL- Crypt32.dll

Siehe auch

CertNameToStr-

Datenkonvertierungsfunktionen

GetLastError-

Abrufen von Daten unbekannter Länge