mssql

README

MSSQL Server Connector

NOTE: This connector is still in alpha and should not be used in production.

The MSSQL Server Connector enables:

• Kubernetes or OpenShift applications to connect to a MSSQL Server 2017 v14.x database using SQL Server authentication
• Connecting applications to have no knowledge of the required database credentials
• New connections to MSSQL to always use fresh credentials from the configured credential provider

Supported configuration (with samples)

Here's a sample secretless.yml configuration file that enables Secretless to connect to an MSSQL Server:

version: 2

services:
  mssql:
    connector: mssql
    listenOn: tcp://0.0.0.0:2223
    credentials:
      username: sa
      password:
        from: conjur
        get: my-sql-server-password
      host: mssql
      port: 1433

Required credentials

All credentials are required unless they're explicitly marked as "optional".

• username - Database username under SQL Server authentication mode
• password - Database password under SQL Server authentication mode
• host - The network address of the target MSSQL Server. In the example above, sine we're using Docker networking, it happens to be just the bare name mssql.
• (optional) port - The port the target MSSQL Server is listening on. Defaults to the standard 1433.

Target Service SSL Support

SSL is currently not supported in the alpha version, but will be coming soon.

Supported versions

The connector supports MSSQL Server 2017.

In particular, it is tested against the mcr.microsoft.com/mssql/server:2017-latest Linux docker image, whose version at the time of this writing is:

Microsoft SQL Server 2017 (RTM-CU17) (KB4515579) - 14.0.3238.1 (X64)  
Sep 13 2019 15:49:57  
Copyright (C) 2017 Microsoft Corporation 
Developer Edition (64-bit) on Linux (Ubuntu 16.04.6 LTS)

Known limitations

• Does not currently support SSL in the connection between Secretless and MSSQL Server.
• Only supports SQL Server authentication mode
• Only limited tests have been performed. Specifically, the ability to connect using Secretless has been tested using two clients:
  • The sqlcmd tool that ships with the above version of MSSQL server
  • The Go MSSQL driver provided by the package github.com/denisenkom/go-mssqldb
• Since we use the go-mssqldb package, Secretless is also affected by the known issues of that package.

Documentation

Index

• func GetTCPPlugin() tcp.Plugin
• func NewConnector(conRes connector.Resources) tcp.Connector
• func NewMSSQLConnector(dsn string) (types.MSSQLConnector, error)
• func PluginInfo() map[string]string
• func ReadLogin(clientBufRaw io.ReadWriteCloser) (interface{}, error)
• func ReadPreloginWithPacketType(rawTdsBuffer io.ReadWriteCloser, rawPktType uint8) (map[uint8][]byte, error)
• func WritePreloginWithPacketType(rawTdsBuffer io.ReadWriteCloser, fields map[uint8][]byte, rawPktType uint8) error
• type ConnectionDetails
  • func NewConnectionDetails(credentials map[string][]byte) (*ConnectionDetails, error)
  • func (cd *ConnectionDetails) Address() string
• type SingleUseConnector
  • func NewSingleUseConnector(logger log.Logger) *SingleUseConnector
  • func NewSingleUseConnectorWithOptions(logger log.Logger, newMSSQLConnector types.MSSQLConnectorCtor, ...) *SingleUseConnector
  • func (connector *SingleUseConnector) Connect(clientConn net.Conn, credentialValuesByID connector.CredentialValuesByID) (net.Conn, error)
  • func (connector *SingleUseConnector) CreateAuthenticationOKMessage() []byte
  • func (connector *SingleUseConnector) CreateGenericErrorMessage() []byte

Functions

func GetTCPPlugin

func GetTCPPlugin() tcp.Plugin

GetTCPPlugin is required as part of the Secretless plugin spec for TCP connector plugins. It returns the TCP plugin.

func NewConnector

func NewConnector(conRes connector.Resources) tcp.Connector

NewConnector returns a tcp.Connector which returns an authenticated connection to a target service for each incoming client connection. It is a required method on the tcp.Plugin interface. The single argument passed in is of type connector.Resources. It contains connector-specific config and a logger.

func NewMSSQLConnector

func NewMSSQLConnector(dsn string) (types.MSSQLConnector, error)

NewMSSQLConnector is the production implementation of MSSQLConnectorCtor, used for creating mssql.Connector instances. We need to wrap the raw constructor provided by mssql (ie, mssql.NewConnector) in this function so that it returns an interface, which enables us to mock it in unit tests.

func PluginInfo

func PluginInfo() map[string]string

PluginInfo is required as part of the Secretless plugin spec. It provides important metadata about the plugin.

func ReadLogin

func ReadLogin(clientBufRaw io.ReadWriteCloser) (interface{}, error)

ReadLogin is the production version of our readLogin dependency, which delegates to the actual 3rd party driver.

func ReadPreloginWithPacketType

func ReadPreloginWithPacketType(
	rawTdsBuffer io.ReadWriteCloser,
	rawPktType uint8,
) (map[uint8][]byte, error)

ReadPreloginWithPacketType is the production version of our readPrelogin dependency, which delegates to the actual 3rd party driver.

func WritePreloginWithPacketType

func WritePreloginWithPacketType(
	rawTdsBuffer io.ReadWriteCloser,
	fields map[uint8][]byte,
	rawPktType uint8,
) error

WritePreloginWithPacketType is the production version of our writePrelogin dependency, which delegates to the actual 3rd party driver.

Types

type ConnectionDetails

type ConnectionDetails struct {
	Host     string
	Port     uint
	Username string
	Password string
}

ConnectionDetails stores the connection info to the real backend database. These values are pulled from the SingleUseConnector credentials config

func NewConnectionDetails

func NewConnectionDetails(credentials map[string][]byte) (*ConnectionDetails, error)

NewConnectionDetails is a constructor of ConnectionDetails structure from a map of credentials.

func (*ConnectionDetails) Address

func (cd *ConnectionDetails) Address() string

Address returns a string representing the network location (host and port) of a MSSQL server. This is the string you would would typically use to connect to the database -- eg, in cmd line tools.

type SingleUseConnector

type SingleUseConnector struct {
	// contains filtered or unexported fields
}

SingleUseConnector is used to create an authenticated connection to an MSSQL target

func NewSingleUseConnector

func NewSingleUseConnector(logger log.Logger) *SingleUseConnector

NewSingleUseConnector creates a new production SingleUseConnector

func NewSingleUseConnectorWithOptions

func NewSingleUseConnectorWithOptions(
	logger log.Logger,
	newMSSQLConnector types.MSSQLConnectorCtor,
	readPrelogin types.ReadPreloginFunc,
	writePrelogin types.WritePreloginFunc,
	readLogin types.ReadLoginFunc,
	newTdsBuffer types.TdsBufferCtor,
) *SingleUseConnector

NewSingleUseConnectorWithOptions creates a new SingleUseConnector, and allows you to specify the newMSSQLConnector explicitly. Intended to be used in unit tests only.

func (*SingleUseConnector) Connect

func (connector *SingleUseConnector) Connect(
	clientConn net.Conn,
	credentialValuesByID connector.CredentialValuesByID,
) (net.Conn, error)

Connect implements the tcp.Connector func signature

It is the main method of the SingleUseConnector. It:

1. Constructs connection details from the provided credentials map.
2. Reads the client PreLogin request
3. Adds channels to the context that can intercept data from the driver
4. Initiates authentication and connection to MsSQL through the third-party driver
5. Intercepts PreLogin response from the driver
6. Customizes the PreLogin response to meet Secretless standards and sends it to the user

Connect requires "host", "port", "username" and "password" credentials.

func (*SingleUseConnector) CreateAuthenticationOKMessage

func (connector *SingleUseConnector) CreateAuthenticationOKMessage() []byte

CreateAuthenticationOKMessage creates an MSSQL message which indicates successful authentication.

func (*SingleUseConnector) CreateGenericErrorMessage

func (connector *SingleUseConnector) CreateGenericErrorMessage() []byte

CreateGenericErrorMessage creates an MSSQL error message