Método IX509CertificateRequestPkcs10::GetCspStatuses (certenroll.h)

  • Artigo

O método GetCspStatuses recupera uma coleção ICspStatuses que contém todos os pares de provedor/algoritmo consistentes com o uso pretendido da chave privada, conforme especificado pelo chamador.

Sintaxe

HRESULT GetCspStatuses(
  [in]  X509KeySpec  KeySpec,
  [out] ICspStatuses **ppCspStatuses
);

Parâmetros

[in] KeySpec

Um valor de enumeração X509KeySpec que especifica o uso pretendido da chave. Esse pode ser um dos valores a seguir.

Valor Significado
XCN_AT_NONE
 Somente API de Criptografia: provedores de CNG (Próxima Geração) são selecionados.
XCN_AT_KEYEXCHANGE
 Somente CSPs ( provedores de serviços criptográficos ) de CryptoAPI com algoritmos de criptografia (incluindo troca de chaves) são selecionados.
XCN_AT_SIGNATURE
 Somente CSPs de CryptoAPI com algoritmos de assinatura são selecionados.

[out] ppCspStatuses

Endereço de uma variável que recebe um ponteiro para uma interface ICspStatuses que representa a coleção.

Retornar valor

Se a função for bem-sucedida, a função retornará S_OK.

Se a função falhar, ela retornará um valor HRESULT que indica o erro. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir. Para obter uma lista de códigos de erro comuns, consulte Valores HRESULT comuns.

Código de retorno Descrição
CERTSRV_E_PROPERTY_EMPTY
 A chave privada não pode ser encontrada.
OLE_E_BLANK
 O objeto não é inicializado.

Comentários

Esse método recupera uma coleção de objetos ICspStatus . Cada objeto representa um único par de provedores/algoritmos. Se você especificar um modelo ao inicializar o objeto de solicitação IX509CertificateRequestPkcs10 , atributos de modelo como pKIDefaultCSPs e pKIDefaultKeySpec afetarão quais pares estão inicialmente habilitados. Você pode chamar as seguintes propriedades em cada objeto ICspStatus para recuperar informações sobre um par:

  • A propriedade CspInformation recupera informações do provedor.
  • A propriedade CspAlgorithm recupera informações de algoritmo.
  • A propriedade EnrollmentStatus recupera um objeto IX509EnrollmentStatus . Chame a propriedade Selected no objeto status para determinar se o par provedor/algoritmo está habilitado para essa solicitação.
  • A propriedade Ordinal recupera a posição na coleção de pares de provedor/algoritmo.

A coleção recuperada por esse método é salva internamente no objeto de solicitação. Até três coleções, uma para cada valor KeySpec , podem ser criadas e salvas. Isso é feito para preservar o estado de seleção dos pares de provedor/algoritmo para que as páginas de propriedades relevantes possam ser exibidas com precisão e rapidez várias vezes e para que o método Encode possa identificar quais provedores e algoritmos serão selecionados se uma chave privada precisar ser criada. Se o estado de seleção de um par de provedores/algoritmos for modificado, as alterações serão salvas na coleção apropriada. As alterações feitas nos membros de uma coleção não afetam os membros de nenhuma outra coleção. As coleções existem desde que o objeto PKCS nº 10 continue existindo.

Suponha, por exemplo, que esse método seja chamado com o parâmetro KeySpec definido como XCN_AT_SIGNATURE e que um modelo seja usado para inicializar a solicitação. As seguintes instruções serão verdadeiras:

  • Uma coleção de objetos ICspStatus é criada e salva no objeto IX509CertificateRequestPkcs10 . A coleção contém todos os pares de provedor/algoritmo válidos instalados no computador.
  • Como o parâmetro KeySpec não está definido como XCN_AT_NONE, a propriedade Selected é definida como SelectedNo para cada par de provedor/algoritmo CNG (Cryptography API: Next Generation) na coleção.
  • Como o parâmetro KeySpec não está definido como XCN_AT_KEYEXCHANGE, a propriedade Selected é definida como SelectedNo para cada par CSP/algoritmo cryptoAPI na coleção em que o algoritmo pode ser usado para criptografar dados ou arquivar uma chave.
  • Para cada provedor referenciado pelo modelo ou chave privada, mas sem suporte no computador, um objeto de espaço reservado ICspStatus é criado e adicionado à coleção e a propriedade Selected é definida como SelectedNo.
  • A propriedade Selected é definida como SelectedYes para cada par CSP/algoritmo cryptoAPI em que o algoritmo só pode ser usado para assinar dados.
  • A propriedade Ordinal é definida para refletir a ordem CSP, se houver, identificada pelo atributo de modelo pKIDefaultCSPs . Os CSPs listados primeiro pelo atributo são ordenados primeiro na coleção. Essa propriedade será usada durante o registro se uma chave privada precisar ser criada. O primeiro par CSP/algoritmo selecionado é usado para criar a chave, mas se a operação falhar, o próximo par selecionado será tentado.
  • Chamar esse método novamente com o mesmo parâmetro KeySpec recupera um ponteiro para a coleção existente criada anteriormente para esse valor de parâmetro.
  • Chamar esse método novamente com um parâmetro KeySpec diferente não afetará a coleção criada para o valor XCN_AT_SIGNATURE KeySpec . Além disso, alterar a propriedade Selected em qualquer membro da nova coleção não afeta nenhum membro da coleção anterior.

O método GetCspStatuses difere da propriedade CspStatuses usando o parâmetro KeySpec . O método permite que os usuários especifiquem esse valor, mas a propriedade usa o valor definido na chave privada associada ao objeto de solicitação.

Você deve inicializar o objeto IX509CertificateRequestPkcs10 antes de chamar esse método. Para obter mais informações, consulte qualquer um dos seguintes métodos:

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho certenroll.h
DLL CertEnroll.dll

Confira também

IX509CertificateRequestPkcs10