Funzione CertNameToStrA (wincrypt.h)

  • Articolo

La funzione CertNameToStr converte un nome codificato in una struttura CERT_NAME_BLOB in una stringa di caratteri con terminazione null.

La rappresentazione stringa segue le specifiche del nome distinto in RFC 1779. Le eccezioni a questa regola sono elencate nella sezione Osservazioni, di seguito.

Sintassi

DWORD CertNameToStrA(
  [in]  DWORD           dwCertEncodingType,
  [in]  PCERT_NAME_BLOB pName,
  [in]  DWORD           dwStrType,
  [out] LPSTR           psz,
  [in]  DWORD           csz
);

Parametri

[in] dwCertEncodingType

Tipo di codifica del certificato usato per codificare il nome. 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
X509_ASN_ENCODING
1 (0x1)
 Specifica la codifica del certificato X.509.

[in] pName

Puntatore alla struttura CERT_NAME_BLOB da convertire.

[in] dwStrType

Questo parametro specifica il formato della stringa di output. Questo parametro specifica anche altre opzioni per il contenuto della stringa.

Questo parametro può avere uno dei valori seguenti.

Valore Significato
CERT_SIMPLE_NAME_STR
1
 Tutti gli identificatori di oggetto (OID) vengono eliminati. CERT_RDN voci sono separate da una virgola seguita da uno spazio (, ). Più attributi in un CERT_RDN sono separati da un segno più racchiuso in spazi ( + ), ad esempio Microsoft, Kim Abercrombie + Programmatore.
CERT_OID_NAME_STR
2
 Gli ID sono inclusi con un separatore di uguale segno (=) dal valore dell'attributo. CERT_RDN voci sono separate da una virgola seguita da uno spazio (, ). Più attributi in un CERT_RDN sono separati da un segno più seguito da uno spazio (+ ).
CERT_X500_NAME_STR
3
 Gli ID vengono convertiti nei nomi delle chiavi X.500 ; altrimenti, sono uguali a CERT_OID_NAME_STR. Se un OID non ha un nome X.500 corrispondente, l'OID viene usato con un prefisso OID.

Il valore RDN viene citato se contiene spazi vuoti iniziali o finali o uno dei caratteri seguenti:

  • Virgola (,)
  • Segno più (+)
  • Segno di uguale (=)
  • Segno di pollice (")
  • Barra rovesciata seguita dalla lettera n (\n)
  • Minore di segno (<)
  • Segno maggiore (>)
  • Segno numero (#)
  • Punto e virgola (;)
Il carattere di virgolette è un segno di pollice ("). Se il valore RDN contiene un segno di pollice, è racchiuso tra virgolette ("").
 

Le opzioni seguenti possono essere combinate anche con il valore precedente per specificare opzioni aggiuntive per la stringa.

Valore Significato
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Sostituire la virgola seguita da uno spazio (, ) separatore con un punto e virgola seguito da uno spazio (; ) separatore.
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Sostituire la virgola seguita da uno spazio (, ) separatore con una barra rovesciata seguita dalla lettera r seguita da una barra rovesciata seguita dalla lettera n (\r\n) separatore.
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Sostituire il segno più racchiuso tra spazi ( + ) separatore con un singolo separatore di spazio.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Disabilitare la citazione.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 L'ordine delle reti RDN nella stringa di nome distinto viene invertito dopo la decodifica. Questo flag non è impostato per impostazione predefinita.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 Per impostazione predefinita, una stringa di chiave X.500 CERT_RDN_T61_STRING viene decodificata come UTF8. Se la decodifica UTF8 ha esito negativo, la chiave X.500 viene decodificata come carattere a 8 bit. Usare CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG per ignorare il tentativo iniziale di decodificare come UTF8.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Se il nome a cui punta il parametro pName contiene un messaggio di posta elettronica RDN e la parte del nome host dell'indirizzo di posta elettronica contiene un IA5String con codifica Punycode, il nome viene convertito nell'equivalente Unicode.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato.

[out] psz

Puntatore a un buffer di caratteri che riceve la stringa restituita. Le dimensioni di questo buffer vengono specificate nel parametro csz .

[in] csz

Dimensioni, in caratteri, del buffer psz . Le dimensioni devono includere il carattere Null terminante.

Valore restituito

Restituisce il numero di caratteri convertiti, incluso il carattere Null terminante.

Se psz è NULL o csz è zero, restituisce le dimensioni necessarie della stringa di destinazione.

Commenti

Se psz non è NULL e csz non è zero, la psz restituita è sempre una stringa con terminazione null.

È consigliabile usare RDN multicomponente (ad esempio CN=James+O=Microsoft) per evitare possibili problemi di ordinamento quando si verifica la decodifica. Prendere invece in considerazione l'uso di RDN con valori singoli(ad esempio CN=James, O=Microsoft).

La rappresentazione stringa segue le specifiche del nome distinto in RFC 1779 , ad eccezione delle deviazioni descritte nell'elenco seguente.

  • I nomi che contengono virgolette sono racchiusi tra virgolette doppie.
  • Le stringhe vuote sono racchiuse tra virgolette doppie.
  • Le stringhe che contengono spazi consecutivi non sono racchiuse tra virgolette.
  • I valori di nome distinto relativo (RDN) di tipo CERT_RDN_ENCODED_BLOB o CERT_RDN_OCTET_STRING vengono formattati in esadecimale.
  • Se un OID non ha un nome X.500 corrispondente, il prefisso "OID" viene usato prima dell'OID.
  • I valori RDN sono racchiusi tra virgolette doppie anziché "\") se contengono spazi vuoti iniziali, spazi vuoti finali o uno dei caratteri seguenti:
    • Virgola (,)
    • Segno più (+)
    • Segno di uguale (=)
    • Segno di pollice (")
    • Barra rovesciata (/)
    • Segno minore (<)
    • Segno maggiore di (>)
    • Segno di numero (#)
    • Punto e virgola (;)
  • Il nome della chiave X.500 per stateOrProvinceName (2.5.4.8) è "S". Questo valore è diverso dal nome della chiave X.500 X.500 RFC 1779 ("ST").
Inoltre, i nomi di chiave X.500 seguenti non sono indicati in RFC 1779, ma possono essere restituiti da questa API:
Chiave Stringa dell'identificatore di oggetto
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
 

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

   
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

Vedi anche

CertRDNValueToStr

CertStrToName

Funzioni di conversione dei dati