CertNameToStrA-Funktion (wincrypt.h)

Artikel
11/20/2024

Die CertNameToStr--Funktion wandelt einen codierten Namen in einer CERT_NAME_BLOB Struktur in eine null-beendete Zeichenfolge um.

Die Zeichenfolgendarstellung folgt den distinguished name specifications in RFC 1779. Die Ausnahmen dieser Regel sind im Abschnitt "Hinweise" unten aufgeführt.

Syntax

DWORD CertNameToStrA(
  [in]  DWORD           dwCertEncodingType,
  [in]  PCERT_NAME_BLOB pName,
  [in]  DWORD           dwStrType,
  [out] LPSTR           psz,
  [in]  DWORD           csz
);

Parameter

[in] dwCertEncodingType

Der Zertifikatcodierungstyp, der zum Codieren des Namens 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 die X.509-Zertifikatcodierung an.

[in] pName

Ein Zeiger auf die zu konvertierende CERT_NAME_BLOB Struktur.

[in] dwStrType

Dieser Parameter gibt das Format der Ausgabezeichenfolge an. Dieser Parameter gibt auch weitere Optionen für den Inhalt der Zeichenfolge an.

Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
CERT_SIMPLE_NAME_STR 1	Alle Objektbezeichner (OIDs) werden verworfen. CERT_RDN Einträge werden durch ein Komma getrennt, gefolgt von einem Leerzeichen (, ). Mehrere Attribute in einer CERT_RDN werden durch ein Pluszeichen getrennt, das in Leerzeichen ( + ) eingeschlossen ist, z. B. Microsoft, Kim Abercrombie + Programmierer.
CERT_OID_NAME_STR 2	OIDs sind mit einem Gleichheitszeichen (=) aus ihrem Attributwert enthalten. CERT_RDN Einträge werden durch ein Komma getrennt, gefolgt von einem Leerzeichen (, ). Mehrere Attribute in einer CERT_RDN werden durch ein Pluszeichen gefolgt von einem Leerzeichen (+) getrennt.
CERT_X500_NAME_STR 3	OIDs werden in ihre X.500 Schlüsselnamen konvertiert; andernfalls sind sie mit CERT_OID_NAME_STRidentisch. Wenn ein OID keinen entsprechenden X.500-Namen hat, wird das OID mit einem Präfix von OID verwendet. Der RDN-Wert wird zitiert, wenn er führende oder nachfolgende Leerzeichen oder eines der folgenden Zeichen enthält: Komma (,) Pluszeichen (+) Gleichheitszeichen (=) Zollzeichen (") Umgekehrter Schrägstrich gefolgt vom Buchstaben n (\n) Kleiner als Zeichen (<) Größer als Zeichen (>) Nummernzeichen (#) Semikolon (;) Das Anführungszeichen ist ein Zollzeichen ("). Wenn der RDN-Wert ein Zollzeichen enthält, wird er in Anführungszeichen ("") eingeschlossen.

Wert

Bedeutung

CERT_SIMPLE_NAME_STR
1

Alle Objektbezeichner (OIDs) werden verworfen. CERT_RDN Einträge werden durch ein Komma getrennt, gefolgt von einem Leerzeichen (, ). Mehrere Attribute in einer CERT_RDN werden durch ein Pluszeichen getrennt, das in Leerzeichen ( + ) eingeschlossen ist, z. B. Microsoft, Kim Abercrombie + Programmierer.

CERT_OID_NAME_STR
2

OIDs sind mit einem Gleichheitszeichen (=) aus ihrem Attributwert enthalten. CERT_RDN Einträge werden durch ein Komma getrennt, gefolgt von einem Leerzeichen (, ). Mehrere Attribute in einer CERT_RDN werden durch ein Pluszeichen gefolgt von einem Leerzeichen (+) getrennt.

CERT_X500_NAME_STR
3

OIDs werden in ihre X.500 Schlüsselnamen konvertiert; andernfalls sind sie mit CERT_OID_NAME_STRidentisch. Wenn ein OID keinen entsprechenden X.500-Namen hat, wird das OID mit einem Präfix von OID verwendet.

Der RDN-Wert wird zitiert, wenn er führende oder nachfolgende Leerzeichen oder eines der folgenden Zeichen enthält:

Komma (,)
Pluszeichen (+)
Gleichheitszeichen (=)
Zollzeichen (")
Umgekehrter Schrägstrich gefolgt vom Buchstaben n (\n)
Kleiner als Zeichen (<)
Größer als Zeichen (>)
Nummernzeichen (#)
Semikolon (;)

Das Anführungszeichen ist ein Zollzeichen ("). Wenn der RDN-Wert ein Zollzeichen enthält, wird er in Anführungszeichen ("") eingeschlossen.

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_SEMICOLON_FLAG 0x40000000	Ersetzen Sie das Komma gefolgt von einem Leerzeichen (, ) durch ein Semikolon gefolgt von einem Leerzeichen (; )trennzeichen.
CERT_NAME_STR_CRLF_FLAG 0x08000000	Ersetzen Sie das Komma gefolgt von einem Leerzeichen (, ) durch einen umgekehrten Schrägstrich gefolgt von dem Buchstaben r gefolgt von einem umgekehrten Schrägstrich gefolgt von dem Buchstaben n (\r\n) Trennzeichen.
CERT_NAME_STR_NO_PLUS_FLAG 0x20000000	Ersetzen Sie das Pluszeichen, das in Leerzeichen ( + ) eingeschlossen ist, durch ein einzelnes Leerzeichen.
CERT_NAME_STR_NO_QUOTING_FLAG 0x10000000	Zitate deaktivieren.
CERT_NAME_STR_REVERSE_FLAG 0x02000000	Die Reihenfolge der RDNs in der distinguished name string wird nach der Decodierung umgekehrt. Diese Kennzeichnung ist standardmäßig nicht festgelegt.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG 0x00010000	Standardmäßig wird eine CERT_RDN_T61_STRING X.500-Schlüsselzeichenfolge als UTF8 decodiert. Wenn DIE UTF8-Decodierung fehlschlägt, wird der X.500-Schlüssel als 8-Bit-Zeichen decodiert. Verwenden Sie CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG, um den anfänglichen Versuch zu überspringen, utf8 zu decodieren.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG 0x00200000	Wenn der Name, auf den der pName-Parameter verweist, eine E-Mail-RDN enthält, und der Hostnamenteil der E-Mail-Adresse einen punycodecodierten IA5String-enthält, wird der Name in das Unicode-Äquivalent konvertiert. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

[out] psz

Ein Zeiger auf einen Zeichenpuffer, der die zurückgegebene Zeichenfolge empfängt. Die Größe dieses Puffers wird im csz--Parameter angegeben.

[in] csz

Die Größe des psz- Puffers in Zeichen. Die Größe muss das beendende NULL-Zeichen enthalten.

Rückgabewert

Gibt die Anzahl der konvertierten Zeichen zurück, einschließlich des endenden Nullzeichens.

Wenn psz-null ist oder csz- null ist, wird die erforderliche Größe der Zielzeichenfolge zurückgegeben.

Bemerkungen

Wenn psz- nicht NULL- ist und csz- nicht null ist, ist die zurückgegebene psz- immer eine null-beendete Zeichenfolge.

Wir empfehlen die Verwendung von Multicomponent RDNs (z. B. CN=James+O=Microsoft), um mögliche Sortierprobleme beim Decodieren zu vermeiden. Verwenden Sie stattdessen single valued RDNs (z. B. CN=James, O=Microsoft).

Die Zeichenfolgendarstellung folgt den distinguished name specifications in RFC 1779 außer den in der folgenden Liste beschriebenen Abweichungen.

Namen, die Anführungszeichen enthalten, werden in doppelte Anführungszeichen eingeschlossen.
Leere Zeichenfolgen werden in doppelte Anführungszeichen eingeschlossen.
Zeichenfolgen, die aufeinander folgende Leerzeichen enthalten, werden nicht in Anführungszeichen eingeschlossen.
Relative Distinguished Name (RDN)-Werte vom Typ CERT_RDN_ENCODED_BLOB oder CERT_RDN_OCTET_STRING werden hexadezimal formatiert.
Wenn ein OID keinen entsprechenden X.500-Namen hat, wird das Präfix "OID" vor OID verwendet.
RDN-Werte werden mit doppelten Anführungszeichen (anstelle von "\") eingeschlossen, wenn sie führende Leerzeichen, nachfolgende Leerzeichen oder eines der folgenden Zeichen enthalten:
- Komma (,)
- Pluszeichen (+)
- Gleichheitszeichen (=)
- Zollzeichen (")
- Umgekehrter Schrägstrich (/)
- Kleiner als Zeichen (<)
- Größer als Zeichen (>)
- Nummernzeichen (#)
- Semikolon (;)
Der X.500-Schlüsselname für stateOrProvinceName (2.5.4.8) OID ist "S". Dieser Wert unterscheidet sich vom RFC 1779 X.500-Schlüsselnamen ("ST").

Darüber hinaus werden die folgenden X.500-Schlüsselnamen nicht in RFC 1779 erwähnt, können aber von dieser API zurückgegeben werden:

Schlüssel	Objektbezeichnerzeichenfolge
E	1.2.840.113549.1.9.1
T	2.5.4.12
G	2.5.4.42
Ich	2.5.4.43
SN	2.5.4.4

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 CertNameToStr als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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

CertRDNValueToStr

CertStrToName-

Datenkonvertierungsfunktionen

Freigeben über