How to write an EPP client in C#

Extensible Provisioning Protocol(EPP), defined in RFC 5730 is a protocol which is used in the Internet industry for the provisioning of domain names, hosting and related contact details. It is currently not used for much otherwise. It is rare to have to write software to consume an EPP-based webservice, so when I came to do so, I could find little to no examples written for the .NET framework. So I’ll post what I have found here.

The basics are as follows. Messages are sent and received in XML, and generally over TCP or similar transport protocols. All communications must be secured. Details of the message structures can be found at the above link.


Another important point is that generally, the messages sent and received from EPP services consist of the length as a network order (big-endian) 32-bit number, followed by the actual request. It is necessary to strip this of in your responses before handling the XML.

The following method will send an XML Document, here in the form of any implementation of XContainer (e.g. XDocument, or XElement), to the specified endpoint over a secure TCP connection. The namespace needs to be specified, and will be "urn:ietf:params:xml:ns:epp-1.0". This will also take care of wrapping your xml within an ‘epp’ root element, as is a requirement of the standard, so it’s only necessary to provide the core XML needed for the command you wish to send. For the initial greeting this is as simple as <hello />

public XDocument APIRequest(XContainer[] requestData, Uri _endpoint, string _xmlns)
{
	XDocument XResponse;

	using(var _tcpClient = new TcpClient(_endpoint.Host, _endpoint.Port))
	{

		using (var sslStream = new SslStream(_tcpClient.GetStream(), false, ValidateServerCertificate))
		{
			sslStream.AuthenticateAsClient(_endpoint.Host);

			using (XmlWriter xw = XmlWriter.Create(sslStream))
			{
				new XDocument(
					new XElement(_xmlns + "epp",
						requestData
					)
				).WriteTo(xw);
			}
	
			sslStream.Flush();

			var response = ReadMessage(sslStream);
			XResponse = XDocument.Parse(response);
		}
	}
	return XResponse;
}

The above method depends on two important methods. ReadMessage and ValidateServerCertificate. ReadMessage decodes the received SSL stream from the service, strips off the length marker, and returns the message as a clean string. ValidateServerCertificate is a requirement of the SSL stream, and it should be used to confirm the secure credentials. It is possible to simply return true from this method, and the connection will be allowed. This is stupid, but would be required if connecting to a server with an expired certificate. The methods are as follows.

private string ReadMessage(SslStream sslStream)
{
	// The first four bytes will be the the content length as a network order (big-endian) 32-bit number.
	var lengthBytes = new byte[4];
	sslStream.Read(lengthBytes, 0, 4);
	Array.Reverse(lengthBytes);

	var length = BitConverter.ToInt32(lengthBytes, 0) - 4;

	// Create a byte array of the correct size for the response.
	var messageBytes = new byte[length];

	var returned = 0;

	while (returned != length)
	{
		returned += sslStream.Read(messageBytes, 0, length);
	}

	return Encoding.UTF8.GetString(messageBytes);
}

// The following method is invoked by the RemoteCertificateValidationDelegate. 
private bool ValidateServerCertificate(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors)
{
	if (sslPolicyErrors == SslPolicyErrors.None)
		return true;

	Console.WriteLine("Certificate error: {0}", sslPolicyErrors);

	// Do not allow this client to communicate with unauthenticated servers. 
	return false;
}

These methods require the following using statements.

using System;
using System.Net.Security;
using System.Net.Sockets;
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Xml;
using System.Xml.Linq;

5 thoughts on “How to write an EPP client in C#

Add yours

  1. Thank you very much. You have no idea what I’ve been through these couple of days, confused, disoriented, frustrated and all are gone because of your excellent article.

    If I may, the string _xmlns didn’t work for me I changed the data type to XNamespace.

    Thank you again man.

  2. hello …
    can you explain me in more detail how i can do EPP in c# (connecting to registry , login create contacte…..)
    thank you for help

  3. Did you complete the project? I have to work for a project same like this and I looking for something already worked. Please contact me, thanks.

  4. For those enquiring about a working EPP client, I have a working proprietary library which I’m unable to share due to commercial restrictions. However I’m happy to answer any specific technical queries.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a website or blog at WordPress.com

Up ↑

%d bloggers like this: