Función CreateProcessWithTokenW (winbase.h)
Crea un nuevo proceso y su subproceso principal. El nuevo proceso se ejecuta en el contexto de seguridad del token especificado. Opcionalmente, puede cargar el perfil de usuario para el usuario especificado.
El proceso que llama a CreateProcessWithTokenW debe tener el privilegio SE_IMPERSONATE_NAME. Si se produce un error en esta función con ERROR_PRIVILEGE_NOT_HELD (1314), use la función CreateProcessAsUser o CreateProcessWithLogonW en su lugar. Normalmente, el proceso que llama a
CreateProcessAsUser debe tener el privilegio SE_INCREASE_QUOTA_NAME y puede requerir el privilegio SE_ASSIGNPRIMARYTOKEN_NAME si el token no se puede asignar. CreateProcessWithLogonW no requiere privilegios especiales, pero se debe permitir que la cuenta de usuario especificada inicie sesión de forma interactiva. Por lo general, es mejor usar CreateProcessWithLogonW para crear un proceso con credenciales alternativas.
Sintaxis
BOOL CreateProcessWithTokenW(
[in] HANDLE hToken,
[in] DWORD dwLogonFlags,
[in, optional] LPCWSTR lpApplicationName,
[in, out, optional] LPWSTR lpCommandLine,
[in] DWORD dwCreationFlags,
[in, optional] LPVOID lpEnvironment,
[in, optional] LPCWSTR lpCurrentDirectory,
[in] LPSTARTUPINFOW lpStartupInfo,
[out] LPPROCESS_INFORMATION lpProcessInformation
);
Parámetros
[in] hToken
Identificador del token principal que representa a un usuario. El identificador debe tener los derechos de acceso TOKEN_QUERY, TOKEN_DUPLICATE y TOKEN_ASSIGN_PRIMARY. Para obtener más información, vea Derechos de acceso para objetos Access-Token. El usuario representado por el token debe tener acceso de lectura y ejecución a la aplicación especificada por lpApplicationName o el parámetro lpCommandLine .
Para obtener un token principal que representa al usuario especificado, llame a la función LogonUser . Como alternativa, puede llamar a la función DuplicateTokenEx para convertir un token de suplantación en un token principal. Esto permite que una aplicación de servidor que suplanta a un cliente cree un proceso que tenga el contexto de seguridad del cliente.
Terminal Services: El proceso del autor de la llamada siempre se ejecuta en la sesión del autor de la llamada, no en la sesión especificada en el token. Para ejecutar un proceso en la sesión especificada en el token, use la función CreateProcessAsUser.
[in] dwLogonFlags
La opción de inicio de sesión. Este parámetro puede ser cero o uno de los valores siguientes.
[in, optional] lpApplicationName
Nombre del módulo que se va a ejecutar. Este módulo puede ser una aplicación basada en Windows. Puede ser algún otro tipo de módulo (por ejemplo, MS-DOS o OS/2) si el subsistema adecuado está disponible en el equipo local.
La cadena puede especificar la ruta de acceso completa y el nombre de archivo del módulo que se va a ejecutar o puede especificar un nombre parcial. En el caso de un nombre parcial, la función usa la unidad actual y el directorio actual para completar la especificación. La función no usará la ruta de acceso de búsqueda. Este parámetro debe incluir la extensión de nombre de archivo; no se supone ninguna extensión predeterminada.
El parámetro lpApplicationName puede ser NULL. En ese caso, el nombre del módulo debe ser el primer token delimitado por espacios en blanco en la cadena lpCommandLine . Si usa un nombre de archivo largo que contiene un espacio, use cadenas entre comillas para indicar dónde finaliza el nombre de archivo y comienzan los argumentos; de lo contrario, el nombre de archivo es ambiguo. Por ejemplo, considere la cadena "c:\program files\sub dir\program name". Esta cadena se puede interpretar de varias maneras. El sistema intenta interpretar las posibilidades en el orden siguiente:
c:\program.exec:\program files\sub.exec:\program files\sub dir\program.exec:\program files\sub dir\program name.exe Si el módulo ejecutable es una aplicación de 16 bits, lpApplicationName debe ser NULL y la cadena a la que apunta lpCommandLine debe especificar el módulo ejecutable, así como sus argumentos.
[in, out, optional] lpCommandLine
Línea de comandos que se va a ejecutar.
La longitud máxima de esta cadena es de 1024 caracteres. Si lpApplicationName es NULL, la parte del nombre del módulo de lpCommandLine se limita a MAX_PATH caracteres.
La función puede modificar el contenido de esta cadena. Por lo tanto, este parámetro no puede ser un puntero a la memoria de solo lectura (como una variable const o una cadena literal). Si este parámetro es una cadena constante, la función puede provocar una infracción de acceso.
El parámetro lpCommandLine puede ser NULL. En ese caso, la función usa la cadena a la que apunta lpApplicationName como línea de comandos.
Si lpApplicationName y lpCommandLine no son NULL, *lpApplicationName especifica el módulo que se va a ejecutar y *lpCommandLine especifica la línea de comandos. El nuevo proceso puede usar GetCommandLine para recuperar toda la línea de comandos. Los procesos de consola escritos en C pueden usar los argumentos argc y argv para analizar la línea de comandos. Dado que argv[0] es el nombre del módulo, los programadores de C suelen repetir el nombre del módulo como primer token de la línea de comandos.
Si lpApplicationName es NULL, el primer token delimitado por espacios en blanco de la línea de comandos especifica el nombre del módulo. Si usa un nombre de archivo largo que contiene un espacio, use cadenas entre comillas para indicar dónde finaliza el nombre de archivo y los argumentos comienzan (vea la explicación del parámetro lpApplicationName ). Si el nombre de archivo no contiene una extensión, se anexa .exe. Por lo tanto, si la extensión de nombre de archivo es .com, este parámetro debe incluir la extensión .com. Si el nombre de archivo finaliza en un punto (.) sin extensión, o si el nombre de archivo contiene una ruta de acceso, .exe no se anexa. Si el nombre de archivo no contiene una ruta de acceso de directorio, el sistema busca el archivo ejecutable en la secuencia siguiente:
- Directorio desde el que se cargó la aplicación.
- Directorio actual del proceso primario.
- Directorio del sistema de Windows de 32 bits. Use la función GetSystemDirectory para obtener la ruta de acceso de este directorio.
- Directorio del sistema de Windows de 16 bits. No hay ninguna función que obtenga la ruta de acceso de este directorio, pero se busca.
- El directorio de Windows. Use la función GetWindowsDirectory para obtener la ruta de acceso de este directorio.
- Los directorios que aparecen en la variable de entorno PATH. Tenga en cuenta que esta función no busca la ruta de acceso por aplicación especificada por la clave del Registro rutas de acceso de aplicación. Para incluir esta ruta de acceso por aplicación en la secuencia de búsqueda, use la función ShellExecute .
[in] dwCreationFlags
Marcas que controlan cómo se crea el proceso. Las marcas CREATE_DEFAULT_ERROR_MODE, CREATE_NEW_CONSOLE y CREATE_NEW_PROCESS_GROUP están habilitadas de forma predeterminada. Para obtener una lista de valores, vea Marcas de creación de procesos.
Este parámetro también controla la clase de prioridad del nuevo proceso, que se usa para determinar las prioridades de programación de los subprocesos del proceso. Para obtener una lista de valores, consulte GetPriorityClass. Si no se especifica ninguna de las marcas de clase de prioridad, la clase de prioridad tiene como valor predeterminado NORMAL_PRIORITY_CLASS a menos que la clase de prioridad del proceso de creación se IDLE_PRIORITY_CLASS o BELOW_NORMAL_PRIORITY_CLASS. En este caso, el proceso secundario recibe la clase de prioridad predeterminada del proceso de llamada.
Si el parámetro dwCreationFlags tiene un valor de 0:
- El proceso obtiene el modo de error predeterminado, crea una nueva consola y crea un nuevo grupo de procesos.
- Se supone que el bloque de entorno del nuevo proceso contiene caracteres ANSI (consulte el parámetro lpEnvironment para obtener información adicional).
- Una aplicación basada en Windows de 16 bits se ejecuta en una máquina VIRTUAL DOS compartida (VDM).
[in, optional] lpEnvironment
Puntero a un bloque de entorno para el nuevo proceso. Si este parámetro es NULL, el nuevo proceso usa un entorno creado a partir del perfil del usuario especificado por lpUsername.
Un bloque de entorno consta de un bloque terminado en null de cadenas terminadas en NULL. Cada cadena tiene el siguiente formato:
Nombre=Valor
Dado que el signo igual (=) se usa como separador, no debe usarse en el nombre de una variable de entorno.
Un bloque de entorno puede contener caracteres Unicode o ANSI. Si el bloque de entorno al que apunta lpEnvironment contiene caracteres Unicode, asegúrese de que dwCreationFlags incluye CREATE_UNICODE_ENVIRONMENT.
Un bloque de entorno ANSI finaliza en dos bytes cero: uno para la última cadena, uno más para finalizar el bloque. Un bloque de entorno Unicode finaliza en cuatro bytes cero: dos para la última cadena y dos más para finalizar el bloque.
Para recuperar una copia del bloque de entorno para un usuario específico, use la función CreateEnvironmentBlock .
[in, optional] lpCurrentDirectory
Ruta de acceso completa al directorio actual del proceso. La cadena también puede especificar una ruta de acceso UNC.
Si este parámetro es NULL, el nuevo proceso tendrá la misma unidad y directorio actuales que el proceso de llamada. (Esta característica se proporciona principalmente para los shells que necesitan iniciar una aplicación y especificar su unidad inicial y directorio de trabajo).
[in] lpStartupInfo
Puntero a una estructura STARTUPINFO o STARTUPINFOEX .
Si el miembro lpDesktop es NULL o una cadena vacía, el nuevo proceso hereda la estación de escritorio y ventana de su proceso primario. La función agrega permiso para la cuenta de usuario especificada a la estación de ventana heredada y al escritorio. De lo contrario, si este miembro especifica un escritorio, es responsabilidad de la aplicación agregar permiso para la cuenta de usuario especificada a la estación de ventana y el escritorio especificados, incluso para WinSta0\Default.
Los identificadores de STARTUPINFO o STARTUPINFOEX deben cerrarse con CloseHandle cuando ya no sean necesarios.
[out] lpProcessInformation
Puntero a una estructura de PROCESS_INFORMATION que recibe información de identificación para el nuevo proceso, incluido un identificador para el proceso.
Los identificadores de PROCESS_INFORMATION deben cerrarse con la función CloseHandle cuando ya no son necesarios.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es distinto de cero.
Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
Tenga en cuenta que la función devuelve antes de que el proceso haya terminado de inicializarse. Si no se puede encontrar un archivo DLL necesario o no se puede inicializar, se finaliza el proceso. Para obtener el estado de finalización de un proceso, llame a GetExitCodeProcess.
Comentarios
De forma predeterminada, CreateProcessWithTokenW no carga el perfil del usuario especificado en la clave del Registro HKEY_USERS . Esto significa que el acceso a la información de la clave del Registro de HKEY_CURRENT_USER puede no producir resultados coherentes con un inicio de sesión interactivo normal. Es responsabilidad suya cargar el subárbol del registro del usuario en HKEY_USERS mediante LOGON_WITH_PROFILE, o llamando a la función LoadUserProfile antes de llamar a esta función.
Si el parámetro lpEnvironment es NULL, el nuevo proceso usa un bloque de entorno creado a partir del perfil del usuario especificado por lpUserName. Si no se establecen las variables HOMEDRIVE y HOMEPATH, CreateProcessWithTokenW modifica el bloque de entorno para usar la unidad y la ruta de acceso del directorio de trabajo del usuario.
Cuando se crea, el nuevo proceso y el subproceso reciben derechos de acceso completos (PROCESS_ALL_ACCESS y THREAD_ALL_ACCESS). Para cualquiera de los identificadores, si no se proporciona un descriptor de seguridad, el identificador se puede usar en cualquier función que requiera un identificador de objeto de ese tipo. Cuando se proporciona un descriptor de seguridad, se realiza una comprobación de acceso en todos los usos posteriores del identificador antes de que se conceda acceso. Si se deniega el acceso, el proceso de solicitud no puede usar el identificador para obtener acceso al proceso o al subproceso.
Para recuperar un token de seguridad, pase el identificador de proceso en la estructura PROCESS_INFORMATION a la función OpenProcessToken .
Al proceso se le asigna un identificador de proceso. El identificador es válido hasta que finaliza el proceso. Se puede usar para identificar el proceso o especificarse en la función OpenProcess para abrir un identificador para el proceso. Al subproceso inicial del proceso también se le asigna un identificador de subproceso. Se puede especificar en la función OpenThread para abrir un identificador al subproceso. El identificador es válido hasta que finaliza el subproceso y se puede usar para identificar de forma única el subproceso dentro del sistema. Estos identificadores se devuelven en PROCESS_INFORMATION.
El subproceso de llamada puede usar la función WaitForInputIdle para esperar hasta que el nuevo proceso haya terminado su inicialización y esté esperando la entrada del usuario sin entrada pendiente. Esto puede ser útil para la sincronización entre los procesos primarios y secundarios, ya que CreateProcessWithTokenW devuelve sin esperar a que el nuevo proceso finalice su inicialización. Por ejemplo, el proceso de creación usaría WaitForInputIdle antes de intentar buscar una ventana asociada al nuevo proceso.
La manera preferida de apagar un proceso es mediante el uso de la función ExitProcess , ya que esta función envía una notificación de terminación cercana a todos los archivos DLL adjuntos al proceso. Otros medios para apagar un proceso no notifican a los archivos DLL adjuntos. Tenga en cuenta que cuando un subproceso llama a ExitProcess, otros subprocesos del proceso se terminan sin la oportunidad de ejecutar ningún código adicional (incluido el código de terminación del subproceso de archivos DLL adjuntos). Para obtener más información, consulte Terminación de un proceso.
Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0500 o posterior. Para obtener más información, vea Uso de los encabezados de Windows.
Comentarios de seguridad
El parámetro lpApplicationName puede ser NULL, en cuyo caso el nombre ejecutable debe ser la primera cadena delimitada por espacios en blanco en lpCommandLine. Si el nombre del archivo ejecutable o la ruta de acceso tiene un espacio en él, existe el riesgo de que se pueda ejecutar un archivo ejecutable diferente debido a la forma en que la función analiza los espacios. El ejemplo siguiente es peligroso porque la función intentará ejecutar "Program.exe", si existe, en lugar de "MyApp.exe". LPTSTR szCmdline = L"C:\\Program Files\\MyApp";
CreateProcessWithTokenW(/*...*/, szCmdline, /*...*/);
Si un usuario malintencionado creara una aplicación denominada "Program.exe" en un sistema, cualquier programa que llame incorrectamente a CreateProcessWithTokenW mediante el directorio Archivos de programa ejecutará esta aplicación en lugar de la aplicación deseada.
Para evitar este problema, no pase NULL para lpApplicationName. Si pasa NULL para lpApplicationName, use comillas alrededor de la ruta de acceso ejecutable en lpCommandLine, como se muestra en el ejemplo siguiente.
LPTSTR szCmdline = L"\"C:\\Program Files\\MyApp\"";
CreateProcessWithTokenW(/*...*/, szCmdline, /*...*/);
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winbase.h (incluya Windows.h) |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |