Tcl Windows API extension

This package includes procedures related to the Security Service Provider Interface (SSPI) on the Windows platforms. For commands for other cryptographic operations, refer to the CryptoAPI documentation.

SSPI overview

The Security Support Provider Interface 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.

This module currently supports only the Negotiate, NTLM, Kerberos, SChannel and Microsoft Unified Security Protocol Provider packages.

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_acquire_credentials with the -role client option. It then creates a new client security context by calling sspi_client_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_step 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_acquire_credentials with the -role server. It then creates a new server security context by calling sspi_server_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_step 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_context_features, sspi_context_username and sspi_context_sizes. In the case of SSL/SChannel based providers, the sspi_local_cert and sspi_remote_cert return the certificates in use for a connection. Note that not all commands are supported by all security providers.

The security context should be released when no longer needed. For schannel based providers only, first call sspi_shutdown_context and pass any returned data to the remote peer. Then call sspi_delete_context to release context releases. For other providers, only sspi_delete_context should be called.

Similarly, when no longer required, both the server and client ends should free resources associated with their credentials by calling sspi_free_credentials.

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_sign and sspi_verify_signature respectively.

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

SSPI stream encryption

For SSPI stream contexts, the commands sspi_encrypt_stream and sspi_decrypt_stream encrypt and decrypt streaming data. Alternately the sspi_encrypt_and_write command can be used to directly write encrypted data to a channel.

Commands

sspi_acquire_credentials ?options?

Returns a credentials handle that can be used to negotiate and establish a security context. The command returns the 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:

-credentials CREDENTIALS	Specifies the credentials to which a handle is to be returned. If unspecified the default credentials for the package are used. For NTLM or Negotiate providers, the sspi_winnt_identity_credentials should be used to return non-default credentials in the appropriate format. For SSL/Schannel based providers, the sspi_schannel_credentials should be used for the same purpose.
-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.
-principal 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.
-role ROLE	Indicates how the credentials will be used, based on ROLE - client or outbound for clients, server or inbound for servers and both (default) if credentials are used for both purposes. Note that SSL/SChannel based providers require separate client and server credentials and both is not a valid option for them.

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

sspi_client_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_acquire_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. Note that several Windows versions, including Windows 7, may experience SSL/TLS negotiation failures when this option is specified. See Microsoft Knowledgebase article KB975858 for details.
-integrity BOOL	If specified as true, messages are to be signed.
-manualvalidation BOOL	If BOOL is false (default), SChannel based providers will validate the remote server's certificate. If specified as true, the provider will not validate the received certificate. It is the caller's responsibility to do so. The remote certificate can be retrieved with sspi_remote_cert and verified as described in Certificate verification.
-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. In the case of a SSL/SChannel based provider, this is generally the name that should match the subject name in the certificate sent by the server.
-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_delete_context.

sspi_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_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_context_username CONTEXT

TBD

sspi_decrypt CONTEXT ENCRYPTTOKEN ENCRYPTEDDATA PADDING ?options?

Returns the decrypted data. CONTEXT is a datagram or connection context. The other parameters correspond to the corresponding values returned from sspi_encrypt.

sspi_decrypt_stream CONTEXT ENCRYPTEDDATA

Returns the decrypted data using the specified stream context. The return value is a pair consisting of a status and the decrypted data. The status may be one of ok, expired, or renegotiate. In all cases the second element, if non empty, contains the decrypted data.

A status of ok is a normal return. If the status is expired, the context has expired and the caller should call sspi_shutdown_context and sspi_delete_context to free the context.

sspi_delete_context CONTEXT

Closes a security context constructed through sspi_client_context or sspi_server_context or and frees any associated resources.

sspi_encrypt CONTEXT BINDATA ?options?

Encrypts the binary data BINDATA based on the specified security context. Returns a list of three elements - the encryption token, the encrypted data and padding. These must all be passed to the remote peer for it successfully decrypt and verify the data.

sspi_encrypt_and_write CONTEXT BINDATA ?options?

Encrypts binary data BINDATA based on the specified security context and writes it to the specified channel. The channel must be in binary mode.

sspi_encrypt_stream CONTEXT BINDATA ?options?

Encrypts BINDATA based on the specified security context and returns the encrypted data.

sspi_enumerate_packages ?options?

If no arguments are specified, returns a list of the names of the security provider packages available on the system. If any options are specified, returns a dictionary keyed by the package name. The corresponding value is itself a dictionary with the keys dependent on the options specified to the command:

-all	Same as all options being specified.
-capabilities	A list of tokens that describe the capabilties of the provider.
-comment	A comment describing the provider.
-rpcid	A DCE RPC identifier, if supported.
-maxtokensize	Maximum size of a security token.
-name	Name of the provider.
-version	The version of the provider interface.

sspi_free_credentials arg CREDENTIALS

Frees resources associated with credentials returned by sspi_acquire_credentials.

sspi_issuers_accepted_by_peer CONTEXT

For SChannel based client contexts, the remote server can request a client certificate issued by specific certificate issuers it will accept. This command returns the list of issuers acceptable to the remote server.

sspi_local_cert CONTEXT

Returns a certificate context for the certificate for the local end of a secured connection. The returned certificate context must be freed by calling cert_release.

sspi_remote_cert CONTEXT

Returns a certificate context for the certificate sent by the remote end of a secured connection. The returned certificate context must be freed by calling cert_release.

sspi_server_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_acquire_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_delete_context.

sspi_sign CONTEXT DATA ?options?

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

sspi_schannel_credentials ?options?

Returns credentials that can be passed to the sspi_acquire_credentials command for SSL/SChannel providers. The credentials are specified through the following options:

-certificates CERTLIST	CERTLIST is a list of certificate context handles with private keys that are used to authenticate the application. Each handle corresponds to a key exchange method supported by the application. On the client end, this need not be specified in which case the provider will find an appropriate certificate if needed.
-cipherstrength CIPHERSTRENGTH	Specifies the strength of the block ciphers to be used in connections using the returned credentials. CIPHERSTRENGTH is list of one or two elements. The first element is the minimum number of bits required in the negotiated encryption key. The second element is the maximum number of bits in the key and defaults to the minimum number of bits if the list contains only one element. A value of 0 indicates a system-specific default to be used. A value of -1 indicates a null cipher (no encryption but with message authentication). This should be used only for debugging purposes.
-protocols PROTOCOLLIST	Specifies the protocols that are acceptable for a connection using the returned credentials. PROTOCOLLIST is a list of one or more of the following: ssl2, ssl3, tls1, tls1.1 and tls1.2. If unspecified, or if PROTOCOLLIST is an empty list, defaults to the list of protocols configured in the system registry.
-rootstore HSTORE	Specifies a handle to an additional certificate root store that contains root certificates to authenticate incoming client connections. This is only used by server applications which need to authenticate clients.
-sessionlifespan MILLISECS	Specifies the number of milliseconds that a Schannel session should be cached. New connections after this time will require a new session. A value of 0 (default) indicates the system-specific default is to be used.

sspi_shutdown_context CONTEXT

Begins the process of shutting down a context. This command is needed, and should be called, only for contexts based on the Schannel based providers. The return value from the command is a pair, the first element of which is the continue, or done. In the former case, the caller should call sspi_step to continue the process of shutting down. In the latter case, the caller can release the context by calling sspi_delete_context. In both cases, the second element contains binary data to be sent to the remote end to complete the shutdown.

sspi_step 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 is a handle to the security context being built. This is the return value from sspi_client_context or sspi_server_context.

The command returns a list containing two or three elements. The first element is a status which may be one of the following values:

done	Indicates that the security context negotiation is completed. The application can use it for cryptographic operations such as signing or encryption.
continue	The security context negotiation is in progress. Additional steps are required in the negotiation process and sspi_step must be called again with additional data received from the remote end.
disconnected	The negotiation is terminated and cannot be used for cryptographic operations. Caller should delete the context using sspi_delete_context.

If the second element of the returned list is not an empty string, it contains data that must be sent to the remote end. This is true for all three cases above.

Finally, the third element of the returned list, if present, contains leftover application data after negotiation is complete (indicated by a status of done). If not empty, it must be passed to the decryption commands. This occurs for stream oriented contexts only (like SSL/TLS).

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

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

sspi_winnt_identity_credentials USER DOMAIN PASSWORD

Returns the credentials based on the specified arguments in a format that can be passed to the sspi_acquire_credentials command when NTLM, Kerberos or Negotiate providers are in use. PASSWORD should be in the form described in Password protection.

SSPI

SYNOPSIS

DESCRIPTION

SSPI overview

SSPI security context establishment

SSPI message signing and encryption

SSPI stream encryption

Commands

COPYRIGHT

TWAPI 4.5.2 Documentation