sdk

README

SFTPGo SDK

The SFTPGo SDK contains code useful for developing SFTPGo plugins.

Although we try not to break functionality, we reserve the right to reorganize the code at will and may occasionally cause breaks if they are warranted. As such we expect the tag of this module will stay less than v1.0.0.

Documentation

Overview

Package sdk provides SFTPGo data structures primarily intended for use within plugins

Index

• Constants
• Variables
• type AzBlobFsConfig
• type BandwidthLimit
  • func (l *BandwidthLimit) GetSourcesAsString() string
• type BaseAzBlobFsConfig
• type BaseGCSFsConfig
• type BaseS3FsConfig
• type BaseSFTPFsConfig
• type BaseUser
• type BaseUserFilters
• type BaseVirtualFolder
• type CryptFsConfig
• type DirectoryPermissions
• type Filesystem
• type FilesystemProvider
  • func GetProviderByName(name string) FilesystemProvider
  • func (p FilesystemProvider) Name() string
  • func (p FilesystemProvider) ShortInfo() string
• type GCSFsConfig
• type HooksFilter
• type PatternsFilter
  • func (p *PatternsFilter) GetCommaSeparatedPatterns() string
  • func (p *PatternsFilter) IsAllowed() bool
  • func (p *PatternsFilter) IsDenied() bool
• type RecoveryCode
• type S3FsConfig
• type SFTPFsConfig
• type TLSUsername
• type TOTPConfig
• type User
• type UserFilters
• type UserType
• type VirtualFolder

Constants

const (
	WebClientPubKeyChangeDisabled     = "publickey-change-disabled"
	WebClientWriteDisabled            = "write-disabled"
	WebClientMFADisabled              = "mfa-disabled"
	WebClientPasswordChangeDisabled   = "password-change-disabled"
	WebClientAPIKeyAuthChangeDisabled = "api-key-auth-change-disabled"
	WebClientInfoChangeDisabled       = "info-change-disabled"
	WebClientSharesDisabled           = "shares-disabled"
	WebClientPasswordResetDisabled    = "password-reset-disabled"
)

Web Client/user REST API restrictions

Variables

var (
	// WebClientOptions defines the available options for the web client interface/user REST API
	WebClientOptions = []string{WebClientWriteDisabled, WebClientPasswordChangeDisabled, WebClientPasswordResetDisabled,
		WebClientPubKeyChangeDisabled, WebClientMFADisabled, WebClientAPIKeyAuthChangeDisabled, WebClientInfoChangeDisabled,
		WebClientSharesDisabled}
	// UserTypes defines the supported user type hints for auth plugins
	UserTypes = []string{string(UserTypeLDAP), string(UserTypeOS)}
)

Types

type AzBlobFsConfig

type AzBlobFsConfig struct {
	BaseAzBlobFsConfig
	// Storage Account Key leave blank to use SAS URL.
	// The access key is stored encrypted based on the kms configuration
	AccountKey kms.BaseSecret `json:"account_key,omitempty"`
	// Shared access signature URL, leave blank if using account/key
	SASURL kms.BaseSecret `json:"sas_url,omitempty"`
}

AzBlobFsConfig defines the configuration for Azure Blob Storage based filesystem

type BandwidthLimit

type BandwidthLimit struct {
	// Source networks in CIDR notation as defined in RFC 4632 and RFC 4291
	// for example "192.0.2.0/24" or "2001:db8::/32". The limit applies if the
	// defined networks contain the client IP
	Sources []string `json:"sources"`
	// Maximum upload bandwidth as KB/s
	UploadBandwidth int64 `json:"upload_bandwidth,omitempty"`
	// Maximum download bandwidth as KB/s
	DownloadBandwidth int64 `json:"download_bandwidth,omitempty"`
}

BandwidthLimit defines a per-source bandwidth limit

func (*BandwidthLimit) GetSourcesAsString

func (l *BandwidthLimit) GetSourcesAsString() string

GetSourcesAsString returns the sources as comma separated string

type BaseAzBlobFsConfig

type BaseAzBlobFsConfig struct {
	Container string `json:"container,omitempty"`
	// Storage Account Name, leave blank to use SAS URL
	AccountName string `json:"account_name,omitempty"`
	// Optional endpoint. Default is "blob.core.windows.net".
	// If you use the emulator the endpoint must include the protocol,
	// for example "http://127.0.0.1:10000"
	Endpoint string `json:"endpoint,omitempty"`
	// KeyPrefix is similar to a chroot directory for local filesystem.
	// If specified then the SFTPGo user will only see objects that starts
	// with this prefix and so you can restrict access to a specific
	// folder. The prefix, if not empty, must not start with "/" and must
	// end with "/".
	// If empty the whole bucket contents will be available
	KeyPrefix string `json:"key_prefix,omitempty"`
	// The buffer size (in MB) to use for multipart uploads.
	// If this value is set to zero, the default value (1MB) for the Azure SDK will be used.
	// Please note that if the upload bandwidth between the SFTPGo client and SFTPGo server is
	// greater than the upload bandwidth between SFTPGo and Azure then the SFTP client have
	// to wait for the upload of the last parts to Azure after it ends the file upload to SFTPGo,
	// and it may time out.
	// Keep this in mind if you customize these parameters.
	UploadPartSize int64 `json:"upload_part_size,omitempty"`
	// How many parts are uploaded in parallel
	UploadConcurrency int `json:"upload_concurrency,omitempty"`
	// Set to true if you use an Azure emulator such as Azurite
	UseEmulator bool `json:"use_emulator,omitempty"`
	// Blob Access Tier
	AccessTier string `json:"access_tier,omitempty"`
}

BaseAzBlobFsConfig defines the base configuration for Azure Blob Storage based filesystem

type BaseGCSFsConfig

type BaseGCSFsConfig struct {
	Bucket string `json:"bucket,omitempty"`
	// KeyPrefix is similar to a chroot directory for local filesystem.
	// If specified then the SFTP user will only see objects that starts
	// with this prefix and so you can restrict access to a specific
	// folder. The prefix, if not empty, must not start with "/" and must
	// end with "/".
	// If empty the whole bucket contents will be available
	KeyPrefix      string `json:"key_prefix,omitempty"`
	CredentialFile string `json:"-"`
	// 0 explicit, 1 automatic
	AutomaticCredentials int    `json:"automatic_credentials,omitempty"`
	StorageClass         string `json:"storage_class,omitempty"`
	// The ACL to apply to uploaded objects. Leave empty to use the default ACL.
	// For more information and available ACLs, refer to the JSON API here:
	// https://cloud.google.com/storage/docs/access-control/lists#predefined-acl
	ACL string `json:"acl,omitempty"`
}

BaseGCSFsConfig defines the base configuration for Google Cloud Storage based filesystems

type BaseS3FsConfig

type BaseS3FsConfig struct {
	Bucket string `json:"bucket,omitempty"`
	// KeyPrefix is similar to a chroot directory for local filesystem.
	// If specified then the SFTP user will only see objects that starts
	// with this prefix and so you can restrict access to a specific
	// folder. The prefix, if not empty, must not start with "/" and must
	// end with "/".
	// If empty the whole bucket contents will be available
	KeyPrefix    string `json:"key_prefix,omitempty"`
	Region       string `json:"region,omitempty"`
	AccessKey    string `json:"access_key,omitempty"`
	Endpoint     string `json:"endpoint,omitempty"`
	StorageClass string `json:"storage_class,omitempty"`
	// The canned ACL to apply to uploaded objects. Leave empty to use the default ACL.
	// For more information and available ACLs, see here:
	// https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl
	ACL string `json:"acl,omitempty"`
	// The buffer size (in MB) to use for multipart uploads. The minimum allowed part size is 5MB,
	// and if this value is set to zero, the default value (5MB) for the AWS SDK will be used.
	// The minimum allowed value is 5.
	// Please note that if the upload bandwidth between the SFTP client and SFTPGo is greater than
	// the upload bandwidth between SFTPGo and S3 then the SFTP client have to wait for the upload
	// of the last parts to S3 after it ends the file upload to SFTPGo, and it may time out.
	// Keep this in mind if you customize these parameters.
	UploadPartSize int64 `json:"upload_part_size,omitempty"`
	// How many parts are uploaded in parallel
	UploadConcurrency int `json:"upload_concurrency,omitempty"`
	// The buffer size (in MB) to use for multipart downloads. The minimum allowed part size is 5MB,
	// and if this value is set to zero, the default value (5MB) for the AWS SDK will be used.
	// The minimum allowed value is 5. Ignored for partial downloads.
	DownloadPartSize int64 `json:"download_part_size,omitempty"`
	// How many parts are downloaded in parallel. Ignored for partial downloads.
	DownloadConcurrency int `json:"download_concurrency,omitempty"`
	// DownloadPartMaxTime defines the maximum time allowed, in seconds, to download a single chunk (5MB).
	// 0 means no timeout. Ignored for partial downloads.
	DownloadPartMaxTime int `json:"download_part_max_time,omitempty"`
	// Set this to `true` to force the request to use path-style addressing,
	// i.e., `http://s3.amazonaws.com/BUCKET/KEY`. By default, the S3 client
	// will use virtual hosted bucket addressing when possible
	// (`http://BUCKET.s3.amazonaws.com/KEY`)
	ForcePathStyle bool `json:"force_path_style,omitempty"`
}

BaseS3FsConfig defines the base configuration for S3 based filesystems

type BaseSFTPFsConfig

type BaseSFTPFsConfig struct {
	Endpoint     string   `json:"endpoint,omitempty"`
	Username     string   `json:"username,omitempty"`
	Fingerprints []string `json:"fingerprints,omitempty"`
	// Prefix is the path prefix to strip from SFTP resource paths.
	Prefix string `json:"prefix,omitempty"`
	// Concurrent reads are safe to use and disabling them will degrade performance.
	// Some servers automatically delete files once they are downloaded.
	// Using concurrent reads is problematic with such servers.
	DisableCouncurrentReads bool `json:"disable_concurrent_reads,omitempty"`
	// The buffer size (in MB) to use for transfers.
	// Buffering could improve performance for high latency networks.
	// With buffering enabled upload resume is not supported and a file
	// cannot be opened for both reading and writing at the same time
	// 0 means disabled.
	BufferSize int64 `json:"buffer_size,omitempty"`
}

BaseSFTPFsConfig defines the base configuration for SFTP based filesystem

type BaseUser

type BaseUser struct {
	// Data provider unique identifier
	ID int64 `json:"id"`
	// 1 enabled, 0 disabled (login is not allowed)
	Status int `json:"status"`
	// Username
	Username string `json:"username"`
	// Email
	Email string `json:"email,omitempty"`
	// Account expiration date as unix timestamp in milliseconds. An expired account cannot login.
	// 0 means no expiration
	ExpirationDate int64 `json:"expiration_date"`
	// Password used for password authentication.
	// For users created using SFTPGo REST API the password is be stored using bcrypt or argon2id hashing algo.
	// Checking passwords stored with pbkdf2, md5crypt and sha512crypt is supported too.
	Password string `json:"password,omitempty"`
	// PublicKeys used for public key authentication. At least one between password and a public key is mandatory
	PublicKeys []string `json:"public_keys,omitempty"`
	// The user cannot upload or download files outside this directory. Must be an absolute path
	HomeDir string `json:"home_dir"`
	// If sftpgo runs as root system user then the created files and directories will be assigned to this system UID
	UID int `json:"uid"`
	// If sftpgo runs as root system user then the created files and directories will be assigned to this system GID
	GID int `json:"gid"`
	// Maximum concurrent sessions. 0 means unlimited
	MaxSessions int `json:"max_sessions"`
	// Maximum size allowed as bytes. 0 means unlimited
	QuotaSize int64 `json:"quota_size"`
	// Maximum number of files allowed. 0 means unlimited
	QuotaFiles int `json:"quota_files"`
	// List of the granted permissions
	Permissions map[string][]string `json:"permissions"`
	// Used quota as bytes
	UsedQuotaSize int64 `json:"used_quota_size,omitempty"`
	// Used quota as number of files
	UsedQuotaFiles int `json:"used_quota_files,omitempty"`
	// Last quota update as unix timestamp in milliseconds
	LastQuotaUpdate int64 `json:"last_quota_update,omitempty"`
	// Maximum upload bandwidth as KB/s, 0 means unlimited.
	// This is the default if no per-source limit match
	UploadBandwidth int64 `json:"upload_bandwidth,omitempty"`
	// Maximum download bandwidth as KB/s, 0 means unlimited.
	// This is the default if no per-source limit match
	DownloadBandwidth int64 `json:"download_bandwidth,omitempty"`
	// Last login as unix timestamp in milliseconds
	LastLogin int64 `json:"last_login,omitempty"`
	// Creation time as unix timestamp in milliseconds. It will be 0 for admins created before v2.2.0
	CreatedAt int64 `json:"created_at"`
	// last update time as unix timestamp in milliseconds
	UpdatedAt int64 `json:"updated_at"`
	// optional description, for example full name
	Description string `json:"description,omitempty"`
	// free form text field for external systems
	AdditionalInfo string `json:"additional_info,omitempty"`
}

BaseUser defines the shared user fields

type BaseUserFilters

type BaseUserFilters struct {
	// only clients connecting from these IP/Mask are allowed.
	// IP/Mask must be in CIDR notation as defined in RFC 4632 and RFC 4291
	// for example "192.0.2.0/24" or "2001:db8::/32"
	AllowedIP []string `json:"allowed_ip,omitempty"`
	// clients connecting from these IP/Mask are not allowed.
	// Denied rules will be evaluated before allowed ones
	DeniedIP []string `json:"denied_ip,omitempty"`
	// these login methods are not allowed.
	// If null or empty any available login method is allowed
	DeniedLoginMethods []string `json:"denied_login_methods,omitempty"`
	// these protocols are not allowed.
	// If null or empty any available protocol is allowed
	DeniedProtocols []string `json:"denied_protocols,omitempty"`
	// filter based on shell patterns.
	// Please note that these restrictions can be easily bypassed.
	FilePatterns []PatternsFilter `json:"file_patterns,omitempty"`
	// max size allowed for a single upload, 0 means unlimited
	MaxUploadFileSize int64 `json:"max_upload_file_size,omitempty"`
	// TLS certificate attribute to use as username.
	// For FTP clients it must match the name provided using the
	// "USER" command
	TLSUsername TLSUsername `json:"tls_username,omitempty"`
	// user specific hook overrides
	Hooks HooksFilter `json:"hooks,omitempty"`
	// Disable checks for existence and automatic creation of home directory
	// and virtual folders.
	// SFTPGo requires that the user's home directory, virtual folder root,
	// and intermediate paths to virtual folders exist to work properly.
	// If you already know that the required directories exist, disabling
	// these checks will speed up login.
	// You could, for example, disable these checks after the first login
	DisableFsChecks bool `json:"disable_fs_checks,omitempty"`
	// WebClient related configuration options
	WebClient []string `json:"web_client,omitempty"`
	// API key auth allows to impersonate this user with an API key
	AllowAPIKeyAuth bool `json:"allow_api_key_auth,omitempty"`
	// UserType is an hint for authentication plugins.
	// It is ignored when using SFTPGo internal authentication
	UserType string `json:"user_type,omitempty"`
	// Per-source bandwidth limits
	BandwidthLimits []BandwidthLimit `json:"bandwidth_limits,omitempty"`
}

BaseUserFilters defines additional restrictions for a user

type BaseVirtualFolder

type BaseVirtualFolder struct {
	ID            int64  `json:"id"`
	Name          string `json:"name"`
	MappedPath    string `json:"mapped_path,omitempty"`
	Description   string `json:"description,omitempty"`
	UsedQuotaSize int64  `json:"used_quota_size"`
	// Used quota as number of files
	UsedQuotaFiles int `json:"used_quota_files"`
	// Last quota update as unix timestamp in milliseconds
	LastQuotaUpdate int64 `json:"last_quota_update"`
	// list of usernames associated with this virtual folder
	Users []string `json:"users,omitempty"`
	// Filesystem configuration details
	FsConfig Filesystem `json:"filesystem"`
}

BaseVirtualFolder defines the path for the virtual folder and the used quota limits. The same folder can be shared among multiple users and each user can have different quota limits or a different virtual path.

type CryptFsConfig

type CryptFsConfig struct {
	Passphrase kms.BaseSecret `json:"passphrase,omitempty"`
}

CryptFsConfig defines the configuration to store local files as encrypted

type DirectoryPermissions

type DirectoryPermissions struct {
	Path        string
	Permissions []string
}

DirectoryPermissions defines permissions for a directory virtual path

type Filesystem

type Filesystem struct {
	Provider     FilesystemProvider `json:"provider"`
	S3Config     S3FsConfig         `json:"s3config,omitempty"`
	GCSConfig    GCSFsConfig        `json:"gcsconfig,omitempty"`
	AzBlobConfig AzBlobFsConfig     `json:"azblobconfig,omitempty"`
	CryptConfig  CryptFsConfig      `json:"cryptconfig,omitempty"`
	SFTPConfig   SFTPFsConfig       `json:"sftpconfig,omitempty"`
}

Filesystem defines filesystem details

type FilesystemProvider

type FilesystemProvider int

FilesystemProvider defines the supported storage filesystems

const (
	LocalFilesystemProvider     FilesystemProvider = iota // Local
	S3FilesystemProvider                                  // AWS S3 compatible
	GCSFilesystemProvider                                 // Google Cloud Storage
	AzureBlobFilesystemProvider                           // Azure Blob Storage
	CryptedFilesystemProvider                             // Local encrypted
	SFTPFilesystemProvider                                // SFTP
)

supported values for FilesystemProvider

func GetProviderByName

func GetProviderByName(name string) FilesystemProvider

GetProviderByName returns the FilesystemProvider matching a given name to provide backwards compatibility, numeric strings are accepted as well

func (FilesystemProvider) Name

func (p FilesystemProvider) Name() string

Name returns the Provider's unique name

func (FilesystemProvider) ShortInfo

func (p FilesystemProvider) ShortInfo() string

ShortInfo returns a human readable, short description for the given FilesystemProvider

type GCSFsConfig

type GCSFsConfig struct {
	BaseGCSFsConfig
	Credentials kms.BaseSecret `json:"credentials,omitempty"`
}

GCSFsConfig defines the configuration for Google Cloud Storage based filesystems

type HooksFilter

type HooksFilter struct {
	ExternalAuthDisabled  bool `json:"external_auth_disabled"`
	PreLoginDisabled      bool `json:"pre_login_disabled"`
	CheckPasswordDisabled bool `json:"check_password_disabled"`
}

HooksFilter defines user specific overrides for global hooks

type PatternsFilter

type PatternsFilter struct {
	// Virtual path, if no other specific filter is defined, the filter applies for
	// sub directories too.
	// For example if filters are defined for the paths "/" and "/sub" then the
	// filters for "/" are applied for any file outside the "/sub" directory
	Path string `json:"path"`
	// files with these, case insensitive, patterns are allowed.
	// Denied file patterns are evaluated before the allowed ones
	AllowedPatterns []string `json:"allowed_patterns,omitempty"`
	// files with these, case insensitive, patterns are not allowed.
	// Denied file patterns are evaluated before the allowed ones
	DeniedPatterns []string `json:"denied_patterns,omitempty"`
}

PatternsFilter defines filters based on shell like patterns. These restrictions do not apply to files listing for performance reasons, so a denied file cannot be downloaded/overwritten/renamed but will still be in the list of files. System commands such as Git and rsync interacts with the filesystem directly and they are not aware about these restrictions so they are not allowed inside paths with extensions filters

func (*PatternsFilter) GetCommaSeparatedPatterns

func (p *PatternsFilter) GetCommaSeparatedPatterns() string

GetCommaSeparatedPatterns returns the first non empty patterns list comma separated

func (*PatternsFilter) IsAllowed

func (p *PatternsFilter) IsAllowed() bool

IsAllowed returns true if the patterns has one or more allowed patterns

func (*PatternsFilter) IsDenied

func (p *PatternsFilter) IsDenied() bool

IsDenied returns true if the patterns has one or more denied patterns

type RecoveryCode

type RecoveryCode struct {
	Secret kms.BaseSecret `json:"secret"`
	Used   bool           `json:"used,omitempty"`
}

RecoveryCode defines a 2FA recovery code

type S3FsConfig

type S3FsConfig struct {
	BaseS3FsConfig
	AccessSecret kms.BaseSecret `json:"access_secret,omitempty"`
}

S3FsConfig defines the base configuration for S3 based filesystems

type SFTPFsConfig

type SFTPFsConfig struct {
	BaseSFTPFsConfig
	Password   kms.BaseSecret `json:"password,omitempty"`
	PrivateKey kms.BaseSecret `json:"private_key,omitempty"`
}

SFTPFsConfig defines the configuration for SFTP based filesystem

type TLSUsername

type TLSUsername string

TLSUsername defines the TLS certificate attribute to use as username

const (
	TLSUsernameNone TLSUsername = "None"
	TLSUsernameCN   TLSUsername = "CommonName"
)

Supported certificate attributes to use as username

type TOTPConfig

type TOTPConfig struct {
	Enabled    bool           `json:"enabled,omitempty"`
	ConfigName string         `json:"config_name,omitempty"`
	Secret     kms.BaseSecret `json:"secret,omitempty"`
	// TOTP will be required for the specified protocols.
	// SSH protocol (SFTP/SCP/SSH commands) will ask for the TOTP passcode if the client uses keyboard interactive
	// authentication.
	// FTP have no standard way to support two factor authentication, if you
	// enable the support for this protocol you have to add the TOTP passcode after the password.
	// For example if your password is "password" and your one time passcode is
	// "123456" you have to use "password123456" as password.
	Protocols []string `json:"protocols,omitempty"`
}

TOTPConfig defines the time-based one time password configuration

type User

type User struct {
	BaseUser
	// Additional restrictions
	Filters UserFilters `json:"filters"`
	// Mapping between virtual paths and virtual folders
	VirtualFolders []VirtualFolder `json:"virtual_folders,omitempty"`
	// Filesystem configuration details
	FsConfig Filesystem `json:"filesystem"`
}

User defines a SFTPGo user

type UserFilters

type UserFilters struct {
	BaseUserFilters
	// Time-based one time passwords configuration
	TOTPConfig TOTPConfig `json:"totp_config,omitempty"`
	// Recovery codes to use if the user loses access to their second factor auth device.
	// Each code can only be used once, you should use these codes to login and disable or
	// reset 2FA for your account
	RecoveryCodes []RecoveryCode `json:"recovery_codes,omitempty"`
}

UserFilters defines additional restrictions for a user TODO: rename to UserOptions in v3

type UserType

type UserType string

UserType defines the supported user types. This is an hint for external auth plugins, is not used in SFTPGo directly

const (
	UserTypeLDAP UserType = "LDAPUser"
	UserTypeOS   UserType = "OSUser"
)

User types, auth plugins could use this info to choose the correct authentication backend

type VirtualFolder

type VirtualFolder struct {
	BaseVirtualFolder
	VirtualPath string `json:"virtual_path"`
	// Maximum size allowed as bytes. 0 means unlimited, -1 included in user quota
	QuotaSize int64 `json:"quota_size"`
	// Maximum number of files allowed. 0 means unlimited, -1 included in user quota
	QuotaFiles int `json:"quota_files"`
}

VirtualFolder defines a mapping between an SFTPGo exposed virtual path and a filesystem path outside the user home directory. The specified paths must be absolute and the virtual path cannot be "/", it must be a sub directory. The parent directory for the specified virtual path must exist. SFTPGo will, by default, try to automatically create any missing parent directory for the configured virtual folders at user login.