CertNameToStrA-Funktion (wincrypt.h)

  • Artikel

Die CertNameToStr-Funktion konvertiert einen codierten Namen in einer CERT_NAME_BLOB-Struktur in eine NULL-Zeichenfolge.

Die Zeichenfolgendarstellung folgt den Distinguished Name-Spezifikationen in RFC 1779. Die Ausnahmen von 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 Bezeichner des Nachrichtencodierungstyps , der im hohen WORD-Wert dieses Werts enthalten ist, wird von dieser Funktion ignoriert.

Bei diesem Parameter kann es sich um den folgenden aktuell definierten Zertifikatcodierungstyp handeln.

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

[in] pName

Ein Zeiger auf die CERT_NAME_BLOB Struktur, die konvertiert werden soll.

[in] dwStrType

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

Dieser Parameter kann einen der folgenden Werte annehmen.

Wert Bedeutung
CERT_SIMPLE_NAME_STR
1
 Alle Objektbezeichner (Object Identifiers , OIDs) werden verworfen. CERT_RDN Einträge werden durch ein Komma gefolgt von einem Leerzeichen (, ) getrennt. 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 (=)-Trennzeichen von ihrem Attributwert enthalten. CERT_RDN Einträge werden durch ein Komma gefolgt von einem Leerzeichen (, ) getrennt. Mehrere Attribute in einem 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_STR identisch. Wenn eine OID keinen entsprechenden X.500-Namen aufweist, wird die OID mit dem Präfix OID verwendet.

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

  • Komma (,)
  • Pluszeichen (+)
  • Gleichheitszeichen (=)
  • Zollmarke (")
  • Umgekehrter Schrägstrich gefolgt vom Buchstaben n (\n)
  • Kleiner als Vorzeichen (<)
  • Größer als Vorzeichen (>)
  • Nummernzeichen (#)
  • Semikolon (;)
Das Anführungszeichen ist eine Zollmarke ("). Wenn der RDN-Wert eine Zollmarke 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 Leerzeichentrennzeichen (, ) durch ein Semikolon gefolgt von einem Leerzeichenzeichen (; ).
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 Trennzeichen n (\r\n).
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Ersetzen Sie das in Leerzeichen ( + ) eingeschlossene Pluszeichen durch ein einzelnes Leerzeichen.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Deaktivieren Sie das Zitieren.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 Die Reihenfolge der RDNs in der Distinguished Name-Zeichenfolge wird nach der Decodierung umgekehrt. Dieses Flag ist nicht standardmäßig 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 ersten Versuch zu überspringen, als UTF8 zu decodieren.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Wenn der Name, auf den der pName-Parameter verweist, ein E-Mail-RDN enthält und der Hostnamenteil der E-Mail-Adresse einen Punycode-codierten 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 beendenden NULL-Zeichens.

Wenn pszNULL oder csz null ist, gibt die erforderliche Größe der Zielzeichenfolge zurück.

Hinweise

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

Es wird davon abgeraten, RDNs mit mehreren Komponenten (z. B. CN=James+O=Microsoft) zu verwenden, um mögliche Bestellprobleme bei der Decodierung zu vermeiden. Erwägen Sie stattdessen die Verwendung einzelner RDNs (z. B. CN=James, O=Microsoft).

Die Zeichenfolgendarstellung folgt den Distinguished Name-Spezifikationen in RFC 1779 mit Ausnahme der 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 aufeinanderfolgende Leerzeichen enthalten, werden nicht in Anführungszeichen eingeschlossen.
  • Relative Distinguished Name (RDN)-Werte vom Typ CERT_RDN_ENCODED_BLOB oder CERT_RDN_OCTET_STRING sind hexadezimal formatiert.
  • Wenn eine OID keinen entsprechenden X.500-Namen aufweist, wird das Präfix "OID" vor der 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 (=)
    • Zollmarke (")
    • Umgekehrter Schrägstrich (/)
    • Kleiner als Vorzeichen (<)
    • Größer als Vorzeichen (>)
    • Nummernzeichen (#)
    • Semikolon (;)
  • Der X.500-Schlüsselname für stateOrProvinceName (2.5.4.8) OID lautet "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 jedoch 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
I 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.

Hinweis

Der wincrypt.h-Header definiert CertNameToStr 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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile wincrypt.h
Bibliothek Crypt32.lib
DLL Crypt32.dll

Weitere Informationen

CertRDNValueToStr

CertStrToName

Datenkonvertierungsfunktionen