Funzione CertStrToNameW (wincrypt.h)
La funzione CertStrToName converte una stringa con terminazione Null X.500 in un nome di certificato codificato.
Sintassi
BOOL CertStrToNameW(
[in] DWORD dwCertEncodingType,
[in] LPCWSTR pszX500,
[in] DWORD dwStrType,
[in, optional] void *pvReserved,
[out] BYTE *pbEncoded,
[in, out] DWORD *pcbEncoded,
[out, optional] LPCWSTR *ppszError
);
Parametri
[in] dwCertEncodingType
Tipo di codifica del certificato utilizzato per codificare la stringa. Il tipo di codifica
Questo parametro può essere il tipo di codifica del certificato attualmente definito seguente.
| Valore | Significato |
|---|---|
|
Specifica codifica del certificato X.509. |
[in] pszX500
Puntatore alla stringa X.500 con terminazione Null da convertire. Il formato di questa stringa viene specificato dal parametro dwStrType.
Questa stringa deve essere formattata come output dalla funzione CertNameToStr.
[in] dwStrType
Questo parametro specifica il tipo della stringa. Questo parametro specifica anche altre opzioni per il contenuto della stringa.
Se nessun flag viene combinato con l'identificatore di tipo stringa, la stringa può contenere una virgola (,) o un punto e virgola (;) come separatori nella nome distinto relativo (RDN) e un segno più (+) come separatore in più valori RDN.
Le virgolette ("") sono supportate. Una virgoletta può essere inclusa in un valore tra virgolette usando due set di virgolette, ad esempio CN="User ""one""".
Un valore che inizia con un segno di numero (#) viene considerato come ASCII esadecimale e convertito in un CERT_RDN_OCTET_STRING. Lo spazio vuoto incorporato viene ignorato. Ad esempio, 1.2.3 = # AB CD 01 è uguale a 1.2.3=#ABCD01.
Gli spazi vuoti che racchiudono le chiavi, gli identificatori di oggetto e i valori vengono ignorati.
Questo parametro può essere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Questo tipo di stringa non è supportato. |
|
Verifica che il tipo stringa sia supportato. La stringa può essere un identificatore di oggetto (OID) o un nome X.500. |
|
Identico a CERT_OID_NAME_STR. Verifica che il tipo stringa sia supportato. La stringa può essere un identificatore di oggetto (OID) o un nome X.500. |
È anche possibile combinare le opzioni seguenti con il valore precedente per specificare opzioni aggiuntive per la stringa.
| Valore | Significato |
|---|---|
|
Come separatore RDN è supportato solo una virgola (,). |
|
Solo un punto e virgola (;) è supportato come separatore RDN. |
|
Solo una barra rovesciata r (\r) o una barra rovesciata n (\n) è supportata come separatore RDN. |
|
Il segno più (+) viene ignorato come separatore e non sono supportati più valori per RDN. |
|
La virgolette non è supportata. |
|
L'ordine dei nomi RDN in un nome distinto viene invertito prima della codifica. Questo flag non è impostato per impostazione predefinita. |
|
Il tipo di valore codificato CERT_RDN_T61_STRING viene usato invece di CERT_RDN_UNICODE_STRING. Questo flag può essere usato se tutti i caratteri Unicode sono minori o uguali a 0xFF. |
|
Il tipo di valore codificato CERT_RDN_UTF8_STRING viene usato anziché CERT_RDN_UNICODE_STRING. |
|
Forza la codifica della chiave X.500 come stringa UTF-8 (CERT_RDN_UTF8_STRING) anziché come stringa Unicode stampabile (CERT_RDN_PRINTABLE_STRING). Questo è il valore predefinito per le autorità di certificazione Microsoft a partire da Windows Server 2003. |
|
Impedisce la codifica di una chiave X.500 Unicode stampabile (CERT_RDN_PRINTABLE_STRING) tramite UTF-8 (CERT_RDN_UTF8_STRING). Usare per abilitare la codifica delle chiavi X.500 come valori Unicode quando viene impostata CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG. |
|
Se la stringa contiene un valore RDN di posta elettronica e l'indirizzo di posta elettronica contiene caratteri Unicode al di fuori del set di caratteri ASCII, la parte del nome host dell'indirizzo di posta elettronica viene codificata in Punycode. L'indirizzo di posta elettronica risultante viene quindi codificato come stringa IA5String. La codifica Punycode del nome host viene eseguita in base all'etichetta.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato. |
[in, optional] pvReserved
Riservato per uso futuro e deve essere NULL.
[out] pbEncoded
Puntatore a un buffer che riceve la struttura codificata.
Le dimensioni di questo buffer vengono specificate nel parametro
Questo parametro può essere NULL per ottenere le dimensioni necessarie del buffer a scopo di allocazione della memoria. Per altre informazioni, vedere Recupero di dati di lunghezza sconosciuta.
[in, out] pcbEncoded
Puntatore a un DWORD che, prima di chiamare la funzione, contiene le dimensioni, in byte, del buffer a cui punta il parametro pbEncoded. Quando la funzione viene restituita, il DWORD contiene il numero di byte archiviati nel buffer.
Se
[out, optional] ppszError
Puntatore a un puntatore di stringa che riceve informazioni aggiuntive sull'errore su una stringa di input non valida.
Se la stringa di pszX500 non è valida, ppszError viene aggiornata da questa funzione in modo che punti all'inizio della sequenza di caratteri non valida. Se non vengono rilevati errori nella stringa di input, ppszError è impostato su NULL.
Se queste informazioni non sono necessarie, passare NULL per questo parametro.
Questo parametro viene aggiornato per i codici di errore seguenti restituiti da GetLastError.
CRYPT_E_INVALID_X500_STRING
CRYPT_E_INVALID_NUMERIC_STRING
CRYPT_E_INVALID_PRINTABLE_STRING
CRYPT_E_INVALID_IA5_STRING
Valore restituito
Restituisce un valore diverso da zero se ha esito positivo o zero in caso contrario.
Per informazioni sugli errori estesi, chiamare GetLastError.
Osservazioni
La tabella seguente contiene le chiavi X.500 supportate, la stringa dell'identificatore di oggetto corrispondente, l'identificatore stringa (da Wincrypt.h) e i tipi di valore.
| Chiave | Stringa dell'identificatore di oggetto | Identificatore stringa | Tipi di valore RDN |
|---|---|---|---|
| CN | 2.5.4.3 | szOID_COMMON_NAME |
Stampabile T61 |
| L | 2.5.4.7 | szOID_LOCALITY_NAME |
Stampabile T61 |
| O | 2.5.4.10 | szOID_ORGANIZATION_NAME |
Stampabile T61 |
| OU | 2.5.4.11 | szOID_ORGANIZATIONAL_UNIT_NAME |
Stampabile T61 |
|
E |
1.2.840.113549.1.9.1 | szOID_RSA_emailAddr | IA5 |
| C | 2.5.4.6 | szOID_COUNTRY_NAME | Stampabile |
|
S SAN |
2.5.4.8 | szOID_STATE_OR_PROVINCE_NAME |
Stampabile T61 |
| VIA | 2.5.4.9 | szOID_STREET_ADDRESS |
Stampabile T61 |
|
T Titolo |
2.5.4.12 | szOID_TITLE |
Stampabile T61 |
|
G GivenName |
2.5.4.42 | szOID_GIVEN_NAME |
Stampabile T61 |
|
Io Iniziali |
2.5.4.43 | szOID_INITIALS |
Stampabile T61 |
| SN | 2.5.4.4 | szOID_SUR_NAME |
Stampabile T61 |
| DC | 0.9.2342.19200300.100.1.25 | szOID_DOMAIN_COMPONENT |
IA5 UTF8 |
Se Printable o T61 è consentito come tipo di valore RDN per la chiave, Printable viene selezionato automaticamente se il componente stringa del nome è un membro dei set di caratteri seguenti:
- A, B, ..., Z
- a, b, ..., z
- 0, 1, …, 9
- (spazio) ' ( ) + , - . / : = ?
I tipi T61 sono codificati con UTF8.
Esempi
Per un esempio che usa questa funzione, vedere Programma C di esempio: Conversione di nomi da certificati ad ASN.1 e Back.
Nota
L'intestazione wincrypt.h definisce CertStrToName come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [app desktop | App UWP] |
| server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| piattaforma di destinazione | Finestre |
| intestazione |
wincrypt.h |
| libreria |
Crypt32.lib |
| dll | Crypt32.dll |