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 |
|---|---|
|
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 |
|---|---|
|
Dieser Zeichenfolgentyp wird nicht unterstützt. |
|
Überprüft, ob der Zeichenfolgentyp unterstützt wird. Die Zeichenfolge kann entweder ein Objektbezeichner (OID) oder ein X.500-Name sein. |
|
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 |
|---|---|
|
Als RDN-Trennzeichen wird nur ein Komma (,) unterstützt. |
|
Nur ein Semikolon (;) wird als RDN-Trennzeichen unterstützt. |
|
Nur ein umgekehrter Schrägstrich r (\r) oder umgekehrter Schrägstrich n (\n) wird als RDN-Trennzeichen unterstützt. |
|
Das Pluszeichen (+) wird als Trennzeichen ignoriert, und mehrere Werte pro RDN werden nicht unterstützt. |
|
Zitate werden nicht unterstützt. |
|
Die Reihenfolge der RDNs in einem distinguished Name wird vor der Codierung umgekehrt. Dieses Flag ist nicht standardmäßig festgelegt. |
|
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. |
|
Der CERT_RDN_UTF8_STRING codierte Werttyp wird anstelle von CERT_RDN_UNICODE_STRING verwendet. |
|
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. |
|
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. |
|
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 |
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 |