Directory Services

DsMakeSpn

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

A client application uses this function to compose an SPN, which it uses to authenticate the service instance. For example, the client can 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 string that specifies the class of the service. This parameter can be any string unique to that service; either the protocol name, for example, ldap, or the string form of a GUID are acceptable.
ServiceName
[in] Pointer to a constant null-terminated string that specifies the DNS name, NetBIOS name, or distinguished name (DN). This parameter must be non-NULL.

For more information about how the ServiceName, InstanceName and InstancePort parameters are used to compose an SPN, see the following Remarks section.

InstanceName
[in, optional] Pointer to a constant null-terminated string that specifies 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 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 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 string that specifies 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 that contains the length, in characters, of the buffer that will receive the new 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 character.

pszSpn
[out] Pointer to a null-terminated 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.
Return Code Description
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 ServiceClass/host format

Note  This format is used by host-based services.

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

    ServiceClass/host: InstancePort/Referrer

To produce an SPN with the ServiceClass/host: InstancePort format

Note  This format is used by replicable services.

  1. Set the InstanceName parameter to the DNS name of the host computer for the service instance. This is the host component.
  2. 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.
  3. Set the Referrer parameter to NULL.
  4. Set the InstancePort parameter to zero. If InstancePort is non-zero, the SPN has 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

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

InitializeSecurityContext, Domain Controller and Replication Management Functions