Guidance

Set up the Secure Data Exchange Service (SDES) automated transfer

Find out how to set up the automated connection option in SDES and transfer your data to and from HMRC.

Once you’ve registered for SDES, you can use this guide to set up and use the automated transfer connection, allowing you transfer your data to and from HMRC automatically.

You can also use SDES to send your data using your web browser.

Before you start

To use the automated transfer connection, you’ll need:

  • the 12-digit service reference number (SRN) you got when you registered for SDES
  • access to the internet
  • a specific username and password on your Government Gateway account dedicated to your software - you can create this using the Manage Users option on the Government Gateway website
  • a specific static Internet Protocol (IP) address range from which your software will connect to HMRC

You’ll also need software which:

  • can transfer files using File Transfer Protocol Secure (FTPS)
  • supports Transport Layer Security (TLS) 1.2 encrypted connection
  • supports one-way authentication

Set up the automated connection

You must first email the SDES support team with your 12-digit SRN and your static IP range. This can be shown as a:

  • wildcard – for example, 192.153.2.*
  • subnet – for example, 192.153.2.0/8
  • range – for example, 192.153.2.110 to 192.153.2.160

Once your IP range has been added, you’ll get a reply from the SDES support team letting you know you can try the connection.

Using the automated transfer

You must enable a connection through your selected FTPS software to one of the following IP addresses:

  • 163.171.0.121
  • 163.171.8.121

You must also connect through the following port numbers:

  • control: 21
  • data: 50,000 to 50,020

SDES requires one-way authentication, and provides a HMRC certificate so you can confirm you’ve connected to the right party. Once authenticated, a TLS connection is established between your FTPS software and the SDES server.

Once the connection is successful, you must issue the following commands on the control channel to complete authentication:

  • USER (containing the Government Gateway user ID created for the FTPS software)
  • PASS (containing Government Gateway password created for the FTPS software)
  • ACCT (containing the name of the service HMRC-SDES, followed by a semi-colon then your unique SRN – for example, ‘HMRC-SDES;012345678901’)

Once authenticated, you can use the FTP commands in the next section to upload or download a file through SDES.

Uploading a file to HMRC - FTP command sequence

Sequence FTP command Success return code Additional error return codes
1 AUTH TLS 234 Command okay  
2 PBSZ 0 200 Command okay  
3 PROT P 200 Command okay  
4 USER 331 User name okay, need password  
5 PASS 332 Need account for login  
6 ACCT 230 User logged in, proceed  
7 STRU F 200 Command okay  
8 TYPE I 200 Command okay  
9 MODE S 200 Command okay  
10 PASV 227 Entering Passive Mode
(h1,h2,h3,h4,p1,p2)
 
11 STOR (filename) Before starting the transfer:
125 Data connection already open; transfer starting.

On completion of the transfer:
250 Requested file action okay, completed.

If the client sends an ABOR before receipt of the 250 and the connection is aborted:
426 Connection closed; transfer aborted, 226 ABOR command successful.
If an unhandled exception occurs when storing the file:
550 Requested action not taken

If the connection fails between the client or server:
426 Connection closed; transfer aborted.

If the file is in use and can’t be written to:
450 Requested file action not taken. File unavailable.
12 QUIT 221 Service closing control connection.  

Downloading a file from HMRCFTP command sequence

Sequence FTP command Success return code Additional error return codes
1 AUTH TLS 234 Command okay  
2 PBSZ 0 200 Command okay  
3 PROT P 200 Command okay  
4 USER 331 User name okay, need password  
5 PASS 332 Need account for login  
6 ACCT 230 User logged in, proceed  
7 STRU F 200 Command okay  
8 TYPE I 200 Command okay  
9 MODE S 200 Command okay  
10 PASV 227 Entering Passive Mode
(h1,h2,h3,h4,p1,p2)
 
11 RETR (filename) Before starting the transfer:
125 Data connection already open; transfer starting.

On completion of the transfer:
250 Requested file action okay, completed.

If the client sends an ABOR before receipt of the 250 and the connection is aborted:
426 Connection closed; transfer aborted, 226 ABOR command successful.
If an unhandled exception occurs when storing the file:
550 Requested action not taken

If the connection fails between the client or server:
426 Connection closed; transfer aborted.

If the file is in use and can’t be written to:
450 Requested file action not taken. File unavailable.
12 QUIT 221 Service closing control connection.  

FTP commands and transfer parameters

This section includes all commands that are supported, partially supported and not supported on SDES.

Supported FTP commands

These FTP commands are supported by SDES.

FTP command Mandatory upload Mandatory download Supported parameters Unsupported parameters Notes
ABOR No No     Used to abort the previous FTP service command.
ACCT Yes Yes <servicename>[;<enrol id>]   The account parameter provides the service name and, in the case of the service owner, it also provides an enrol ID.
AUTH Yes Yes     Used to specify the security extensions. As all connections must be started using a secure channel, this command is redundant.
NOOP No No     This command doesn’t affect any parameters or previously entered commands. It specifies no action other than that the server will send an OK reply.
PASS Yes Yes <password>   The command that provides the password.
PBSZ Yes Yes     Specifies the protection buffer size. For FTP-TLS, which appears to the FTP application as a streaming protection mechanism, this isn’t required. The PBSZ command must still be issued, but must have a parameter of ‘0’ to indicate that no buffering is taking place and the data connection should not be encapsulated.
PROT Yes Yes P C, S and E Specifies the channel’s protection mode and whether they’re clear or encrypted.
QUIT Yes Yes     Used to close the FTP session.
RETR No Yes <filename>   Used to download a file.
SIZE No No <filename>   Provides the size of the file that has been uploaded.
STOR Yes No <filename>   Used to upload a file.
USER Yes Yes <username>   Provides the user name.

Unsupported FTP Commands

These FTP access and control commands are not supported by SDES.

FTP Command Notes
ADAT Provides the security data as a follow up to a successful AUTH command. As that command is redundant, this command is also redundant.
ALLO Allocates storage space in the server.
APPE Used to append to an existing file. If the file doesn’t exist, then a new file is created in its place.
CCC Clear Command Channel - makes a secured control/command channel revert back to plaintext (un-secured) mode.
CDUP Changes the current directory to the parent directory.
CONF Confidentiality protection command.
CWD Changes the working directory.
DELE Used to delete a file.
ENC This is the Privacy Protected Channel command.
HELP Provides help on the commands from the server.
LIST Used to list the directory contents.
MIC This is the Integrity Protected command.
MKD Used to make a directory.
NLST Causes a directory listing to be sent from a server to a user site.
PWD Prints the current working directory.
REST Provides the restart marker. Files being uploaded following this command will be appended from the marker onwards. Files being downloaded will start from the marker.
RNFR Renames the file.
RNTO Renames the file.
RWD Removes a directory.
REIN Re-initialises the connection.
STAT Provides the status information.
SITE Used by the server to provide services specific to this system that are essential to file transfer, but not sufficiently universal to be included as commands in the protocol.
SMNT Mounts a file structure.
STOU Used to find out the type of operating system at the server.

Supported FTP transfer parameter

This FTP transfer parameter command is fully supported by SDES.

FTP command Mandatory upload Mandatory download Supported parameters Unsupported parameters Notes
PASV Yes Yes     The command that tells the FTP server to do data transfer in FTP passive mode

Partially supported FTP transfer parameters

These FTP transfer parameter commands are partially supported by SDES.

FTP command Mandatory upload Mandatory download Supported parameters Unsupported parameters Notes
MODE Yes Yes S B and C The transfer mode must indicate that the transfer type is stream. Block and compressed mode are specifically not supported.
STRU Yes Yes F R and P The structure command must always indicate that the data being transferred is a file.
TYPE Yes Yes I A, E, and L Only the image representational type of data transfer is supported.

Unsupported FTP transfer parameter

This FTP transfer parameter command is not supported by SDES.

FTP command Mandatory upload Mandatory download Supported parameters Unsupported parameters Notes
PORT No No     This command is used to support Active Mode in FTP.

FTP error codes

You may receive these error codes when using SDES.

Error code Description
502 Command not implemented Any command that’s not supported by the server, for example, LIST.
504 Command not implemented for that parameter Any command where there’s an unsupported parameter. For example, MODE C.
501 Syntax error in parameters or arguments Any command where there’s an incorrect syntax. For example, REST filename.ext.
530 Not logged in When a command is specified before logging in.

When the PASS command is not provided after the USER command.

When the ACCT command is not provided after the PASS command.
503 Bad sequence of commands When the STOR or RETR command is provided before the MODE, TYPE, STRU and PASV commands.
Requested action aborted. Local error in processing. For unhandled exceptions when processing commands.

Invalid file types

SDES can be used to transfer any file formats up to 10 gigabytes (GB) in size, apart from executable (.exe) and encrypted files, which will be automatically rejected. You can’t upload files with a filename containing:

  • angle brackets ( < or > )
  • quotation marks ( “ )
  • question marks ( ? )
  • vertical lines ( | )
  • colons ( : )
  • asterisks ( * )
  • forward or back slashes ( / or \ )

SDES notifications

SDES currently only supports email notifications. System notifications through an API will be made available in early 2018.

Email notifications are sent to the user email address provided through the browser interface for SDES from noreply@sdes.hmrc.gov.uk

You may receive the following emails from the SDES service, depending on whether you’re downloading from or uploading to HMRC.

Downloading from HMRC

Email subject Email content Description
Download [filename] You have a new file to download from HMRC. It’s called [filename].

If you have any questions, email MDTSSETCustomerManagement@hmrc.gsi.gov.uk or call 03000 597 222.

Secure Data Exchange Service.
This is triggered per individual file when it becomes available for download in SDES.
We’ll delete [filename] in [#] hours You still need to download [filename]. We’re going to delete it in the next [#] hours.

If you have any questions email MDTSSETCustomerManagement@hmrc.gsi.gov.uk or call 03000 597 222.

Secure Data Exchange Service.
Warning emails in advance of automatic deletion after a 6 day holding period.

Emails are triggered 48, 24 and 12 hours in advance.
We’ve deleted [filename] We’ve deleted [filename].

If you want us to send it again, contact the HMRC department you’ve been dealing with. If you have problems with this call 03000 597 222 or email MDTSSETCustomerManagement@hmrc.gsi.gov.uk.

Secure Data Exchange Service.
A file is deleted after the 6 day holding period for security and is no longer available for download.

Uploading to HMRC

Email subject Email content Description
[Filename] failed our virus scan Your document [filename] failed our virus scan.

If you want to send it again, try checking it with your IT department and make sure you’re using anti-virus software.

If you have any questions email MDTSSETCustomerManagement@hmrc.gsi.gov.uk or call 03000 597 222.

Secure Data Exchange Service.
A virus was detected in the uploaded file and automatically deleted for security.
We’ve delivered [filename] We’ve successfully virus checked and delivered [filename].

Another HMRC department will now check your documents and contact you if necessary.

If you have any questions email MDTSSETCustomerManagement@hmrc.gsi.gov.uk or call 03000 597 222.

Secure Data Exchange Service.
The uploaded file has been successfully delivered to the intended HMRC recipient. Delivery doesn’t validate that the content of the file is acceptable.
Please resend [filename] There was a problem with our service and we deleted [filename]. Please upload your document again.

If you have any questions email MDTSSETCustomerManagement@hmrc.gsi.gov.uk or call 03000 597 222.

Secure Data Exchange Service.
Due to a technical or security error, SDES has deleted all uploaded files and requires the user to re-upload the specific file.

Security and auditing

Security is provided at various stages to ensure that only authenticated users can access the automated function of SDES. For example:

  • only existing SDES users who have created a Government Gateway account, enrolled and have obtained a SRN are allowed
  • only connections made from a previously approved IP address are permitted
  • all connections are authenticated using Government Gateway credentials to ensure that HMRC can identify the connecting organisation
  • HMRC provides a certificate to allow the connecting organisation to verify they’re connecting to the correct address
  • a secure TLS 1.2 encrypted connection must be completed before any transfers may take place - connections which don’t meet this standard are rejected

Once files are successfully delivered through SDES, they’re always encrypted during transit or at rest. There’s no direct access to any files within SDES, meaning that even HMRC technical support teams can’t access files.

Auditing information

For security purposes, SDES records all interactions, file movements and system activities. This includes:

  • users logging into the service
  • any actions taken via browser or automated connections
  • any activities, such as virus checks

This enables SDES to have full traceability for security purposes, and to also quickly identify and resolve any issues.

Test file uploads and downloads

SDES has a test option where a ‘proving file’ can either be sent by a user to HMRC, or sent from HMRC to the user.

This is a specifically named file that doesn’t interfere with HMRC systems, but allows upload and download capabilities to be verified.

To run the proving file test, you must contact the SDES support team.

Published 1 June 2018