14 November 2015
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 GNU Lesser General Public License Version 3 (GNU LGPL 3.0) and was written by Daniel Marschall.
Download the current version of the API here
Browse the source code online:
OIDInfoAPI
Note: Not every throwable Exception (they are all of type OIDInfoException
) is described in the method descriptions.
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 and the CSV check, 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.
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.
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.
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)
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.
Also, this function will remove unnecessary phrasings like "OID for " at the beginning or ending of the description.
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.
$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:
OIDInfoAPI::SOFT_CORRECT_BEHAVIOR_NONE
: The illegal identifier will be deleted.
OIDInfoAPI::SOFT_CORRECT_BEHAVIOR_LOWERCASE_BEGINNING
: The beginning will be enforced to be lowercase.
OIDInfoAPI::SOFT_CORRECT_BEHAVIOR_ALL_POSSIBLE
: All invalid characters will be removed, and the beginning will be enforced to be lowercase.
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_csv_check']
If the CSV storage is loaded, the XML entry will only be added if the OID does not exist in the CSV file
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
$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'] = '';
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 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+)
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, $useCache=true)
Returns true
if $oid
is existing.
If $useCache
is true
, the CSV cache will be checked first.
If the OID does not exist in the cache, or if the CSV storage is not loaded, or if $useCache
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. CSV cache not loaded 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, $useCache=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 $useCache
is true
, the CSV cache 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 the CSV storage is not loaded, or if $useCache
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. CSV cache not loaded and online check disabled).
An Exception of type OIDInfoException
will be thrown in case that $oid
cannot be repaired with trySanitizeOID($oid)