Introduction

**

MySCP

What is this ?

If you need to transfer files to or from your web site securely, you will want to use Secure Copy - also known as SCP. SCP uses encryption similar to SSH (Secure Shell) to encrypt data between the client and server. This ensures that no one can intercept and view the data transmitted.

In most situations such as when authentication is required (i.e. whenever you are asked for your password), SCP should always be used as opposed to FTP to transfer files. Regular FTP sends your uniq name, password, and other information across the network in clear text format. This makes it very easy for others to detect your information, and use it to do sinister things to your account and the network.

This level of security can be extremely important if you are transferring mission critical data such as Credit Card records, client information, digital assets, or other critical and sensitive data.


License

MySCP License Agreement

1. License Agreement. As used in this Agreement, "Activecrypt" shall mean Activecrypt Software LLC. Activecrypt grants Licensee a non-exclusive and non-transferable license to reproduce and use for personal or internal business purposes the executable code version of the Product, provided any copy must contain all of the original proprietary notices. This license does not entitle Licensee to receive from Activecrypt hard-copy documentation, technical support, telephone assistance, or enhancements or updates to the Product. If more than one license agreement was provided for the Product, and the terms vary, the order of precedence of those license agreements is as follows: a signed agreement, a license agreement available for review on the Activecrypt website, a printed or electronic agreement that states clearly that it supersedes other agreements, a printed agreement provided with the Product, an electronic agreement provided with the Product. Activecrypt may terminate this Agreement at any time, for any reason or no reason. Activecrypt may also terminate this Agreement if Licensee breaches any of its terms and conditions. Upon termination, Licensee shall destroy all copies of the Product.

2. Restrictions. Without Activecrypt’s prior written consent, Licensee may not: (i) modify or create any derivative works of the Product or documentation, including customization, translation or localization; (ii) decompile, disassemble, reverse engineer, or otherwise attempt to derive the source code for the Product (except to the extent applicable laws specifically prohibit such restriction); (iii) redistribute, encumber, sell, rent, lease, sublicense, or otherwise transfer rights to the Product; (iv) remove or alter any trademark, logo, copyright or other proprietary notices, legends, symbols.

3. Fees. There is no license fee for the Product. If Licensee wishes to receive the Product on media, there may be a small charge for the media and for shipping and handling. Licensee is responsible for any and all taxes.

4. Disclaimer of Warranty. THE PRODUCT IS PROVIDED FREE OF CHARGE, AND, THEREFORE, ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE WARRANTIES THAT IT IS FREE OF DEFECTS, VIRUS FREE, ABLE TO OPERATE ON AN UNINTERRUPTED BASIS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS AGREEMENT. NO USE OF THE PRODUCT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.

5. Limitation of Liability. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL Activecrypt OR ITS AFFILIATES OR SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF OR INABILITY TO USE THE PRODUCT, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOST PROFITS, LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF, AND REGARDLESS OF THE LEGAL OR EQUITABLE THEORY (CONTRACT, TORT OR OTHERWISE) UPON WHICH THE CLAIM IS BASED. IN ANY CASE, Activecrypt’S COLLECTIVE LIABILITY UNDER ANY PROVISION OF THIS AGREEMENT SHALL NOT EXCEED IN THE AGGREGATE THE SUM OF THE FEES LICENSEE PAID FOR THIS LICENSE (IF ANY). SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL, CONSEQUENTIAL OR SPECIAL DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.

6. Export Control. Licensee agrees to comply with all export laws and restrictions and regulations of the United States or foreign agencies or authorities, and not to export or re-export the Product or any direct product thereof in violation of any such restrictions, laws or regulations, or without all necessary approvals. As applicable, each party shall obtain and bear all expenses relating to any necessary licenses and/or exemptions with respect to its own export of the Product from the U.S. By installing or using the Product, Licensee agrees to the foregoing and represents and warrants that it complies with these conditions.

4. Proprietary Rights. Title, ownership rights, and intellectual property rights in the Product shall remain in Activecrypt and/or its suppliers. The Product is protected by copyright and other intellectual property laws and by international treaties. The source code of the MySCP is partially based on Putty.

PuTTY is copyright 1997-2003 Simon Tatham.

Portions copyright Robert de Bath, Joris van Rantwijk, Delian Delchev, Andreas Schultz, Jeroen Massar, Wez Furlong, Nicolas Barry, and CORE SDI S.A.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL SIMON TATHAM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


AbsentKeyPolicy

This property defines the behavior of the component if it meets unknown host. By default this property is CACHE. This means that for every host component stores fingerprints in the registry. This provides tracking of the server keys and avoids "Man-in-the-Middle" attacks. See also DifferentKeyPolicy.

This property can be one of the following:

CONN_ABANDON | Immediately terminate the connection. Default.
NO_CACHE | Do not save fingerprint to the registry.
CACHE | Save fingerprint to the registry.
THROW_EVENT | Throw event with information about host and fingerprint. See OnAbsentFingerprint for details.


Compression

Property Compression As ECOMPRESSION

Compression is extremely useful if you send uncompressed data over the network. If you enable compression, the component will use fully transparent compression and decompression on-fly. Documents and html pages for example are good candidates for compressed transmission. But if you send a large archive, compression is useless.

This property can be one of the following:

COMPRESSION_ENABLED | Enable compression
COMPRESSION_DISABLED | Disable compression


DifferentKeyPolicy

property DifferentKeyPolicy As KEYPOLICY

This property defines the behavior of the component in the case of the absent host. The component stores finger prints of all known hosts in the registry. Why ? Because it can warn if the fingerprint has been changed. New fingerprints could mean that administrator of the SSH server has regenerated keys for the server or .... someone has supplied wrong keys to the component. The second case means hacking attempt. You can find more about this attack on the Google if you search for "man-in-the-middle attack". Default value is CONN_ABANDON

This property can have one of the following values:

CONN_ABANDON | Immediately terminate the connection. Default.
NO_CACHE | Do not save fingerprint to the registry.
CACHE | Save fingerprint to the registry.
THROW_EVENT | Throw event with information about host and fingerprint. See OnDifferentFingerprint for details.


Compression

Error

Property Error As SCPERROR

Returns the status of the last operation. This value changes asynchronously. This means that it can be changed by the component itself without your interaction.

The list of all possible errors and its meaning:

SCPERR_NO_ERRORS | No errors
SCPERR_UNABLE_TO_INITIALIZE_WINSOCK | Unable to initialize WinSock
SCPERR_WINSOCK_VER_INCOMPATIBLE_1_1 | WinSock version is incompatible with 1.1
SCPERR_EMPTY_HOST_NAME | Empty host name
SCPERR_NO_SUCH_FILE_OR_DIR | No such file or directory
SCPERR_TARGET_NOT_DIR | Target is not a directory
SCPERR_MULTIPLELEVEL_WILDCARDS_UNSUPPORTED | Multiple-level wildcards unsupported
SCPERR_WILDCARD_MATCHED_NO_FILES | Wildcard matched no files
SCPERR_UNABLE_TO_OPEN_FILE | Unable to open file
SCPERR_UNABLE_TO_OPEN_DIRECTORY | Unable to open directory
SCPERR_ERROR_WHILE_WRITING | Error while writing
SCPERR_UNABLE_TO_CREATE_DIRECTORY | Unable to create directory
SCPERR_ERROR_WHILE_READING | Error while reading
SCPERR_FILE_TYPE_NOT_SUPPLIED | File type not supplied
SCPERR_ERROR_WHILE_SENDING_DATA | Error while sending data
SCPERR_ERROR_WHILE_RECEIVING_DATA | Error while receiving data
SCPERR_INTERNAL_ERROR | Internal error
SCPERR_OUT_OF_MEMORY | Out of memory
SCPERR_HOST_NOT_FOUND | Host not found
SCPERR_TRY_AGAIN, | Host does not exist
SCPERR_NET_DOWN | Network is down
SCPERR_UNABLE_TO_AUTHENTICATE | Unable to authenticate
SCPERR_NETWORK_ERROR | Network error
SCPERR_PROTOCOL_ERROR | Protocol error"
SCPERR_PERMISSION_DENIED | Permission denied
SCPERR_TIMEDOUT | Connection timed out
SCPERR_OPERATION_UNSUPPORTED | Operation unsupported
SCPERR_CONNECTION_ABANDONED | Connection abandoned
SCPERR_ALREADY_BUSY | Already busy
SCPERR_CONNECTION_RESET_BY_USER | Connection reset by user
SCPERR_SERVER_SENT_DISCONNECT_MESSAGE | Server sent disconnect message
SCPERR_COULD_NOT_CONNECT | Could not connect
SCPERR_LOST_CONNECTION | Lost connection
SCPERR_SSH2_PROTOCOL_NOT_PROVIDED_BY_SERVER | SSH protocol version 2 not provided by server


Status

Property Status As STATUS

This property provides the information about current status of the component. It can have one of the following values:

STATUS_NOTCONNECTED | Idle state.
STATUS_CONNECTING | Connecting to the host.
STATUS_AUTHORIZING | Authorization is in progress.
STATUS_SENDING | Transmitting file to the server.
STATUS_RECEIVING | Receiving file from the server.
STATUS_DISCONNECTING | Disconnection is in progress.


Timeout

property Timeout As Long

Defines timeout in seconds for all underlying socket operations. It affects on connection time as well as sending and receiving packet. Default value is 5. If you are behind firewall or use dialup, you may want to set up this property to higher value.


OnAbsentFingerprint

event OnAbsentFingerprint ( Host As String, Fingerprint As String, Save As Boolean)

This event is fired when component receives keys from unknown host. See AbsentKeyPolicy for details. If you set Save to True, new host and its fingerprint will be saved in the registry. If you sent this property to If you want to cancel the connection, you should call DisconnectNow function.


OnAuthorization

event OnAuthorization ()

This event happens after component successfully authorized on the server.


OnConnect

event OnConnect ()

This event happens when the component has been successfully connected to the host, but have not yet been authorized.


OnDifferentFingerprint

event OnDifferentFingerprint ( Host As String, Fingerprint As String, Save As Boolean)

This event is fired when component receives keys from host which already has another fingerprints and DifferentKeyPolicy set to THROW_EVENT. See DifferentKeyPolicy for details. If you set Save to True, new fingerprint will be saved in the registry and authorization will succeed . If you sent this property to False, authorization will succeed but new fingerprint will not be saved. If you want to cancel the connection, you should call DisconnectNow function.


OnDisconnect

event OnDisconnect ()

This event is fired when the component disconnects from the server.


OnProcessFile

event OnProcessFile (Filename As String, Percent As Integer)

This events fired when MySCP has transmitted a portion of a file. By utilizing this event you can draw progress bars which display which file is currently is being transmitted and how many has been done so far. When you transmit a whole directory, this events reports actual file and transmitted percents of this file.


OnError

event OnError ( Error As SCPERROR, ErrorMessage As String)

This event is fired when error happens.

Here is the list of all possible errors and its meaning.


DisconnectNow

Sub DisconnectNow ()

Immediately terminates connection. You can use this function from event handlers. For example if you found that keys supplied by SSH servers are wrong. See OnAbsentFingerprint and OnDifferentFingerprint. SendFile and ReceiveFile automatically terminate the connection after transmission is complete.


ReceiveFile

Sub ReceiveFile (Host As String, Port As Integer, Login As String, Password As String, Source As String, Destination As String)

This function transfer one or more files to the local system. You can specify one or more files to transfer. If you specify a directory, the whole directory will be transferred to the local system recursively with preserving the structure.

If key file is specified, MySCP will try to authorize using this public key. As a passphrase for the key it will use given Password. If authorization with key will fail, it will try to authorize using usual login/password scheme.

ReceiveFile works asynchronously. This means it returns immediately after you called it. The actual file transfer runs in the separate thread. When transfer completed, the corresponding error code is set in the Error property. You can wait until competition of the task with function WaitForComplete of do something useful in your application. You can also check the Status property. When it is set to STATUS_NOTCONNECTED check the Error property and see if the transmission was completed successfully. You can also use events and find if the transmission was successful by analyzing Error property in the OnDisconnect event.


SendFile

Sub SendFile (Host As String, Port As Integer, Login As String, Password As String, Source As String, Destination As String)

This function transfer one or more files to the remote system. You can specify one or more files to transfer. If you specify a directory, the whole directory will be transferred to the remote system recursively with preserving the structure.

If key file is specified, MySCP will try to authorize using this public key. As a passphrase for the key it will use given Password. If authorization with key will fail, it will try to authorize using usual login/password scheme.

SendFile works asynchronously. This means it returns immediately after you called it. The actual file transfer runs in the separate thread. When transfer completed, the corresponding error code is set in the Error property. You can wait until competition of the task with function WaitForComplete of do something useful in your application. You can also check the Status property. When it is set to STATUS_NOTCONNECTED check the Error property and see if the transmission was completed successfully. You can also use events and find if the transmission was successful by analyzing Error property in the OnDisconnect event.


Methods

xp_aes_decrypt

Decrypts data previously encrypted with xp_aes_encrypt function

Syntax

xp_aes_encrypt { encrypted_text , key, variable1 OUTPUT [, variable2 OUTPUT , variable3 OUTPUT ...] }

Arguments

encrypted_text

VARCHAR or VARBINARY. Text previously encrypted with xp_aes_encrypt function.

key

VARCHAR. Key is represented by a string which consists of characters from 0 to 9 and A, B, C, D, E, F so called 'hexadecimal notation'. Valid lengths of string are 32, 48 and 64 chars. Which evolves 128, 192 and 256 bit AES encryption. Example of 32 chars key - '076541A84BEF792A1234567890D98769'

variable1 OUTPUT [, variable2 OUTPUT , variable3 OUTPUT ...]

Variables to hold the decrypted information. The order of the variables should be the same like the order of variables given to the encryption function.

Remark

If you specify the wrong password decryption will succeed but clear_text will probably hold some garbage. You can not find out if the password was wrong or correct.

Permissions

Execute permissions default to the public role.

Return Code Values

0 - success, or Error code if failed.

Example
declare @encrypted varchar (8000)
declare @return_code int

exec xp_aes_encrypt 'test','0123456789ABCDEF0123456789ABCDEF',@encrypted output
exec @return_code = xp_aes_decrypt @a,'0123456789ABCDEF0123456789ABCDEF',@encrypted output
if @return_code != 0
begin
raiserror ('AES encryption failed!',16,10)
end


Properties

xp_aes_decrypt

Decrypts data previously encrypted with xp_aes_encrypt function

Syntax

xp_aes_encrypt { encrypted_text , key, variable1 OUTPUT [, variable2 OUTPUT , variable3 OUTPUT ...] }

Arguments

encrypted_text

VARCHAR or VARBINARY. Text previously encrypted with xp_aes_encrypt function.

key

VARCHAR. Key is represented by a string which consists of characters from 0 to 9 and A, B, C, D, E, F so called 'hexadecimal notation'. Valid lengths of string are 32, 48 and 64 chars. Which evolves 128, 192 and 256 bit AES encryption. Example of 32 chars key - '076541A84BEF792A1234567890D98769'

variable1 OUTPUT [, variable2 OUTPUT , variable3 OUTPUT ...]

Variables to hold the decrypted information. The order of the variables should be the same like the order of variables given to the encryption function.

Remark

If you specify the wrong password decryption will succeed but clear_text will probably hold some garbage. You can not find out if the password was wrong or correct.

Permissions

Execute permissions default to the public role.

Return Code Values

0 - success, or Error code if failed.

Example
declare @encrypted varchar (8000)
declare @return_code int

exec xp_aes_encrypt 'test','0123456789ABCDEF0123456789ABCDEF',@encrypted output
exec @return_code = xp_aes_decrypt @a,'0123456789ABCDEF0123456789ABCDEF',@encrypted output
if @return_code != 0
begin
raiserror ('AES encryption failed!',16,10)
end