DsMakeSpnA-Funktion (dsparse.h)

Artikel
11/20/2024

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

Eine Clientanwendung verwendet diese Funktion zum Verfassen eines SPN, das zum Authentifizieren der Dienstinstanz verwendet wird. Beispielsweise kann der Client einen SPN im pszTargetName Parameter 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

Zeigen Sie auf eine konstante null-beendete 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 zulässig.

[in] ServiceName

Zeigen Sie auf eine konstante null-beendete Zeichenfolge, die den DNS-Namen, den NetBIOS-Namen oder den Distinguished Name (DN) angibt. Dieser Parameter muss nichtNULL-sein.

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

[in, optional] InstanceName

Zeigen Sie auf eine konstante null-beendete Zeichenfolge, die den DNS-Namen oder die IP-Adresse des Hosts für eine Instanz des Diensts angibt.

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

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

[in] InstancePort

Portnummer für eine Instanz 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-beendete Zeichenfolge, die den DNS-Namen des Hosts angibt, der eine IP-Adressverweisung gegeben hat. Dieser Parameter wird ignoriert, es sei denn, der parameter ServiceName gibt eine IP-Adresse an.

[in, out] pcSpnLength

Zeigen Sie auf eine Variable, die die Länge des Puffers in Zeichen enthält, die den neuen erstellten SPN erhalten. Dieser Wert kann 0 sein, um die endgültige Puffergröße im Voraus anzufordern.

Der pcSpnLength Parameter empfängt auch die tatsächliche Länge des erstellten SPN, einschließlich des endenden Nullzeichens.

[out] pszSpn

Zeigen Sie auf eine mit Null beendete Zeichenfolge, die den erstellten SPN empfängt. Dieser Puffer sollte die von pcSpnLengthangegebene Länge sein. 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.

Bemerkungen

Das Format des SPN, das von der DsMakeSpn Funktion erzeugt wird, hängt von den Eingabeparametern ab. Es gibt zwei grundlegende Formate. Beide Formate beginnen mit der ServiceClass- Zeichenfolge gefolgt von einem Hostnamennamen 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 die Dienstinstanz fest. Dies ist die Hostkomponente des SPN.
Legen Sie die Parameter InstanceName und Referrer auf NULL-fest.
Legen Sie den parameter InstancePort auf null fest. Wenn InstancePort- ungleich Null ist, weist der SPN das folgende Format auf:
```
<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 die Dienstinstanz fest. Dies ist die Hostkomponente.
Legen Sie den ServiceName Parameter auf eine Zeichenfolge fest, die eine Instanz des Diensts identifiziert. Beispielsweise könnte es sich um den distinguishierten Namen des Dienstverbindungspunkts für diese Dienstinstanz sein.
Legen Sie den parameter Referrer auf NULLfest.
Legen Sie den parameter InstancePort auf null fest. Wenn InstancePort- ungleich Null ist, weist der SPN das folgende Format auf:
```
<service class>/<host>:<instance port>/<service name>
```

Der parameter Referrer 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 weist das folgende Format auf:

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

dabei ist die Hostkomponente die InstanceName- Zeichenfolge oder die ServiceName- Zeichenfolge, wenn InstanceName- NULL-ist und die InstancePort Komponente optional ist.

Zeichenfolgenparameter können den Schrägstrich (/) nicht enthalten, da sie verwendet wird, um die Komponenten des SPN zu trennen.

Anmerkung

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
mindestens unterstützte Client-	Windows Vista
mindestens unterstützte Server-	Windows Server 2008
Zielplattform-	Fenster
Header-	dsparse.h (include Ntdsapi.h)
Library	Ntdsapi.lib
DLL-	Ntdsapi.dll

Siehe auch

Domänencontroller- und Replikationsverwaltungsfunktionen

InitializeSecurityContext-

Freigeben über