oid-info.com API for PHP

24 November 2021

Introduction

oid-info.com is a public repository for Object Identifiers (OIDs). This API is available in PHP and can be used in web-interfaces (Apache module, cgi-bin, etc.) but can also be used in command line tools written in PHP (on Linux with shebang #!/usr/bin/php) .

The majority of the functions provided by this API helps developers in creating XML files which can be uploaded to the OID repository to add multiple OIDs, but the API also contains other helpful utilities related to OIDs, UUIDs and the OID repository in general. The XML generation can be useful for Registration Authorities (RAs) that want to deliver their assignments to oid-info.com , but also for people who want to support the OID repository by adding OIDs from public sources. The XML files generated by these API functions are conform with the XML schema of oid-info.com and can be uploaded here - you will also find more information about the XML submission at these pages.

An example of a XML generation code can be found here: oidinfo_example.phps

The API is licensed under the terms of the Apache 2.0 License and was written by Daniel Marschall.

Download

Download the current version of the API here / Browse SVN repository

Browse the source code online:

Table of Contents

Class OIDInfoAPI

Note: Not every throwable Exception (they are all of type OIDInfoException) is described in the method descriptions.

Part 1: "Ping API" / "Verbose Ping Provider" for checking if OIDs are available or allowed to create

Online check functions

Note: These 4 functions include the strictCheckSyntax() check (see Part 2: Syntax checking).

public function checkOnlineExists($oid)

An online check will be performed, to check if $oid exists. "Exist" means, the OID was added to the repository. Exist does not mean that the OID is also validated by the OID repository admin (i.e. available through the web interface).

You can use the function oidExisting which uses the online-check (verbose ping provider) and the simple-ping-provider, if available, in combination.

public function checkOnlineAvailable($oid)

An online check will be performed, to check if $oid is available. "Available" means, the OID was added to the repository and is validated by the OID repository admin.

public function checkOnlineAllowed($oid)

An online check will be performed, to check if $oid is allowed. "Allowed" means, that the OID repository allows the creation of this OID. This is the case for OIDs which are not created in a frozen or leaf arc of the OID tree and are not known as illegal.

Attention! "Allowed" will also be true if the OID already exists in the OID repository.

Attention! Before using this function, you should verify that $oid is not listed in the local blacklist (please see Part 4: Offline check if OIDs are illegal), by using illegalOID($oid), because this low level function does not include this check by design.

public function checkOnlineMayCreate($oid)

An online check will be performed, to check if $oid may be created. This means that the OID is allowed (checkOnlineAllowed) and does not exist (!checkOnlineExists).

Attention! Before using this function, you should verify that $oid is not listed in the local blacklist (please see Part 4: Offline check if OIDs are illegal), by using illegalOID($oid), because this low level function does not include this check by design. It is recommended to use oidMayCreate() instead.

Caching

pingCacheMaxAge = 3600

The results of checkOnlineExists, checkOnlineAvailable, checkOnlineAllowed and checkOnlineMayCreate are cached to reduce the amount of web traffic, which also increases the performance. The variable pingCacheMaxAge contains the maxiumum amount of seconds before the cache entry will be renewed. The cache will be automatically cleared if the function clearPingCache is called, or if the PHP script session terminates.

The default value is 3600 seconds, which is 1 hour. If you are using the OIDInfo-API in a long-term process (e.g. a daemon or crawler service), you should probably modify the pingCacheMaxAge setting.

If you want to make sure that the cache is never used, please set pingCacheMaxAge = -1. Please note, that the cache is still maintained (extended and updated).

If you do not want that the cache entries expire, you can use the PHP constant INF: pingCacheMaxAge = INF.

public function clearPingCache()

This function clears the ping cache. This will also reduce the amount of currently used memory.

Configuration of the verbose ping provider

The "Verbose Ping Provider" is a HTTP(S) webservice which tells wheather an OID exists at oid-info.com, and if it may be created.

The webservice must return following content:

         First digit of the ping result
         "-" = error
         "0" = OID does not exist
         "1" = OID does exist, but is not approved yet
         "2" = OID does exist and is accessible

         Second digit of the ping result
         "-" = error
         "0" = The OID may not be created
         "1" = OID is not an illegal OID, and none of its ascendant is a leaf and its parent OID is not frozen

$verbosePingProviders = array('https://misc.daniel-marschall.de/oid-repository/ping_oid.php?oid={OID}');

The URL(s) of the verbose ping provider(s). The string {OID} will be replaced by the OID in dot-notation. Usually, you do not need to edit this configuration.

Part 2: Syntax checking

public static function strictCheckSyntax($oid)

Returns true, if the $oid has the correct syntax for usage in the XML files for the OID repository. This means:

public static function trySanitizeOID($oid)

Tries to repair $oid to make it comply with strictCheckSyntax. A leading dot as well as leading zeros will be removed. If the OID is still invalid, the function will return false, otherwise the sanitized OID as string.

Part 3: XML file creation

public function softCorrectEMail($email, $params)

This function tries to correct an invalid eMail address (probably obfuscated for anti spam purposes), e.g. "john[at]example[dot]com" will be corrected into "john@example.com" .

If $params['allow_illegal_email'] is true, and the email address is still invalid, an empty string will be returned.

Otherwise, the function will return the email address which was fully, partially or not corrected.

Attention! You don't need to use this function if you create an XML file using createXMLEntry, since this step will be done automatically.

public function softCorrectPhone($phone, $params)

This function tries to corrects a phone number and remove invalid characters, like dashes or brackets.

Attention! You don't need to use this function if you create an XML file using createXMLEntry, since this step will be done automatically.

public function correctDesc($desc, $params, $ending_dot_policy=OIDInfoAPI::OIDINFO_CORRECT_DESC_OPTIONAL_ENDING_DOT, $enforce_xhtml_light=false)

This function tries to change the description to make it comply with the XML file.

If $params['allow_html'] is true, HTML tags will be allowed, otherwise they will be encoded.

If $params['tolerant_htmlentities'] is true, double encoded HTML entities like & will be corrected.

Also, this function will remove unnecessary phrasings like "OID for " at the beginning or ending of the description.

Following constants are valid values for $ending_dot_policy:

If $enforce_xhtml_light is set to true, then tags which are not included in the XHTML Light specification are removed, except if $params['ignore_xhtml_light'] is true.

Attention! You don't need to use this function if you create an XML file using createXMLEntry, since this step will be done automatically.

public function xmlAddHeader($firstName, $lastName, $email)

Outputs the beginning of a XML file which can be created and submitted to oid-info.com

public function xmlAddFooter()

Returns the footer of the XML file.

public function createXMLEntry($oid, $elements, $params, $comment='')

Returns a <oid> entry for the XML file, with an optional comment $comment above the entry.

Valid values of $elements and $params will be explained in the following sections.

Valid values for $params

$params['allow_html']

Allows HTML in <description> and <information>

Default: false

$params['allow_illegal_email']

Does not delete email addresses which could not be repaired with softCorrectEMail.

This should stay enabled, because we don't know if the source used some kind of human-readable anti-spam technique instead of an actual wrong address.

Default: true

$params['soft_correct_behavior']

This defines the way ASN.1 identifiers ($elements['synonymous-identifier']) will be corrected in case they are illegal. Following modes are available:

Default: OIDInfoAPI::SOFT_CORRECT_BEHAVIOR_NONE

$params['do_online_check']

Flag to disable this online check (checkOnlineMayCreate($oid)) to save traffic and runtime.

Default: false

$params['do_illegality_check']

Checks if the OID is illegal (illegalOID($oid)) before adding it to the XML

Default: true

$params['do_simpleping_check']

When a simple ping provider defined, the XML entry will not be added when one of the simple ping providers reports the OID as existing.

Default: true

$params['auto_extract_name']

If this is set, the <information> field will end with "Automatically extracted from ..."

Default: ''

$params['auto_extract_url']

If this is set, the <information> field will end with "Automatically extracted from ..."

Default: ''

$params['always_output_comment']

Also output comment if there was an error (e.g. OID already existing)

Default: false

$params['ignore_xhtml_light']

If set to true, tags which are not allowed in the XHTML Light specification won't be excluded (fields: address, description and information).

Valid values for $elements

$elements['synonymous-identifier'] = ''; // string or array
$elements['description'] = '';
$elements['information'] = '';

$elements['first-registrant']['first-name'] = '';
$elements['first-registrant']['last-name'] = '';
$elements['first-registrant']['address'] = '';
$elements['first-registrant']['email'] = '';
$elements['first-registrant']['phone'] = '';
$elements['first-registrant']['fax'] = '';
$elements['first-registrant']['creation-date'] = '';

$elements['current-registrant']['first-name'] = '';
$elements['current-registrant']['last-name'] = '';
$elements['current-registrant']['address'] = '';
$elements['current-registrant']['email'] = '';
$elements['current-registrant']['phone'] = '';
$elements['current-registrant']['fax'] = '';
$elements['current-registrant']['modification-date'] = '';

Part 4: Offline check if OIDs are illegal

With these functions, you can query if OIDs are listed in a blacklist, which is stored locally. The download package contains a default illegality rule file which contains known illegal OID arcs.

public function clearIllegalityRules()

Clears all illegality rules (please see below).

public function loadIllegalityRuleFile($file)

Loads a file which contains illegality rules (please see below).

public function addIllegalityRule($rule)

Adds an illegality rule (please see below).

public function illegalOID($oid, &$illegal_root='')

Returns true, if $oid is marked as illegal OID according to the illegality rules.

$illegal_root will contain the illegal beginning of the OID.

Example: If 2.999.1 would be marked as illegal, and if $oid is 2.999.1.55, then $illegal_root will be 2.999.1

Illegality rules

Illegality rules define arcs or OIDs which are considered as illegal.

An illegality rule file has following syntax:

[1.3.6.1.4.1.37476.3.1.5.1]

-- comment
rule --comment
rule
rule

where 1.3.6.1.4.1.37476.3.1.5.1 is the file format definition, and rule is an illegality rule (which can also be manually defined via addIllegalityRule($rule)) with following syntax:

2.999.(11-).0 : the arc values 11 and below are illegal

2.999.(11+).0 : the arc values 11 and above are illegal

2.999.(1-5).0 : the arc values 1 to 5 are illegal

2.999.*.0 : * is equal to (0+)

Part 5: Misc functions

function __construct()

When the class is created and a file with the name "oid_illegality_rules" exist, this file will be processed with loadIllegalityRuleFile.

public static function getPublicURL($oid)

Returns the public URL to the OID registry, pointing to the information about $oid.

public function oidExisting($oid, $onlineCheck=true, $useSimplePingProvider=true)

Returns true if $oid is existing.

If $useSimplePingProvider is true, the simple ping provider will be checked first.

If the OID does not exist in the cache, or if no simple ping provider is loaded, or if $useSimplePingProvider is false, then an online check (checkOnlineExists) will be done if $onlineCheck is true.

An Exception of type OIDInfoException will be thrown, if none of the both checks could be performed (e.g. no simple ping provider is defined and online check disabled).

An Exception of type OIDInfoException will be thrown in case that $oid cannot be repaired with trySanitizeOID($oid)

public function oidMayCreate($oid, $onlineCheck=true, $useSimplePingProvider=true, $illegalityCheck=true)

Returns true if $oid may be created.

If $illegalityCheck is true and illegalOID($oid) results is true, then the function will immediately result in false.

If $useSimplePingProvider is true, the simple ping provider will be checked first if the OID is already existing (which would result in false).

If the OID does not exist in the cache, or if no simple ping provider is loaded, or if $useSimplePingProvider is false, then an online check (checkOnlineMayCreate) will be done if $onlineCheck is true.

An Exception of type OIDInfoException will be thrown, if none of the both checks could be performed (e.g. no simple ping provider defined and online check disabled).

An Exception of type OIDInfoException will be thrown in case that $oid cannot be repaired with trySanitizeOID($oid)

Part 6: Simple Ping Providers

Following table shows the differnce between the Simple Ping Providers and the Verbose Ping Providers.

Simple Ping Provider (Part 6) Verbose Ping Provider (Part 1)
Uses Telnet protocol (usually port 49500) Uses HTTP(s) protocol
Multiple queries per session/connection Only 1 query per session (HTTP(s) request)
Multiple simple ping providers can be defined and hosted anywhere Only the official ViaThinkSoft service can be used
Can provide any OID tree (e.g. your own RA's OIDs) Provides information on all OIDs in oid-info.com
Only provides information if the OID exists at the given local database. Provides information if the OID exists at oid-info.com, and if it may be created. Additionally, the information provided will make clear if the OID is active (i.e. activated by the verified by the administrator after submitting).
Very fast, especially if the service is located at the local host. Rather slow
Usual scenario: You have an OID tree of your RA, and want to quickly check if a given OID is in that tree. Usual scenario: You want to check if you may create an OID at oid-info.com, or if it is available there. 
public function addSimplePingProvider($addr)

Adds a simple ping provider.

Possibility 1 (OIDSimplePingProvider): $addr is a hostname without protocol specification. The port is optional. If no port is specified, the port 49500 will be used. The connection will be only built up while the first query is sent!

Possibility 2 (CSVSimplePingProvider):: $addr is a filename of a CSV file. A "virtual" simple ping provider will be created. The CSV will be read immediately, and will be re-read in every query, after the modification timestamp had changed.

public function removeSimplePingProvider($addr)

Removed a simple ping provider.

public function removeAllSimplePingProviders()

Removes all simple ping providers.

public function listSimplePingProviders()

List all simple ping providers.

public function simplePingProviderCheckOID($oid)

Checks if an OID is existing.

The result is true when one of the providers returns "1".

The result is false if all providers returned "0".

The result is null no providers returned "1", and at least one provider failed to connect or returned something unexpected.

Throws an Exception of type OIDInfoException, if no providers are in the list.

public function simplePingProviderAvailable()

Returns true, if at least one ping provider is added to the list.