Função CertNameToStrA (wincrypt.h)

  • Artigo

A função CertNameToStr converte um nome codificado em uma estrutura CERT_NAME_BLOB em uma cadeia de caracteres terminada em nulo.

A representação de cadeia de caracteres segue as especificações de nome diferenciadas no RFC 1779. As exceções a essa regra são listadas na seção Comentários, abaixo.

Sintaxe

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

Parâmetros

[in] dwCertEncodingType

O tipo de codificação de certificado que foi usado para codificar o nome. O identificador de tipo de codificação de mensagem , contido no WORD alto desse valor, é ignorado por essa função.

Esse parâmetro pode ser o seguinte tipo de codificação de certificado definido no momento.

Valor Significado
X509_ASN_ENCODING
1 (0x1)
 Especifica a codificação de certificado X.509.

[in] pName

Um ponteiro para a estrutura CERT_NAME_BLOB a ser convertida.

[in] dwStrType

Esse parâmetro especifica o formato da cadeia de caracteres de saída. Esse parâmetro também especifica outras opções para o conteúdo da cadeia de caracteres.

Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
CERT_SIMPLE_NAME_STR
1
 Todos os OIDs ( identificadores de objeto ) são descartados. CERT_RDN entradas são separadas por uma vírgula seguida por um espaço (, ). Vários atributos em uma CERT_RDN são separados por um sinal de adição entre espaços ( + ), por exemplo, Microsoft, Kim Abercrombie + Programador.
CERT_OID_NAME_STR
2
 Os OIDs são incluídos com um separador de sinal de igual (=) de seu valor de atributo. CERT_RDN entradas são separadas por uma vírgula seguida por um espaço (, ). Vários atributos em um CERT_RDN são separados por um sinal de adição seguido por um espaço (+ ).
CERT_X500_NAME_STR
3
 Os OIDs são convertidos em seus nomes de chave X.500 ; caso contrário, eles são iguais aos CERT_OID_NAME_STR. Se um OID não tiver um nome X.500 correspondente, o OID será usado com um prefixo de OID.

O valor rdn será citado se contiver espaço em branco à esquerda ou à direita ou um dos seguintes caracteres:

  • Vírgula (,)
  • Sinal de adição (+)
  • Sinal de igual (=)
  • Marca de polegada (")
  • Barra invertida seguida pela letra n (\n)
  • Sinal menor que (<)
  • Sinal maior que (>)
  • Sinal de número (#)
  • Ponto-e-vírgula (;)
O caractere de aspas é uma marca de polegada ("). Se o valor rdn contiver uma marca de polegada, ele será colocado entre aspas ("").
 

As opções a seguir também podem ser combinadas com o valor acima para especificar opções adicionais para a cadeia de caracteres.

Valor Significado
CERT_NAME_STR_SEMICOLON_FLAG
0x40000000
 Substitua a vírgula seguida por um separador de espaço (, ) por um ponto e vírgula seguido por um separador de espaço (; ).
CERT_NAME_STR_CRLF_FLAG
0x08000000
 Substitua a vírgula seguida por um separador de espaço (, ) por uma barra invertida seguida pela letra r seguida por uma barra invertida seguida pelo separador de letra n (\r\n).
CERT_NAME_STR_NO_PLUS_FLAG
0x20000000
 Substitua o sinal de adição entre espaços ( + ) separador por um separador de espaço único.
CERT_NAME_STR_NO_QUOTING_FLAG
0x10000000
 Desabilitar aspas.
CERT_NAME_STR_REVERSE_FLAG
0x02000000
 A ordem dos RDNs na cadeia de caracteres de nome diferenciado é invertida após a decodificação. Esse sinalizador não é definido por padrão.
CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG
0x00010000
 Por padrão, uma cadeia de caracteres de chave X.500 CERT_RDN_T61_STRING é decodificada como UTF8. Se a decodificação UTF8 falhar, a chave X.500 será decodificada como um caractere de 8 bits. Use CERT_NAME_STR_DISABLE_IE4_UTF8_FLAG para ignorar a tentativa inicial de decodificar como UTF8.
CERT_NAME_STR_ENABLE_PUNYCODE_FLAG
0x00200000
 Se o nome apontado pelo parâmetro pName contiver um RDN de email e a parte do nome do host do endereço de email contiver uma IA5String codificada por Punycode, o nome será convertido no equivalente Unicode.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor.

[out] psz

Um ponteiro para um buffer de caracteres que recebe a cadeia de caracteres retornada. O tamanho desse buffer é especificado no parâmetro csz .

[in] csz

O tamanho, em caracteres, do buffer psz . O tamanho deve incluir o caractere nulo de terminação.

Valor retornado

Retorna o número de caracteres convertidos, incluindo o caractere nulo de terminação.

Se psz for NULL ou csz for zero, retornará o tamanho necessário da cadeia de caracteres de destino.

Comentários

Se psz não for NULL e csz não for zero, o psz retornado sempre será uma cadeia de caracteres terminada em nulo.

É recomendável não usar RDNs multicomponentes (por exemplo, CN=James+O=Microsoft) para evitar possíveis problemas de ordenação durante a decodificação. Em vez disso, considere usar RDNs com valor único (por exemplo, CN=James, O=Microsoft).

A representação de cadeia de caracteres segue as especificações de nome diferenciadas no RFC 1779 , exceto pelos desvios descritos na lista a seguir.

  • Os nomes que contêm aspas estão entre aspas duplas.
  • Cadeias de caracteres vazias são colocadas entre aspas duplas.
  • Cadeias de caracteres que contêm espaços consecutivos não estão entre aspas.
  • Os valores rdn (nome diferenciado relativo) do tipo CERT_RDN_ENCODED_BLOB ou CERT_RDN_OCTET_STRING são formatados em hexadecimal.
  • Se uma OID não tiver um nome X.500 correspondente, o prefixo "OID" será usado antes do OID.
  • Os valores RDN serão colocados entre aspas duplas (em vez de "\") se contiverem espaço em branco à esquerda, espaço em branco à direita ou um dos seguintes caracteres:
    • Vírgula (,)
    • Sinal de adição (+)
    • Sinal de igual (=)
    • Marca de polegada (")
    • Barra invertida (/)
    • Sinal menor que (<)
    • Sinal maior que (>)
    • Sinal de número (#)
    • Ponto-e-vírgula (;)
  • O nome da chave X.500 para stateOrProvinceName (2.5.4.8) OID é "S". Esse valor é diferente do nome da chave RFC 1779 X.500 ("ST").
Além disso, os seguintes nomes de chave X.500 não são mencionados no RFC 1779, mas podem ser retornados por esta API:
Chave Cadeia de caracteres do identificador de objeto
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
 

Exemplos

Para obter um exemplo que usa essa função, consulte

Exemplo de programa C: convertendo nomes de certificados em ASN.1 e Back.

Observação

O cabeçalho wincrypt.h define CertNameToStr como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

   
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho wincrypt.h
Biblioteca Crypt32.lib
DLL Crypt32.dll

Confira também

CertRDNValueToStr

CertStrToName

Funções de conversão de dados