DsGetSpnA function (ntdsapi.h)
The DsGetSpn function constructs an array of one or more service principal names (SPNs). Each name in the array identifies an instance of a service. These SPNs may be registered with the directory service (DS) using the DsWriteAccountSpn function.
Syntax
NTDSAPI DWORD DsGetSpnA(
[in] DS_SPN_NAME_TYPE ServiceType,
[in] LPCSTR ServiceClass,
[in, optional] LPCSTR ServiceName,
[in] USHORT InstancePort,
[in] USHORT cInstanceNames,
[in, optional] LPCSTR *pInstanceNames,
[in, optional] const USHORT *pInstancePorts,
[out] DWORD *pcSpn,
[out] LPSTR **prpszSpn
);
Parameters
[in] ServiceType
Identifies the format of the SPNs to compose. The ServiceType parameter can have one of the following values.
DS_SPN_DNS_HOST, DS_SPN_DN_HOST, DS_SPN_NB_HOST
The SPNs have the following format.
ServiceClass/ InstanceName: InstancePort
The ServiceName parameter must be NULL. This is the SPN format for a host-based service, which provides services identified with its host computer. The InstancePort component is optional.
DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN
The SPNs have the following format.
ServiceClass/ InstanceName: InstancePort/ ServiceName
The ServiceName parameter must be the DNS name or DN of a domain. This format is used for a replicable service that provides services to the specified domain.
DS_SPN_SERVICE
The SPNs have the following format.
ServiceClass/ InstanceName: InstancePort/ ServiceName
The ServiceName parameter must be a canonical DN or DNS name that identifies an instance of the service. For example, it could be a DNS name of a SRV record, or the distinguished name of the service connection point for this service instance.
[in] ServiceClass
Pointer to a constant null-terminated string that specifies the class of the service; for example, http. Generally, this can be any string that is unique to the service.
[in, optional] ServiceName
Pointer to a constant null-terminated string that specifies the DNS name or distinguished name (DN) of the service. ServiceName is not required for a host-based service. For more information, see the description of the ServiceType parameter for the possible values of ServiceName.
[in] InstancePort
Specifies the port number of the service instance. If this value is zero, the SPN does not include a port number.
[in] cInstanceNames
Specifies the number of elements in the pInstanceNames and pInstancePorts arrays. If this value is not zero, pInstanceNames must point to an array of cInstanceNames strings, and pInstancePorts can be either NULL or a pointer to an array of cInstanceNames port numbers. If this value is zero, DsGetSpn returns only one SPN in the prpszSpn array and pInstanceNames and pInstancePorts are ignored.
[in, optional] pInstanceNames
Pointer to an array of null-terminated strings that specify extra instance names (not used for host names). This parameter is ignored if cInstanceNames is zero. In that case, the InstanceName component of the SPN defaults to the fully qualified DNS name of the local computer or the NetBIOS name if DS_SPN_NB_HOST or DS_SPN_NB_DOMAIN is specified.
[in, optional] pInstancePorts
Pointer to an array of extra instance ports. If this value is non-NULL, it must point to an array of cInstanceNames port numbers. If this value is NULL, the SPNs do not include a port number. This parameter is ignored if cInstanceNames is zero.
[out] pcSpn
Pointer to a variable that receives the number of SPNs contained in prpszSpn.
[out] prpszSpn
Pointer to a variable that receives a pointer to an array of SPNs. This array must be freed with DsFreeSpnArray.
Return value
If the function returns an array of SPNs, the return value is ERROR_SUCCESS.
If the function fails, the return value can be one of the following error codes.
Remarks
To create SPNs for multiple instances of a replicated service running on multiple host computers
- Set cInstanceNames to the number of instances.
- Specify the names of the host computers in the pInstanceNames array.
To create SPNs for multiple instances of a service running on the same host computer
- Set the cInstanceNames to the number of instances.
- Set each entry in the pInstanceNames array to the DNS name of the host computer.
- Use the pInstancePorts parameter to specify an array of unique port numbers for each instance to disambiguate the SPNs.
An application with the appropriate privileges, which are usually those of a domain administrator, can call the DsWriteAccountSpn function to register one or more SPNs on the user or computer account where the service is running. Clients can then use the SPNs to authenticate the service.
Note
The ntdsapi.h header defines DsGetSpn 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 | ntdsapi.h |
Library | Ntdsapi.lib |
DLL | Ntdsapi.dll |