3.1.4.1.26 ICertAdminD::ImportCertificate (Opnum 28)

Article
06/24/2021

The ImportCertificate method imports a certificate into the CA database.

 HRESULT ImportCertificate(
   [in, string, unique] wchar_t const* pwszAuthority,
   [in, ref] CERTTRANSBLOB* pctbCertificate,
   [in] LONG dwFlags,
   [out] LONG* pdwRequestId
 );

pwszAuthority: See the pwszAuthority definition in section 3.1.4.1.1.

pctbCertificate: A CERTTRANSBLOB that contains an ASN.1 DER–encoded (as specified in [X660] and [X690]) certificate that is inserted into the CA database.

dwFlags: A LONG value that MUST take one of the following values.

Value	Meaning
0	If this value is set, the CA server does not allow certificates that are not issued by it to be imported into its database.
FLAG_ALLOW_IMPORT_FOREIGN 0x00010000	A request to the CA server to allow certificates that are not issued by it to be imported into its database.
ICF_EXISTINGROW 0x00020000	A request to the CA to associate the imported certificates with an existing request row.

Value

Meaning

If this value is set, the CA server does not allow certificates that are not issued by it to be imported into its database.

FLAG_ALLOW_IMPORT_FOREIGN

0x00010000

A request to the CA server to allow certificates that are not issued by it to be imported into its database.

ICF_EXISTINGROW

0x00020000

A request to the CA to associate the imported certificates with an existing request row.

pdwRequestId: Returns the request ID for the imported certificate. This is used to refer to the certificate after it is imported into the database.

ImportCertificate imports a certificate into the CA database Request table.

The CA server MUST apply the following processing rules:

The CA server MUST enforce that the pctbCertificate parameter value represents an ASN.1 DER–encoded certificate (as specified in [X660]). If not, it MUST fail with the error ERROR_INVALID_DATA (0x8007000D).
The CA server MUST validate the signature on the certificate by using the public key that is associated with the CA's signing certificates.
If the ICF_EXISTINGROW flag is not passed as the value of dwFlags, if the signature validation succeeds (at step 2), and if the certificate does not already exist in the Request table (this is checked by searching on the Serial_Number in the certificate in the database), the certificate MUST be added to the Request table as a new row and the CA MUST return the resulting Request_Request_ID to the client. For processing rules for each data element in the Request table, see the ImportCertificate data element in the following table.
If the ICF_EXISTINGROW flag is not passed as the value of dwFlags, if the signature validation succeeds (at step 2), and if the certificate is already present in the Request table, the CA MUST fail with the error ERROR_OBJECT_EXISTS.
If the ICF_EXISTINGROW flag is passed as the value of dwFlags, if the signature validation succeeds (at step 2), and if the certificate does not already exist in the Request table (this is checked by searching on the Serial_Number in the certificate in the database):

The CA MUST locate an entry in the Request table whose Request_Disposition is "request pending" and whose Request_ID has an entry in the Extensions table with a Subject Key Identifier equal to the SubjectKeyIdentifier extension of the certificate that is passed as pctbCertificate.
1. If the entry is found in the Request Table, the CA MUST update the fields from the information in the certificate. For processing rules for each data element in the Request table, see the ImportCertificate processing rules in the following table. The CA MUST return the Request_Request_ID of the updated Request table row as the pdwRequestId parameter.
2. If the entry is not found in the Request table, the CA MUST fail with the error 0x80092009 (CRYPT_E_NO_MATCH).
If the signature validation fails (at step 2) and FLAG_ALLOW_IMPORT_FOREIGN is not passed as a value of dwFlags, the CA MUST fail with the error 0x800b0107, according to the ImportCertificate data element processing rules in the following table.
If the signature validation fails (at step 2) and FLAG_ALLOW_IMPORT_FOREIGN is passed as value of dwFlags and the certificate is already present in the Request table, the CA SHOULD return the resulting Request_Request_ID to the client. For processing rules for each data element in the Request table, see the ImportCertificate processing rules in the following table.<61>
If the signature validation fails (at step 2), if FLAG_ALLOW_IMPORT_FOREIGN is passed as the value of dwFlags, and if the certificate is not already present in the Request table, the certificate SHOULD be added to the Request table as a new row and the CA SHOULD return the resulting Request_Request_ID to the client. For processing rules for each data element in the Request table, see the ImportCertificate data element in the following table.<62>

The certificate fields and extensions SHOULD be processed and stored in individual Request table fields according to the rules in the following table.

Data type	Maximum size of data	Data element name	Processing rule or x.509 certificate field or extension
0x10001 long indexed	4 bytes	Request_Request_ID	The next sequential number after Request_Request_ID of the last database row.
0x1 long	4 bytes	"Request_Status_Code"	If the import is successful, the CA SHOULD set this value to 0.
0x10001 long indexed	4 bytes	"Request_Disposition"	If the certificate being imported was issued by a foreign CA, set Request_Disposition to "foreign certificate". The Microsoft CA uses a DB_DISP_FOREIGN value that is equal to decimal 12 for "foreign certificate". Otherwise, set to "certificate issued".
0x4 string	8192 bytes	"Request_Disposition_Message"	The CA SHOULD set the value of the Request_Disposition_Message column to any value the implementer considers informative for presentation to a human. The Microsoft CA sets Request_Disposition_Message in this case to "certificate issued".
0x10002 date indexed	8 bytes	"Request_Submitted_When"	The time when the method is invoked.
0x10002 date indexed	8 bytes	"Request_Resolved_When"	The time when the method is invoked.
0x10004 string indexed	2048 bytes	"Request_Requester_Name"	The identity of the caller invoking the method.
0x10004 string indexed	2048 bytes	"Request_Caller_Name"	The identity of the caller invoking the method.
0x3 bin	4096 bytes	"Request_Raw_Name"	The raw subject information from the certificate.
0x4 string	8192 bytes	"Request_Country"	The country attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Organization"	The organization attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Org_Unit"	The organizational-unit attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Common_Name"	The common name attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Locality"	The locality attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_State"	The state or province name attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Title"	The title attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Given_Name"	The given name attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Initials"	The initials attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_SurName"	The surname attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_Domain_Component"	The domainComponent attribute of the certificate Subject.
0x4 string	8192 bytes	"Request_EMail"	The [RFC822] Name from Subject Alternative Name.
0x4 string	8192 bytes	"Request_Device_Serial_Number"	The serial number attribute of the certificate Subject.
0x10001 long indexed	4 bytes	"Request_ID"	The next sequential number after Request_Request_ID of the last database row.
0x3 bin	16384 bytes	"Raw_Certificate"	The byte stream that is pointed to in the parameter pctbCertificate ->pb member.
0x10004 string indexed	128 bytes	"Certificate_Hash"	The SHA-1 hash over the value of "Raw_Certificate".
0x10004 string indexed	254 bytes	"Certificate_Template"	The extnValue of extension with OID (1) 1.3.6.1.4.1.311.20.2.
0x10004 string indexed	128 bytes	"Serial_Number"	The serial number ([RFC3280] section 4.1.2.2) of the certificate.
0x2 date	8 bytes	"Not_Before"	The Validity::notBefore ([RFC3280] section 4.1.2.5) field of the certificate.
0x10002 date indexed	8 bytes	"Not_After"	The Validity::notAfter ([RFC3280] section 4.1.2.5) field of the certificate.
0x4 string	128 bytes	"Subject_Key_Identifier"	The Value of the SubjectKeyIdentifier ([RFC3280] section 4.2.1.2) extension of the certificate.
0x3 bin	4096 bytes	"Raw_Public_Key"	The raw value of the public key that is associated with the certificate. (SubjectPublicKeyInfo->subjectPublicKey).
0x1 long	4 bytes	"Public_Key_Length"	The length, in bits, of the public key that is associated with the certificate (SubjectPublicKeyInfo->subjectPublicKey).
0x4 string	254 bytes	"Public_Key_Algorithm"	The name of the algorithm that is associated with the public key of the certificate (SubjectPublicKeyInfo->algorithm->algorithm).
0x3 bin	4096 bytes	"Raw_Public_Key_Algorithm_Parameters"	The raw value of the parameters that are associated with the public key of the certificate (SubjectPublicKeyInfo->algorithm->parameters).
0x4 string	8192 bytes	"Distinguished_Name"	The Subject ([RFC3280] section 4.1.2.6) field of the certificate.
0x4 string	8192 bytes	"Country"	The country attribute of the certificate Subject.
0x4 string	8192 bytes	"Organization"	The organization attribute of the certificate Subject.
0x4 string	8192 bytes	"OrgUnit"	The organizational-unit attribute of the certificate Subject.
0x10004 string indexed	8192 bytes	"Common_Name"	The common name (CN) attribute of the certificate Subject.
0x4 string	8192 bytes	"Locality"	The locality attribute of the certificate Subject.
0x4 string	8192 bytes	"State"	The state or province name attribute of the certificate Subject.
0x4 string	8192 bytes	"Title"	The title attribute of the certificate Subject.
0x4 string	8192 bytes	"Given_Name"	The given name attribute of the certificate Subject.
0x4 string	8192 bytes	"Initials"	The initials attribute of the certificate Subject.
0x4 string	8192 bytes	"SurName"	The surname attribute of the certificate Subject.
0x4 string	8192 bytes	"Domain_Component"	The DomainComponent attribute of the certificate Subject.
0x4 string	8192 bytes	"EMail"	The [RFC822] Name from Subject Alternative Name.
0x4 string	8192 bytes	"Device_Serial_Number"	The serial number attribute of the certificate Subject.

3.1.4.1.26 ICertAdminD::ImportCertificate (Opnum 28)

Additional resources