Função CertStrToNameA (wincrypt.h)
A função CertStrToName converte uma cadeia de caracteres X.500 terminada em nulo em um nome de certificado codificado.
Sintaxe
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
);
Parâmetros
[in] dwCertEncodingType
O tipo de codificação de certificado que foi usado para codificar a cadeia de caracteres. 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 |
|---|---|
|
Especifica a codificação de certificado X.509 . |
[in] pszX500
Um ponteiro para a cadeia de caracteres X.500 terminada em nulo a ser convertida. O formato dessa cadeia de caracteres é especificado pelo parâmetro dwStrType .
Espera-se que essa cadeia de caracteres seja formatada da mesma forma que a saída da função CertNameToStr .
[in] dwStrType
Esse parâmetro especifica o tipo da cadeia de caracteres. Esse parâmetro também especifica outras opções para o conteúdo da cadeia de caracteres.
Se nenhum sinalizador for combinado com o especificador de tipo de cadeia de caracteres, a cadeia de caracteres poderá conter uma vírgula (,) ou um ponto-e-vírgula (;) como separadores no RDN (nome diferenciado relativo ) e um sinal de adição (+) como separador em vários valores RDN.
Há suporte para aspas (""). Uma aspa pode ser incluída em um valor entre aspas usando dois conjuntos de aspas, por exemplo, CN="Usuário ""um"".
Um valor que começa com um sinal numérico (#) é tratado como ASCII hexadecimal e convertido em um CERT_RDN_OCTET_STRING. O espaço em branco inserido é ignorado. Por exemplo, 1.2.3 = # AB CD 01 é igual a 1.2.3=#ABCD01.
O espaço em branco que envolve as chaves, os identificadores de objeto e os valores é ignorado.
Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Não há suporte para esse tipo de cadeia de caracteres. |
|
Valida se há suporte para o tipo de cadeia de caracteres. A cadeia de caracteres pode ser um OID (identificador de objeto ) ou um nome X.500. |
|
Idêntico a CERT_OID_NAME_STR. Valida se há suporte para o tipo de cadeia de caracteres. A cadeia de caracteres pode ser um OID (identificador de objeto ) ou um nome X.500. |
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 |
|---|---|
|
Há suporte apenas para uma vírgula (,) como separador rdn. |
|
Há suporte apenas para um ponto e vírgula (;) como separador rdn. |
|
Somente uma barra invertida r (\r) ou barra invertida n (\n) tem suporte como separador rdn. |
|
O sinal de adição (+) é ignorado como separador e não há suporte para vários valores por RDN. |
|
Não há suporte para aspas. |
|
A ordem dos RDNs em um nome diferenciado é invertida antes da codificação. Esse sinalizador não é definido por padrão. |
|
O tipo de valor codificado CERT_RDN_T61_STRING é usado em vez de CERT_RDN_UNICODE_STRING. Esse sinalizador poderá ser usado se todos os caracteres Unicode forem menores ou iguais a 0xFF. |
|
O tipo de valor codificado CERT_RDN_UTF8_STRING é usado em vez de CERT_RDN_UNICODE_STRING. |
|
Força a chave X.500 a ser codificada como uma cadeia de caracteres UTF-8 (CERT_RDN_UTF8_STRING) em vez de como uma cadeia de caracteres Unicode imprimível (CERT_RDN_PRINTABLE_STRING). Esse é o valor padrão para as autoridades de certificação da Microsoft a partir do Windows Server 2003. |
|
Impede forçar uma chave X.500 unicode imprimível (CERT_RDN_PRINTABLE_STRING) a ser codificada usando UTF-8 (CERT_RDN_UTF8_STRING). Use para habilitar a codificação de chaves X.500 como valores Unicode quando CERT_NAME_STR_FORCE_UTF8_DIR_STR_FLAG for definido. |
|
Se a cadeia de caracteres contiver um valor RDN de email e o endereço de email contiver caracteres Unicode fora do conjunto de caracteres ASCII, a parte do nome do host do endereço de email será codificada em Punycode. O endereço de email resultante é codificado como uma cadeia de caracteres IA5String . A codificação punycode do nome do host é executada em uma base de rótulo por rótulo.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
[in, optional] pvReserved
Reservado para uso futuro e deve ser NULL.
[out] pbEncoded
Um ponteiro para um buffer que recebe a estrutura codificada.
O tamanho desse buffer é especificado no parâmetro pcbEncoded .
Esse parâmetro pode ser NULL para obter o tamanho necessário do buffer para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.
[in, out] pcbEncoded
Um ponteiro para um DWORD que, antes de chamar a função, contém o tamanho, em bytes, do buffer apontado pelo parâmetro pbEncoded . Quando a função retorna, o DWORD contém o número de bytes armazenados no buffer.
Se pbEncoded for NULL, o DWORD receberá o tamanho, em bytes, necessário para o buffer.
[out, optional] ppszError
Um ponteiro para um ponteiro de cadeia de caracteres que recebe informações de erro adicionais sobre uma cadeia de caracteres de entrada que não é válida.
Se a cadeia de caracteres pszX500 não for válida, ppszError será atualizado por essa função para apontar para o início da sequência de caracteres que não é válida. Se nenhum erro for detectado na cadeia de caracteres de entrada, ppszError será definido como NULL.
Se essas informações não forem necessárias, passe NULL para esse parâmetro.
Esse parâmetro é atualizado para os seguintes códigos de erro retornados de GetLastError.
CRYPT_E_INVALID_X500_STRING
CRYPT_E_INVALID_NUMERIC_STRING
CRYPT_E_INVALID_PRINTABLE_STRING
CRYPT_E_INVALID_IA5_STRING
Retornar valor
Retornará diferente de zero se tiver êxito ou zero caso contrário.
Para obter informações de erro estendidas, chame GetLastError.
Comentários
A tabela a seguir contém as chaves X.500 com suporte, a cadeia de caracteres do identificador de objeto correspondente, o identificador de cadeia de caracteres (de Wincrypt.h) e os tipos de valor.
| Chave | Cadeia de caracteres do identificador de objeto | Identificador de cadeia de caracteres | Tipos de valor RDN |
|---|---|---|---|
| CN | 2.5.4.3 | szOID_COMMON_NAME |
Imprimível T61 |
| L | 2.5.4.7 | szOID_LOCALITY_NAME |
Imprimível T61 |
| O | 2.5.4.10 | szOID_ORGANIZATION_NAME |
Imprimível T61 |
| OU | 2.5.4.11 | szOID_ORGANIZATIONAL_UNIT_NAME |
Imprimível T61 |
|
E |
1.2.840.113549.1.9.1 | szOID_RSA_emailAddr | IA5 |
| C | 2.5.4.6 | szOID_COUNTRY_NAME | Imprimível |
|
S ST |
2.5.4.8 | szOID_STATE_OR_PROVINCE_NAME |
Imprimível T61 |
| RUA | 2.5.4.9 | szOID_STREET_ADDRESS |
Imprimível T61 |
|
T Título |
2.5.4.12 | szOID_TITLE |
Imprimível T61 |
|
G GivenName |
2.5.4.42 | szOID_GIVEN_NAME |
Imprimível T61 |
|
I Iniciais |
2.5.4.43 | szOID_INITIALS |
Imprimível T61 |
| SN | 2.5.4.4 | szOID_SUR_NAME |
Imprimível T61 |
| DC | 0.9.2342.19200300.100.1.25 | szOID_DOMAIN_COMPONENT |
IA5 UTF8 |
Se Printable ou T61 for permitido como o tipo de valor RDN para a chave, Printable será selecionado automaticamente se o componente de cadeia de caracteres de nome for um membro dos seguintes conjuntos de caracteres:
- A, B, ..., Z
- a, b, ..., z
- 0, 1, ..., 9
- (espaço) ' ( ) + , - . / : = ?
Os tipos T61 são codificados em UTF8.
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 CertStrToName 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
| Requisito | Valor |
|---|---|
| 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de