Export (0) Print
Expand All

IX509Enrollment::InstallResponse method

The InstallResponse method installs a certificate chain on the end-entity computer. The byte array that contains the response is encoded by using Distinguished Encoding Rules (DER) as defined by the Abstract Syntax Notation One (ASN.1) standard. You must specify the DER-encoded byte array in a string that is either a pure binary sequence or is Unicode encoded. This method is web enabled.

Syntax


HRESULT InstallResponse(
  [in]            InstallResponseRestrictionFlags Restrictions,
  [in]            BSTR strResponse,
  [in]            EncodingType Encoding,
  [in, optional]  BSTR strPassword
);

Parameters

Restrictions [in]

An InstallResponseRestrictionFlags enumeration value that specifies the type of certificates that can be installed. This can be one or more of the following values.

ValueMeaning
AllowNone

Do not install untrusted certificates or certificates for which there is no corresponding request.

AllowNoOutstandingRequest

Create the private key from the certificate response rather than from the dummy certificate. This makes the dummy certificate optional. If this value is not set, the dummy certificate must exist, and the private key is extracted from it.

AllowUntrustedCertificate

Install untrusted end entity and certification authority certificates. Certification authority certificates include root and subordinate CA certificates. End entity certificates are installed to the personal store, and CA certificates are installed to the certification authority store.

AllowUntrustedRoot

Perform the same action as the AllowUntrustedCertificate flag but also installs the certificate even if the certificate chain cannot be built because the root is not trusted.

Note  On Windows Vista, the behavior of this flag is the same as that defined for the AllowUntrustedCertificate flag. Beginning with Windows Vista with SP1, you can install a certificate that chains up to an untrusted root.

 

strResponse [in]

A BSTR variable that contains the DER-encoded response.

Encoding [in]

An EncodingType enumeration value that specifies the type of encoding applied to the string that contains the DER-encoded response.

strPassword [in, optional]

An optional password for the certificate installation. This can be NULL or an empty string to indicate that no password is used. If there is a password, clear it from memory when you have finished using it by calling the SecureZeroMemory function. For more information about protecting the password, see Handling Passwords.

Beginning with Windows 8 and Windows Server 2012, a NULL or empty password may mean that the PFX packet was created in the PFXExportCertStoreEx function by using the PKCS12_PROTECT_TO_DOMAIN_SIDS flag. If so, the PFX was encrypted to an Active Directory group. For more information, see PFXExportCertStoreEx and PFXImportCertStore.

Return value

If the function succeeds, the function returns S_OK.

If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Return codeDescription
E_ACCESSDENIED

This method was called from the web and either AllowNoOutstandingRequest or AllowUntrustedCertificate was specified in the Restrictions parameter.

HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW

The length of the string that contains the password exceeds 64 kilobytes.

OLE_E_BLANK

The enrollment object has not been initialized.

 

Remarks

The InstallResponse method:

  1. Retrieves the dummy certificate from the external store.
  2. Retrieves the certificate contained in the response and installs it on the computer.
  3. Copies properties from the dummy certificate in the external store onto the newly installed certificate in the personal store.

Before calling the InstallResponse method, you must initialize the IX509Enrollment object by calling one of the following methods.

If you call this method from the web, you can specify only AllowNone or AllowUntrustedRoot in the Restrictions parameter. If you specify AllowNoOutstandingRequest or AllowUntrustedCertificate, the method returns an E_ACCESSDENIED error.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

CertEnroll.h

DLL

CertEnroll.dll

See also

IX509Enrollment

 

 

Community Additions

ADD
Show:
© 2014 Microsoft