DsCrackSpn

The DsCrackSpn function parses a service principal name (SPN) into its component strings.

DWORD DsCrackSpn(
  LPCTSTR pszSPN,
  DWORD *pcServiceClass,
  LPTSTR ServiceClass,
  DWORD *pcServiceName,
  LPTSTR ServiceName,
  DWORD *pcInstanceName,
  LPTSTR InstanceName,
  USHORT *pInstancePort
);

Parameters

pszSPN

[in] Pointer to a constant null-terminated string specifying the SPN to parse. The SPN has the following format, in which the ServiceClass and host components must be present and the InstancePort and InstanceName components are optional.

ServiceClass/ Host: Port/ ServiceName

pcServiceClass

[in, out, optional] Pointer to a variable containing the length in characters of the ServiceClass buffer. On output, pcServiceClass returns the actual length of the string returned in ServiceClass, including the terminating null character.

If pcServiceClass is NULL or the input length is zero, the function does not return the ServiceClass string, nor does it return the required buffer size.

ServiceClass

[out, optional] Pointer to a buffer that receives a null-terminated string containing the ServiceClass component of the SPN. This buffer should be the length specified by pcServiceClass. Set the ServiceClass parameter to NULL if you have no use for this component of the SPN.

pcServiceName

[in, out, optional] Pointer to a variable containing the length in characters of the ServiceName buffer. On output, pcServiceName returns the actual length of the string returned in ServiceName, including the terminating null character.

If the pcServiceName parameter is NULL or the input length is zero, the function does not return the ServiceName string, nor does it return the required buffer size.

ServiceName

[out, optional] Pointer to a buffer that receives a null-terminated string containing the ServiceName component of the SPN. This buffer should be the length specified by pcServiceName. Set the ServiceName parameter to NULL if you have no use for this component of the SPN.

If the ServiceName component is not present in the SPN, both ServiceName and InstanceName parameters will return the Host computer.

pcInstanceName

[in, out, optional] Pointer to a variable containing the length in characters of the InstanceName buffer. On output, pcInstanceName returns the actual length of the string returned in InstanceName, including the terminating null character.

If the pcInstanceName parameter is NULL or the input length is zero, the function does not return the InstanceName string, nor does it return the required buffer size.

InstanceName

[out, optional] Pointer to a buffer that receives a null-terminated string containing the Host component of the SPN. The pcInstanceName parameter specifies the length of this buffer. Set the InstanceName parameter to NULL if you have no use for this component of the SPN.

pInstancePort

[out, optional] Pointer to a variable that receives the integer value of the Port component of the SPN. If the SPN does not have a Port component, the value returned is zero. Set this parameter to NULL if you have no use for this component of the SPN.

Return Values

If the function parses the SPN, the return value is ERROR_SUCCESS.

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

ERROR_INVALID_PARAMETER

A parameter is incorrect.

ERROR_NOT_ENOUGH_MEMORY

There is insufficient memory available.

ERROR_BUFFER_OVERFLOW

If any of the buffers is too small, the function fails with this error and returns the required buffer size in the corresponding buffer-length parameter. To determine which buffer was too small, compare required sizes to the input sizes. Also, the function ignores buffers that are NULL or have a zero size on input. So, it does not return an error or required buffer size in these cases.

Remarks

The InstancePort parameter is zero if not present.

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