you with all the SRS commands, suggest development strategies and provide
assistance with using GnuPG, which is used by all SRS clients to handle digital
signatures. The concepts discussed in this document are common to all SRS client
implementations, regardless of API choice.
3. Choosing an API
Your choice of API may be entirely dependent on your infrastructure (i.e., the
operating system of your web server). If you need to choose between APIs, though,
this section is designed to help by describing how each API is implemented. You may
want to skip this section if you are already committed to a particular API. Note that
each API has a corresponding Reference Guide that details installation and
configuration procedures specific to it.
3.1 Common Elements
As discussed in the Technical Overview, an SRS client must perform the following
1. Create outgoing command packets and parse incoming response packets
according to the SRS protocol specification
2. Digitally sign outgoing packets and verify the signature of incoming packets
3. Provide for SSL encrypted HTTP communication
Beyond platform and language considerations, how each API accomplishes these
tasks is the main differentiating factor.
One component common to all APIs is the use of GnuPG for the handling of digital
signatures. Regardless of API, a GnuPG installation is required on your target
platform. A later section in this document presents an overview of GnuPG usage as it
relates to your SRS client.
3.4 SRS Component for Windows
The SRS Component for Windows is a dual-interface COM component, which makes
it ideal for use in a multitude of Windows development environments, including ASP.
In fact, it was developed with ASP in mind as its target environment. The component
can be accessed easily from scripting languages, Visual Basic, Visual C++ and any
other environment that supports Automation or raw COM interfaces.
The entire component is housed in a single DLL, SRSplus.dll. It exposes a single
interface, ISrs, which provides access to all of the SRS commands. All configuration
information for the component is stored in the registry. As with the other APIs, the
SRS component uses GnuPG for its digital signature handling. In addition, it requires
WinSock 2.0 and the CryptoAPI with SecureChannel for performing secure HTTP. It
also requires the Windows Scripting Runtime for access to the [url removed, login to view]
object, which the component uses to exchange data with its clients. Except for
GnuPG, all of these technologies are typically installed automatically by later versions
of windows (e.g., Windows 2000 and above) and are readily available from Microsoft
for most Windows versions.
From a development perspective, all the client code must do is instantiate and
initialize an ISrs object, invoke ISrs methods with appropriate parameters, process
the results (usually returned in a [url removed, login to view] object), then uninitialize
and destroy the object.
• Use for all Windows development, especially ASP pages.
• Dependent on GnuPG
• Dependent on WinSock 2.0, CryptoAPI with SecureChannel, and the Windows
4. SRS Command Reference
This section details each SRS command and its usage. Though each API has specific
requirements for parameter types passed into SRS functions, they all conceptually
use the same two parameter types: string and name-value pair lists. In the Perl
API, these correspond to scalar and associative array types. In the C APIs, they
correspond to char* and NameValueList types. The equivalent type used by the
SRS Component for Windows is the IDictionary interface. Specific function
signatures, return values and code samples are provided in the API Reference
documentation for each of the APIs. In the rest of this section, we will make use of
the conceptual terms string and name-value pair in order to remain API
neutral. You may want to have the specific Reference for the API you will be using on
hand as you read this section.
4.1 Important Considerations
Understanding the information in this section is essential to achieving a successful
implementation. Keep the following in mind as you read about the SRS commands:
NAME-VALUE PAIRS The values in name-value pairs are always strings, even if the
information is numeric in nature. It is the programmer’s responsibility to perform
type conversions on returned data, if necessary. This primarily affects C
The SRS server does not return name-value pairs in any particular order. Your code
should be able to handle any arbitrary ordering of the returned data.
DATES All date values are returned from the SRS server in Unix (Linux) epoch time
format, which is a count of the number of seconds since 1970/01/01 00:00 UTC.
MULTIPLE PARAMETER VALUES Some commands accept or return multiple entries of
the same named value. For example, server information returned from a Whois
command may return more than one name server if multiple name servers are
defined for the domain. In this case, the name part of the name-value pairs will have
a numerical index appended to the name part, separated by a space. For example, if
the domain ‘mydomain’ has two name servers defined, the returned name-value
pairs could look like this:
DNS SERVER NAME 1 “[url removed, login to view]”
DNS SERVER NAME 2 “[url removed, login to view]”
In the documentation, all parameters that exhibit this behavior have the string “1…n”
appended to the parameter name. For example, in the above example, the
documentation would list the parameter as DNS SERVER NAME 1…n.
Commands that modify data in the SRS database allow the client to pass an optional
transaction ID to the SRS server. These IDs are persisted as strings, so you may use
any combination of letters and numbers for the string. If supplied, the ID string will
be added to the SRS server log alongside the transaction. Do not pass a NULL for
the transaction ID, but instead pass “0”, “none” or some other meaningless
Commands that take a transaction ID parameter also return a request ID. It is
generated by the server and is also logged alongside every transaction. These IDs
are useful for offline inquiries if a historical log search must be performed (e.g., in
the case of a disputed transaction). Think of them as receipts or confirmation codes.
If you decide not to send transaction IDs, it is suggested that you log the request
IDs you get back as a safeguard.
ERRORS If a command fails, descriptive error strings will be returned in one or more
namevalue pairs named ERROR 1…n. For example, if required parameters are missing
from the CreateContact input, the command will fail and return multiple error
strings, one for each missing piece of information:
ERROR 1 “Please enter a phone number.”
ERROR 2 “The email address you entered is invalid.”
ERROR 3 “Please select a country.’”
Note that if there is only one error string, that the appended error number is optional
and might not appear. The following is a legal response
ERROR “Please enter a phone number.”
SPECIFYING DOMAIN AND TLD PARAMETERS When specifying DOMAIN and TLD
parameters, periods are allowed only when the domain or tld has multiple levels. For
example, do not submit “.com” as the TLD parameter for a .com tld. Instead, submit
“com” as the tld. On the other hand, it is legal to submit “[url removed, login to view]” since it is a multiple
level tld. Examples:
TLD String Legal?
“[url removed, login to view]” YES
“[url removed, login to view]” YES
For DOMAIN parameters, currently the only legal multiple level domains are in the
.name tld. For domains in the .name tld it is legal to include a period in the DOMAIN
parameter to separate the two domain levels. For example, “[url removed, login to view]”
would be a legal value for the DOMAIN parameter when registering the domain
“[url removed, login to view]”.
REGISTRATION LENGTH Some tlds have a minimum term of registration greater than
one year. As of this writing, the following tlds have a minimum 2 year registration
term: [url removed, login to view], [url removed, login to view], [url removed, login to view], and org.uk. The controlling registries for each
respective tld set forth the minimum registration term policies; you are urged to
verify the current policies with each registry.
IP ADDRESSES Do not hardcode “dotted” IP addresses for the SRSplus servers in
any code or hostfiles. Always prefer the symbolic addresses (i.e., [url removed, login to view] &
[url removed, login to view]) since the actual IP addresses are subject to change.
I will provide you complete code to implement. If you will be able to