DsMakeSpnA-Funktion (dsparse.h)

Artikel
08/23/2023

Die DsMakeSpn-Funktion erstellt einen Dienstprinzipalnamen (Service Principal Name, SPN), der einen Dienst instance identifiziert.

Eine Clientanwendung verwendet diese Funktion, um einen SPN zu erstellen, den sie zum Authentifizieren des Diensts instance. Der Client kann beispielsweise einen SPN im parameter pszTargetName der InitializeSecurityContext-Funktion übergeben.

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
);

Parameter

[in] ServiceClass

Zeiger auf eine konstante NULL-endende Zeichenfolge, die die Klasse des Diensts angibt. Dieser Parameter kann eine beliebige Zeichenfolge sein, die für diesen Dienst eindeutig ist. entweder der Protokollname, z. B. ldap, oder die Zeichenfolgenform einer GUID sind akzeptabel.

[in] ServiceName

Zeiger auf eine konstante NULL-endende Zeichenfolge, die den DNS-Namen, NetBIOS-Namen oder Distinguished Name (DN) angibt. Dieser Parameter muss nicht NULL sein.

Weitere Informationen dazu, wie die Parameter ServiceName, InstanceName und InstancePort zum Erstellen eines SPN verwendet werden, finden Sie im folgenden Abschnitt Hinweise.

[in, optional] InstanceName

Zeiger auf eine konstante NULL-endende Zeichenfolge, die den DNS-Namen oder die IP-Adresse des Hosts für eine instance des Diensts angibt.

Wenn ServiceName den DNS- oder NetBIOS-Namen des Diensthostcomputers angibt, muss der InstanceName-ParameterNULL sein.

Wenn ServiceName einen DNS-Domänennamen, den Namen eines DNS-SRV-Eintrags oder einen distinguished Name angibt, z. B. den DN eines Dienstverbindungspunkts, muss der InstanceName-Parameter den DNS- oder NetBIOS-Namen des Diensthostcomputers angeben.

[in] InstancePort

Portnummer für eine instance des Diensts. Verwenden Sie 0 für den Standardport. Wenn dieser Parameter null ist, enthält der SPN keine Portnummer.

[in, optional] Referrer

Zeiger auf eine konstante NULL-endende Zeichenfolge, die den DNS-Namen des Hosts angibt, der eine IP-Adressreferenz erteilt hat. Dieser Parameter wird ignoriert, es sei denn, der Parameter ServiceName gibt eine IP-Adresse an.

[in, out] pcSpnLength

Zeiger auf eine Variable, die die Länge des Puffers in Zeichen enthält, der den neu erstellten SPN empfängt. Dieser Wert kann 0 sein, um die endgültige Puffergröße im Voraus anzufordern.

Der parameter pcSpnLength empfängt auch die tatsächliche Länge des erstellten SPN, einschließlich des abschließenden NULL-Zeichens.

[out] pszSpn

Zeiger auf eine NULL-endende Zeichenfolge, die den konstruierten SPN empfängt. Dieser Puffer sollte die von pcSpnLength angegebene Länge aufweisen. Der pszSpn-Parameter kann NULL sein, um die endgültige Puffergröße im Voraus anzufordern.

Rückgabewert

Wenn die Funktion einen SPN zurückgibt, wird der Rückgabewert ERROR_SUCCESS. Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.

Hinweise

Das Format des von der DsMakeSpn-Funktion erzeugten SPN hängt von den Eingabeparametern ab. Es gibt zwei grundlegende Formate. Beide Formate beginnen mit der ServiceClass-Zeichenfolge , gefolgt von einem Hostcomputernamen und einer optionalen InstancePort-Komponente .

Hinweis Dieses Format wird von hostbasierten Diensten verwendet.

So erstellen Sie einen SPN mit dem Format "<ServiceClass>/<host>"

Legen Sie den Parameter ServiceName auf den DNS-Namen des Hostcomputers für den Dienst instance fest. Dies ist die Hostkomponente des SPN.
Legen Sie die Parameter InstanceName und Referrer auf NULL fest.
Legen Sie den InstancePort-Parameter auf 0 (null) fest. Wenn InstancePort ungleich null ist, hat der SPN das folgende Format:
```
<service class>/<host>:<instance port>/<referrer>
```

Hinweis Dieses Format wird von replizierbaren Diensten verwendet.

So erstellen Sie einen SPN mit dem Format "<ServiceClass>/<host>:<InstancePort>"

Legen Sie den Parameter InstanceName auf den DNS-Namen des Hostcomputers für den Dienst instance fest. Dies ist die Hostkomponente.
Legen Sie den ServiceName-Parameter auf eine Zeichenfolge fest, die eine instance des Diensts identifiziert. Beispielsweise kann es sich um den distinguished Name des Dienstverbindungspunkts für diesen Dienst instance.
Legen Sie den Referrer-Parameter auf NULL fest.
Legen Sie den InstancePort-Parameter auf 0 (null) fest. Wenn InstancePort ungleich null ist, hat der SPN das folgende Format:
```
<service class>/<host>:<instance port>/<service name>
```

Der Referrer-Parameter wird nur verwendet, wenn der Parameter ServiceName die IP-Adresse des Hostcomputers des Diensts angibt. In diesem Fall gibt Referrer den DNS-Namen des Computers an, der die IP-Adresse als Empfehlung angegeben hat. Der SPN hat das folgende Format:

<service class>/<host>:<instance port>/<referrer>

Dabei ist die Hostkomponente die InstanceName-Zeichenfolge oder die ServiceName-Zeichenfolge , wenn InstanceNameNULL ist, und die InstancePort-Komponente optional ist.

Zeichenfolgenparameter können den Schrägstrich (/) nicht enthalten, da es zum Trennen der Komponenten des SPN verwendet wird.

Hinweis

Der dsparse.h-Header definiert DsMakeSpn als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	dsparse.h (ntdsapi.h einschließen)
Bibliothek	Ntdsapi.lib
DLL	Ntdsapi.dll

Weitere Informationen

Domänencontroller- und Replikationsverwaltungsfunktionen

InitializeSecurityContext