Tcl Windows API extension

The Security Support Provider Interface (SSPI) is a standard interface to various security protocols that provide for security functions such as authentication, encryption and integrity. The SSPI interface allows establishment of a security context that can be used for signing and encrypting data passed between a client and a server.

SSPI security context establishment

On the client side, the application program starts off by retrieving the credentials to be used to authenticate itself to the server by calling sspi_new_credentials with the -outbound option. It then creates a new client security context by calling sspi_client_new_context specifying appropriate desired security characteristics. The application then exchanges messages with the server to complete the authentication.

Depending on the security protocol in use, the authentication between the client and the server may require multiple message exchanges between the client and the server. Once it obtains its security context, the client calls sspi_security_context_next passing it the security context. This command returns an indication of whether the authentication is complete, or more exchanges with the server are required. In the latter case, data returned by the command is sent to the server and the server response is passed back to the command. This sequence is repeated until the command indicates the authentication is complete or generates a Tcl exception indicating authentication failure. The security context generated in this manner can then be used to sign and encrypt messages between the client and the server.

On the server side, the application program starts off by retrieving its own credentials by calling sspi_new_credentials with the -inbound. It then creates a new server security context by calling sspi_server_new_context passing it the authentication data sent by the client. The server then enters the authentication loop described below. From this point on, the server follows the authentication loop calling sspi_security_context_next in the same manner as described above for the client.

Once a security context is established, either on the client or the server, its characteristics, including the negotiated parameters, security principal name etc. can be retrieved through commands sspi_get_security_context_flags, sspi_get_security_context_username and sspi_get_security_context_sizes.

When no longer required, both the server and client ends should free resources associated with their credentials by calling sspi_free_credentials. Similarly, the security context should be released when no longer needed by calling sspi_close_security_context.

SSPI message signing and encryption

Once a security context has been completely created as above, it can then be used to generate and verify messages signatures using sspi_generate_signature and sspi_verify_signature respectively.

Similarly, the security context can be used to encrypt and decrypt messages using sspi_encrypt and sspi_decrypt.

Commands

sspi_client_new_context CREDENTIALS ?options?

Initiates the building of a new client-side, security context from based on the specified credentials. CREDENTIALS is a handle to credentials returned by sspi_new_credentials. The returned value, which is a handle to a security context, should be treated as opaque by the caller and used as described in SSPI security context establishment.

The options below specify the requirements for the context. Note that not all security providers support all options or combinations of options. Refer to the Windows SDK for more information about these options.

-confidentiality BOOL	If specified as true, messages are to be encrypted.
-connection BOOL	If specified as true, the security context will not handle formatting of messages.
-datarep DATAREP	Specifies the data representation on the target. DATAREP must be either network (default) or native.
-delegate BOOL	If specified as true, the server can use the context to other servers as the client. Requires -mutualauth to also be specified as true.
-extendederror BOOL	When true, the remote end is notified of errors.
-integrity BOOL	If specified as true, messages are to be signed.
-mutualauth BOOL	If specified as true, both the client and server are to be authenticated.
-replaydetect BOOL	If specified as true, detection of replayed messages is desired.
-sequencedetect BOOL	If specified as true, detection of out-of-sequence messages is desired.
-stream BOOL	If specified as true, indicates a stream oriented connection.
-target TARGET	Specifies the target of the security context. The format depends on the security service provider.
-usesessionkey BOOL	If specified as true, a new session key must be negotiated.

When a security context is no longer required, it should be released by calling sspi_close_security_context.

sspi_close_security_context CONTEXT

Closes a security context constructed through sspi_client_new_context or sspi_server_new_context or and frees any associated resources.

sspi_decrypt CONTEXT ENCRYPTTOKEN ENCRYPTEDDATA PADDING ?options?

Returns the decrypted data.

sspi_encrypt CONTEXT PLAINTEXT ?options?

Encrypts PLAINTEXT based on the specified security context. Returns a list of three elements - the encryption token, the encrypted data and padding. These must be passed to #sspi_decrypt for decryption to be successful.

sspi_enumerate_packages

Returns a list of the names of the security provider packages available on the system.

sspi_generate_signature CONTEXT DATA ?options?

Generates a signature for DATA based on the supplied security context. Returns a list containing the generated signature and DATA.

sspi_get_security_context_features CONTEXT

After a security context is established, this command may be used to retrieve information about what security features were negotiated. The command returns a keyed list with boolean values for the following fields.

-confidentiality	If true, encryption is supported.
-connection	If true, the security context will not handle formatting of messages.
-delegate	If true, the server can use the context to other servers as the client.
-extendederror	If true, the remote end is notified of errors.
-integrity	If true, messages signing is supported.
-mutualauth	If true, both the client and server are authenticated.
-replaydetect	If true, detection of replayed messages is enabled.
-sequencedetect	If true, detection of out-of-sequence messages is enabled.
-stream	If true, indicates a stream oriented connection.

sspi_get_security_context_sizes CONTEXT

Returns a keyed list with the following fields:

-maxtoken	Maximum size of token used in the authentication exchange.
-maxsig	Maximum size of signature.
-blocksize	Messages should preferably be a multiple of this value.
-trailersize	Size of security trailer to be appended to messages.

sspi_get_security_context_username CONTEXT

TBD

sspi_free_credentials arg CREDENTIALS

Frees resources associated with credentials returned by sspi_new_credentials.

sspi_new_credentials ?options?

Returns credentials that can be used to negotiate and establish a security context. The command returns a handle to the credentials unless the -getexpiration option is specified in which case it returns a keyed list with two fields: -handle which is the handle to the credentials, and -expiration which returns the time (as number of 100ns intervals since January 1, 1601) at which the credentials expire.

The following options may be specified with the command:

-domain DOMAIN	Specifies the domain to which the user account belongs. Not all security providers support this. By default, the user account for the current process is used.
-getexpiration	If specified, the expiration time for the returned credentials is also returned. See description of command return value above.
-package SECURITYPACKAGE	Specifies the security package with which the credentials are to be used. By default, this is NTLM. The list of available security packages on a system can be obtained through sspi_enumerate_packages.
-password PASSWORD	Specifies the password for retrieving credentials to the user account specified by the -user option.
-principal.arg PRINCIPAL	Specifies the name of the principal whose credentials are to be referenced. By default, this is the user account under which the process is running.
-usage DIRECTION	Indicates how the credentials will be used, based on DIRECTION - inbound, outbound or both (default).
-user USERNAME	Specifies the name of the user account. Not all security providers support this. By default, the user account for the current process is used.

The returned credentials must be freed by calling sspi_free_credentials when no longer needed.

sspi_security_context_next CONTEXT ?RESPONSE?

Depending on the security provider in use, building a security context may require negotiation with multiple message exchanges between the client and server. This command indicates to the caller whether the negotiation is complete or additional exchange is required. See SSPI security context establishment for an overview of this process.

CONTEXT contains the security context being built. This is the return value from sspi_client_new_context, sspi_server_new_context or from a previous call to sspi_security_context_next.

The command returns a list containing three elements. The first element is either done, indicating that building of the security context was successfully completed, or continue, indicating that additional negotiation is required. In both cases, if the second element of the returned list is not an empty string, it contains data to be sent to the remote end to either complete or continue the negotiation. The application should keep calling sspi_security_context_next until it returns done as the first element of the returned list. Finally, the third element of the returned list contains the updated context. Callers should pass this in as CONTEXT in the next call to the command.

The command will raise a Tcl exception if the security context negotiation fails for any reason, including authentication failures.

sspi_server_new_context CREDENTIALS CLIENTDATA ?options?

Initiates the building of a new server-side, security context from based on the specified credentials and security data received from the client. CREDENTIALS is a handle to credentials returned by sspi_new_credentials. The returned value, which is a handle to a security context, should be treated as opaque by the caller and used as described in SSPI security context establishment.

The options below specify the requirements for the context. Note that not all security providers support all options or combinations of options. Refer to the Windows SDK for more information about these options.

-confidentiality BOOL	If specified as true, messages are to be encrypted.
-connection BOOL	If specified as true, the security context will not handle formatting of messages.
-datarep DATAREP	Specifies the data representation on the target. DATAREP must be either network (default) or native.
-delegate BOOL	If specified as true, the server can use the context to other servers as the client. Requires -mutualauth to also be specified as true.
-extendederror BOOL	When true, the remote end is notified of errors.
-integrity BOOL	If specified as true, messages are to be signed.
-mutualauth BOOL	If specified as true, both the client and server are to be authenticated.
-replaydetect BOOL	If specified as true, detection of replayed messages is desired.
-sequencedetect BOOL	If specified as true, detection of out-of-sequence messages is desired.
-stream BOOL	If specified as true, indicates a stream oriented connection.

When a security context is no longer required, it should be released by calling sspi_close_security_context.

sspi_verify_signature CONTEXT SIGNATURE DATA ?options?

Verifies that the signature SIGNATURE for the supplied data DATA is valid. Generates a Tcl error if the signature is not valid else returns an integer mask that indicates the level of protection (provider dependent).

Cryptographic API

SYNOPSIS

DESCRIPTION

SSPI overview

SSPI security context establishment

SSPI message signing and encryption

Commands

COPYRIGHT

TWAPI 3.1.17 Documentation