MQRegisterCertificate

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MQRegisterCertificate function registers an internal or external certificate in the directory service. Registering a certificate stores the public part of the certificate in the directory service under the applicable user object.

HRESULT APIENTRY MQRegisterCertificate(  
  DWORD dwFlags,    
  PVOID lpCertBuffer,    
  DWORD dwCertBufferLength    
);

Parameters

dwFlags

[in] Specifies when the certificate is registered. Specify one of the following:

MQCERT_REGISTER_ALWAYS

Registers an internal or external certificate each time MQRegisterCertificate is called.

For internal certificates (lpCertBuffer = NULL), a new certificate is created and registered.

For external certificates, this option must be set.

MQCERT_REGISTER_IF_NOT_EXIST

Registers an internal certificate only when none exist. This option cannot be used when registering external certificates.

If an internal certificate is found, the certificate is not registered. In this case, the call succeeds and the MQ_INFORMATION_INTERNAL_USER_CERT_EXIST information code is returned.

Checking for an existing certificate is done locally, without querying the directory service.

lpCertBuffer

[in] Pointer to the buffer that contains the certificate blob of an external certificate, or NULL if registering an internal certificate. External certificates must be in ASN.1 DER encoded format.

dwCertBufferLength

[in] The length of the certificate buffer. For internal certificates, specify 0.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_CANNOT_CREATE_CERT_STORE (0xC00E006F)

Message Queuing cannot create a certificate store for its internal certificate. This error is returned only when you do not have permission to manipulate your own profile.

MQ_ERROR_CANNOT_OPEN_CERT_STORE (0xC00E0070)

Message Queuing cannot open the certificate store for its internal certificate. This error is only returned only when you do not have permission to manipulate your own profile.

MQ_ERROR_ILLEGAL_USER (0xC00E0011)

User is not a domain user. You must be a domain user to be able to register a certificate. This function is not supported for local user accounts.

MQ_ERROR_INTERNAL_USER_CERT_EXIST (0xC00E002E)

The internal or external certificate specified is already registered in Active Directory Domain Services (AD DS) for the user.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

A supplied parameter is not set to a valid value. For example, dwCertBufferLength is set to 0 and lpCertBuffer points to a buffer containing an external certificate.

MQ_ERROR_UNSUPPORTED_OPERATION (0xC00E006A)

A computer operating in workgroup attempted to register a certificate in the directory service.

MQ_INFORMATION_INTERNAL_USER_CERT_EXIST (0x400E000A)

An internal certificate already exists for the user. This information code does not indicate an error condition. It is returned when dwFlags is set to MQ_REGISTER_IF_NOT_EXIST.

Remarks

Message Queuing can only register external certificates placed in the Microsoft® Internet Explorer personal certificate store. To obtain an external certificate, contact a trusted certification authority. For example, request a class 1 certificate from VeriSign Commercial Software Publishers using Microsoft Internet Explorer. If Internet Explorer is used to obtain the certificate, the certificate is automatically placed in the Microsoft Internet Explorer personal certificate store.

Certificates can also be registered in the Message Queuing Properties dialog box, which can be opened from Computer Management in MSMQ 3.0 (or from the applicable Control Panel applet in MSMQ 1.0 and MSMQ 2.0). To register a certificate in MSMQ 3.0, go to the User Certificate page, and then under User certificates, click Register.

Equivalent COM Method

When using COM components, you can register certificates by calling MSMQApplication.RegisterCertificate.

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Sending a message with an internal certificate attached	C/C++ Code Example: Requesting Authentication Using an Internal Certificate
Sending a message with an external certificate attached	C/C++ Code Example: Requesting Authentication Using an External Certificate
Reading messages to see if authentication was requested by the sending application	C/C++ Code Example: Validating Authentication

Requirements

Windows NT/2000/XP: Included in Windows 2000 and later.

Windows 95/98/Me: Unsupported.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.