DsMakeSpn

The DsMakeSpn function constructs a service principal name (SPN) that identifies an instance of a service.

A client program uses this function to compose an SPN, which it uses to authenticate the service instance. For example, the client could pass an SPN in the pszTargetName parameter of the InitializeSecurityContext function.

DWORD DsMakeSpn(
  LPCTSTR ServiceClass,
  LPCTSTR ServiceName,
  LPCTSTR InstanceName,
  USHORT InstancePort,
  LPCTSTR Referrer,
  DWORD *pcSpnLength,
  LPTSTR pszSpn
);

Parameters

ServiceClass

[in] Pointer to a constant null-terminated Unicode string specifying the class of the service. This parameter may be any string unique to that service; either the protocol name (for example, ldap) or the string form of a GUID will work.

ServiceName

[in] Pointer to a constant null-terminated string specifying the domain name service (DNS) name, NetBIOS name, or distinguished name (DN). This parameter must be non-NULL.

See the following Remarks section for information on how the ServiceName, InstanceName and InstancePort parameters are used to compose an SPN.

InstanceName

[in, optional] Pointer to a constant null-terminated Unicode string specifying the DNS name or IP address of the host for an instance of the service.

If ServiceName specifies the DNS or NetBIOS name of the service's host computer, the InstanceName parameter must be NULL.

If ServiceName specifies a DNS domain name, the name of a DNS SRV record, or a distinguished name, such as the DN of a service connection point, the InstanceName parameter must specify the DNS or NetBIOS name of the service's host computer.

InstancePort

[in] Port number for an instance of the service. Use 0 for the default port. If this parameter is zero, the SPN does not include a port number.

Referrer

[in, optional] Pointer to a constant null-terminated Unicode string specifying the DNS name of the host that gave an IP address referral. This parameter is ignored unless the ServiceName parameter specifies an IP address.

pcSpnLength

[in, out] Pointer to a variable containing the length in characters of the buffer that will receive the newly constructed SPN. This value may be 0 to request the final buffer size in advance.

The pcSpnLength parameter also receives the actual length of the SPN created, including the terminating null.

pszSpn

[out] Pointer to a null-terminated Unicode string that receives the constructed SPN. This buffer should be the length specified by pcSpnLength. The pszSpn parameter may be NULL to request the final buffer size in advance.

Return Values

If the function returns an SPN, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following error codes.

ERROR_BUFFER_OVERFLOW

The buffer in pszSpn is not large enough to hold the constructed SPN. The required length for the buffer is returned in pcSpnLength.

ERROR_INVALID_PARAMETER

A parameter is incorrect.

Remarks

The format of the SPN produced by the DsMakeSpn function depends on the input parameters. There are two basic formats. Both formats begin with the ServiceClass string followed by a host computer name and an optional InstancePort component.

To produce an SPN with the following format: (used by host-based services)

ServiceClass/ host

• Set the ServiceName parameter to the DNS name of the host computer for the service instance. This is the host component of the SPN.
• Set the InstanceName and Referrer parameters to NULL.
• Set the InstancePort parameter to zero. If InstancePort is non-zero, the SPN will have the following format:

  ServiceClass/ host: InstancePort/ Referrer

To produce an SPN with the following format: (used by replicable services)

ServiceClass/ host: InstancePort

• Set the InstanceName parameter to the DNS name of the host computer for the service instance. This is the host component.
• Set the ServiceName parameter to a string that identifies an instance of the service. For example, it could be the distinguished name of the service connection point for this service instance.
• Set the Referrer parameter to NULL.
• Set the InstancePort parameter to zero. If InstancePort is non-zero, the SPN will have the following format:

  ServiceClass/host: InstancePort/ ServiceName

The Referrer parameter is used only if the ServiceName parameter specifies the IP address of the service's host computer. In this case, Referrer specifies the DNS name of the computer that gave the IP address as a referral. The SPN has the following format:

ServiceClass/ host: InstancePort/ Referrer

where the host component is the InstanceName string or the ServiceName string if InstanceName is NULL, and the InstancePort component is optional.

String parameters cannot include the forward slash ('/') character, as it is used to separate the components of the SPN.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsapi.h.
  Library: Included as a resource in Ntdsapi.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

DC and Replication Management Functions, InitializeSecurityContext