Funzione CertStrToNameA (wincrypt.h)
La funzione CertStrToName converte una stringa X.500 con terminazione null in un nome certificato codificato.
Sintassi
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
);
Parametri
[in] dwCertEncodingType
Tipo di codifica del certificato usato per codificare la stringa. L'identificatore del tipo di codifica del messaggio , contenuto nell'alto WORD di questo valore, viene ignorato da questa funzione.
Questo parametro può essere il seguente tipo di codifica del certificato attualmente definito.
| Valore | Significato |
|---|---|
|
Specifica la 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 l'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 non vengono combinati flag con l'identificatore di tipo stringa, la stringa può contenere una virgola (,) o un punto e virgola (;) come separatori nel nome distinto relativo (RDN) e un segno più (+) come separatore in più valori RDN.
Le virgolette ("") sono supportate. Una citazione può essere inclusa in un valore virgolette usando due set di virgolette, ad esempio CN="User ""one"".
Un valore che inizia con un segno di numero (#) viene considerato esadecimale ASCII 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.
Spazio vuoto che circonda le chiavi, gli identificatori di oggetto e i valori vengono ignorati.
Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Questo tipo di stringa non è supportato. |
|
Convalida che il tipo di stringa sia supportato. La stringa può essere un identificatore di oggetto (OID) o un nome X.500. |
|
Identico a CERT_OID_NAME_STR. Convalida che il tipo di stringa sia supportato. La stringa può essere un identificatore di oggetto (OID) o un nome X.500. |
Le opzioni seguenti possono essere combinate anche con il valore precedente per specificare opzioni aggiuntive per la stringa.
| Valore | Significato |
|---|---|
|
Solo una virgola (,) è supportata come separatore RDN. |
|
Solo un punto e virgola (;) è supportato come separatore RDN. |
|
Solo una barra rovesciata r (\r) o barra rovesciata n (\n) è supportata come separatore RDN. |
|
Il segno più (+) viene ignorato come separatore e più valori per RDN non sono supportati. |
|
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 anziché 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 chiave X.500 da codificare come stringa UTF-8 (CERT_RDN_UTF8_STRING) anziché come stringa Unicode stampabile (CERT_RDN_PRINTABLE_STRING). Si tratta del valore predefinito per le autorità di certificazione Microsoft a partire da Windows Server 2003. |
|
Impedisce di forzare una chiave Unicode stampabile (CERT_RDN_PRINTABLE_STRING) X.500 da codificare usando UTF-8 (CERT_RDN_UTF8_STRING). Usare per abilitare la codifica di 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 all'esterno 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 l'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 pcbEncoded .
Questo parametro può essere NULL per ottenere le dimensioni necessarie del buffer a scopo di allocazione della memoria. Per altre informazioni, vedere Recupero dei 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 restituisce, la DWORD contiene il numero di byte archiviati nel buffer.
Se pbEncoded è NULL, la DWORD riceve le dimensioni, in byte, necessarie per il buffer.
[out, optional] ppszError
Puntatore a un puntatore di stringa che riceve informazioni di errore aggiuntive su una stringa di input non valida.
Se la stringa pszX500 non è valida, ppszError viene aggiornata da questa funzione per puntare 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.
Commenti
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 valore.
| Chiave | Stringa dell'identificatore di oggetto | Identificatore stringa | Tipi di valore RDN |
|---|---|---|---|
| CN | 2.5.4.3 | szOID_COMMON_NAME |
Carattere stampabile T61 |
| L | 2.5.4.7 | szOID_LOCALITY_NAME |
Carattere stampabile T61 |
| O | 2.5.4.10 | szOID_ORGANIZATION_NAME |
Carattere stampabile T61 |
| OU | 2.5.4.11 | szOID_ORGANIZATIONAL_UNIT_NAME |
Carattere stampabile T61 |
|
E |
1.2.840.113549.1.9.1 | szOID_RSA_emailAddr | IA5 |
| C | 2.5.4.6 | szOID_COUNTRY_NAME | Carattere stampabile |
|
S ST |
2.5.4.8 | szOID_STATE_OR_PROVINCE_NAME |
Carattere stampabile T61 |
| STREET | 2.5.4.9 | szOID_STREET_ADDRESS |
Carattere stampabile T61 |
|
T Titolo |
2.5.4.12 | szOID_TITLE |
Carattere stampabile T61 |
|
G GivenName |
2.5.4.42 | szOID_GIVEN_NAME |
Carattere stampabile T61 |
|
I Iniziali |
2.5.4.43 | szOID_INITIALS |
Carattere stampabile T61 |
| SN | 2.5.4.4 | szOID_SUR_NAME |
Carattere 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.
Esempio
Per un esempio che usa questa funzione, vedere Esempio di programma C: Conversione di nomi da certificati ad ASN.1 e Indietro.
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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | wincrypt.h |
| Libreria | Crypt32.lib |
| DLL | Crypt32.dll |