DsMakeSpnA function (dsparse.h)

Article
02/09/2023

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.

Syntax

DSPARSE DWORD DsMakeSpnA(
  [in]           LPCSTR ServiceClass,
  [in]           LPCSTR ServiceName,
  [in, optional] LPCSTR InstanceName,
  [in]           USHORT InstancePort,
  [in, optional] LPCSTR Referrer,
  [in, out]      DWORD  *pcSpnLength,
  [out]          LPSTR  pszSpn
);

Parameters

[in] ServiceClass

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.

[in] ServiceName

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.

[in, optional] InstanceName

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.

[in] InstancePort

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.

[in, optional] Referrer

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.

[in, out] pcSpnLength

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.

[out] pszSpn

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 value

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.

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.

Note This format is used by host-based services.

To produce an SPN with the "<ServiceClass>/<host>" format

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 nonzero, the SPN has the following format:
```
<service class>/<host>:<instance port>/<referrer>
```

Note This format is used by replicable services.

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

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 nonzero, the SPN has the following format:
```
<service class>/<host>:<instance port>/<service name>
```

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:

<service class>/<host>:<instance port>/<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.

Note

The dsparse.h header defines DsMakeSpn as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	dsparse.h (include Ntdsapi.h)
Library	Ntdsapi.lib
DLL	Ntdsapi.dll