DsMakeSpnA, fonction (dsparse.h)

Article
08/23/2023

La fonction DsMakeSpn construit un nom de principal de service (SPN) qui identifie un service instance.

Une application cliente utilise cette fonction pour composer un SPN, qu’elle utilise pour authentifier le service instance. Par exemple, le client peut passer un SPN dans le paramètre pszTargetName de la fonction InitializeSecurityContext .

Syntaxe

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

Paramètres

[in] ServiceClass

Pointeur vers une chaîne constante terminée par null qui spécifie la classe du service. Ce paramètre peut être n’importe quelle chaîne propre à ce service ; le nom du protocole, par exemple ldap, ou la forme de chaîne d’un GUID sont acceptables.

[in] ServiceName

Pointeur vers une chaîne constante terminée par un caractère Null qui spécifie le nom DNS, le nom NetBIOS ou le nom unique (DN). Ce paramètre doit être non NULL.

Pour plus d’informations sur la façon dont les paramètres ServiceName, InstanceName et InstancePort sont utilisés pour composer un SPN, consultez la section Remarques suivante.

[in, optional] InstanceName

Pointeur vers une chaîne constante terminée par un caractère Null qui spécifie le nom DNS ou l’adresse IP de l’hôte pour une instance du service.

Si ServiceName spécifie le nom DNS ou NetBIOS de l’ordinateur hôte du service, le paramètre InstanceName doit être NULL.

Si ServiceName spécifie un nom de domaine DNS, le nom d’un enregistrement SRV DNS ou un nom unique, tel que le DN d’un point de connexion de service, le paramètre InstanceName doit spécifier le nom DNS ou NetBIOS de l’ordinateur hôte du service.

[in] InstancePort

Numéro de port d’une instance du service. Utilisez 0 pour le port par défaut. Si ce paramètre est égal à zéro, le SPN n’inclut pas de numéro de port.

[in, optional] Referrer

Pointeur vers une chaîne constante terminée par un caractère Null qui spécifie le nom DNS de l’hôte qui a donné une référence d’adresse IP. Ce paramètre est ignoré, sauf si le paramètre ServiceName spécifie une adresse IP.

[in, out] pcSpnLength

Pointeur vers une variable qui contient la longueur, en caractères, de la mémoire tampon qui recevra le nouveau SPN construit. Cette valeur peut être 0 pour demander la taille finale de la mémoire tampon à l’avance.

Le paramètre pcSpnLength reçoit également la longueur réelle du SPN créé, y compris le caractère null de fin.

[out] pszSpn

Pointeur vers une chaîne terminée par null qui reçoit le SPN construit. Cette mémoire tampon doit être la longueur spécifiée par pcSpnLength. Le paramètre pszSpn peut être NULL pour demander la taille finale de la mémoire tampon à l’avance.

Valeur retournée

Si la fonction retourne un SPN, la valeur de retour est ERROR_SUCCESS. Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants.

Remarques

Le format du SPN produit par la fonction DsMakeSpn dépend des paramètres d’entrée. Il existe deux formats de base. Les deux formats commencent par la chaîne ServiceClass suivie d’un nom d’ordinateur hôte et d’un composant InstancePort facultatif.

Note Ce format est utilisé par les services basés sur l’hôte.

Pour produire un SPN au format «< ServiceClass>/<host> »

Définissez le paramètre ServiceName sur le nom DNS de l’ordinateur hôte pour le service instance. Il s’agit du composant hôte du SPN.
Définissez les paramètres InstanceName et Referrer sur NULL.
Définissez le paramètre InstancePort sur zéro. Si InstancePort est différent de zéro, le SPN a le format suivant :
```
<service class>/<host>:<instance port>/<referrer>
```

Note Ce format est utilisé par les services réplicables.

Pour produire un SPN au format «< ServiceClass>/<host> :<InstancePort> »

Définissez le paramètre InstanceName sur le nom DNS de l’ordinateur hôte pour le service instance. Il s’agit du composant hôte.
Définissez le paramètre ServiceName sur une chaîne qui identifie un instance du service. Par exemple, il peut s’agir du nom unique du point de connexion de service pour ce service instance.
Définissez le paramètre Referrer sur NULL.
Définissez le paramètre InstancePort sur zéro. Si InstancePort est différent de zéro, le SPN a le format suivant :
```
<service class>/<host>:<instance port>/<service name>
```

Le paramètre Referrer est utilisé uniquement si le paramètre ServiceName spécifie l’adresse IP de l’ordinateur hôte du service. Dans ce cas, Referrer spécifie le nom DNS de l’ordinateur qui a donné l’adresse IP comme référence. Le SPN a le format suivant :

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

où le composant hôte est la chaîne InstanceName ou la chaîne ServiceName si InstanceName a la valeur NULL et que le composant InstancePort est facultatif.

Les paramètres de chaîne ne peuvent pas inclure le caractère de barre oblique (/), car il est utilisé pour séparer les composants du SPN.

Notes

L’en-tête dsparse.h définit DsMakeSpn en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	dsparse.h (inclure Ntdsapi.h)
Bibliothèque	Ntdsapi.lib
DLL	Ntdsapi.dll

Voir aussi

Fonctions de gestion des contrôleurs de domaine et de la réplication

InitializeSecurityContext