Freigeben über


CertStrToNameA-Funktion (wincrypt.h)

Die CertStrToName-Funktion konvertiert eine X.500-Zeichenfolge mit NULL-Termin in einen codierten Zertifikatnamen.

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 Bezeichner des Nachrichtencodierungstyps , der im hohen WORD dieses Werts enthalten ist, wird von dieser Funktion ignoriert.

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

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

[in] pszX500

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

Es wird erwartet, dass diese Zeichenfolge genauso formatiert ist wie die Ausgabe der CertNameToStr-Funktion .

[in] dwStrType

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

Wenn keine Flags mit dem Zeichenfolgentypbezeichner kombiniert werden, kann die Zeichenfolge ein Komma (,) oder ein Semikolon (;) als Trennzeichen im 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 eingefügt werden, indem zwei Anführungszeichensätze verwendet werden, z. B. CN="User ""one""".

Ein Wert, der mit einem Zahlenzeichen (#) beginnt, wird als ASCII-Hexadezimalzeichen behandelt und in ein CERT_RDN_OCTET_STRING konvertiert. Eingebetteter Leerraum wird ignoriert. Beispielsweise ist 1.2.3 = # AB CD 01 identisch mit 1.2.3=#ABCD01.

Leerzeichen, die die Schlüssel, Objektbezeichner und Werte umschließen, werden ignoriert.

Dieser Parameter kann einen der folgenden Werte annehmen.

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
Als RDN-Trennzeichen wird nur ein Komma (,) 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
Zitate werden nicht unterstützt.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
Die Reihenfolge der RDNs in einem distinguished Name wird vor der Codierung umgekehrt. Dieses Flag ist nicht standardmäßig festgelegt.
CERT_NAME_STR_ENABLE_T61_UNICODE_FLAG
0x00020000
Der CERT_RDN_T61_STRING codierte Werttyp wird anstelle von CERT_RDN_UNICODE_STRING verwendet. Dieses Flag 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_STRING verwendet.
CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG
0x00080000
Erzwingt, dass der X.500-Schlüssel als UTF-8-Zeichenfolge (CERT_RDN_UTF8_STRING) und nicht als druckbare Unicode-Zeichenfolge (CERT_RDN_PRINTABLE_STRING) codiert wird. 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-X.500-Schlüssel (CERT_RDN_PRINTABLE_STRING) mithilfe von UTF-8 (CERT_RDN_UTF8_STRING) codiert wird. Verwenden Sie , 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 bezeichnungsweise ausgeführt.

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

[in, optional] pvReserved

Für die zukünftige Verwendung reserviert und muss NULL sein.

[out] pbEncoded

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

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

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

[in, out] pcbEncoded

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

Wenn pbEncodedNULL ist, erhält das DWORD die für den Puffer erforderliche Größe in Bytes.

[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 Zeichenfolge 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 GetLastError zurü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 ungleich null zurück, wenn erfolgreich oder andernfalls null.

Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Hinweise

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
E

ST

2.5.4.8 szOID_STATE_OR_PROVINCE_NAME Druckbar

T61

STREET 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

I

Initials

2.5.4.43 szOID_INITIALS Druckbar

T61

SN 2.5.4.4 szOID_SUR_NAME Druckbar

T61

DC 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 druckbar automatisch ausgewählt, wenn die Namenszeichenfolgenkomponente mitglied 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.

Hinweis

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
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

CertNameToStr

Datenkonvertierungsfunktionen

GetLastError

Abrufen von Daten unbekannter Länge