MSMQApplication.RegisterCertificate

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

(Introduced in MSMQ 2.0.) The RegisterCertificate method of the MSMQApplication object 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.

Sub RegisterCertificate( _  
  [ ByRef Flags], _  
  [ ByRef ExternalCertificate] _  
)

Parameters

Flags

[in, optional] One of the following constants that specify when the certificate is registered (in C++, a reference to a VARIANT that specifies the constant):

MQCERT_REGISTER_ALWAYS

The default. Registers an internal or external certificate each time RegisterCertificate is called.

For internal certificates, a new certificate is created and registered, deleting any existing certificate.

For external certificates (see varExternalCertificate), 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_EXITS information code is returned.

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

ExternalCertificate

[in, optional] Specifies the contents of the external certificate to be registered. This argument is a Byte array that contains a binary representation of the external certificate (in C++, a reference to a VARIANT containing a byte array that specifies the contents of the external certificate).

If this argument is not used, an internal certificate is registered.

Return Values

This method has no return values.

Error Codes

The following error codes can be returned by this method.

MQ_OK (0L)

Indicates success.

MQ_ERROR_CANNOT_CREATE_CERT_STORE (0xC00E006FL)

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 (0xC00E0070L)

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 (0xC00E0011L)

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 (0xC00E002EL)

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

MQ_INFORMATION_INTERNAL_USER_CERT_EXIST (0x400E00AL)

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

For information on return codes, see Message Queuing Error and Information Codes.

Remarks

Message Queuing can register only 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. When you use Microsoft Internet Explorer to obtain the certificate, the certificate is automatically placed in the Microsoft Internet Explorer personal certificate store.

RegisterCertificate cannot be used when operating in workgroup mode.

When you call RegisterCertificate, you do not have to reference the MSMQApplication object explicitly because this object is defined as the application object, whose methods and properties are globally available. This method can only be called for the local computer. If MSMQApplication.Machine is set to another computer, an error is returned.

In C++ COM applications, you must use a smart pointer to the IMSMQApplication2 or IMSMQApplication3 interface to expose the RegisterCertificate method.

Equivalent API Function

When using API functions, call MQRegisterCertificate to register the certificate.

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

Requirements

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

Windows 95/98/Me: Unsupported.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.