Subversion Repositories oidinfo_api

Compare Revisions

Ignore whitespace Rev 22 → Rev 23

/trunk/oid_utils.inc.phps
3,7 → 3,7
/*
* OID-Utilities for PHP
* Copyright 2011-2021 Daniel Marschall, ViaThinkSoft
* Version 2021-05-21
* Version 2021-09-23
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
31,11 → 31,11
* Checks if an OID has a valid dot notation.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-09
* @param string $oid<br />
* @param string $oid<br/>
* An OID in dot notation.
* @param boolean $allow_leading_zeroes<br />
* @param boolean $allow_leading_zeroes<br/>
* true of leading zeroes are allowed or not.
* @param boolean $allow_leading_dot<br />
* @param boolean $allow_leading_dot<br/>
* true of leading dots are allowed or not.
* @return boolean true if the dot notation is valid.
**/
50,9 → 50,9
* Returns a full regular expression to validate an OID in dot-notation
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-09
* @param boolean $allow_leading_zeroes<br />
* @param boolean $allow_leading_zeroes<br/>
* true of leading zeroes are allowed or not.
* @param boolean $allow_leading_dot<br />
* @param boolean $allow_leading_dot<br/>
* true of leading dots are allowed or not.
* @return string The regular expression
**/
69,17 → 69,17
* It can be inserted into regular expressions.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-09
* @param int $min_len<br />
* 0="." and greater will be recognized, but not ""<br />
* 1=".2" and greater will be recognized<br />
* 2=".2.999" and greater will be recognized (default)<br />
* @param int $min_len<br/>
* 0="." and greater will be recognized, but not ""<br/>
* 1=".2" and greater will be recognized<br/>
* 2=".2.999" and greater will be recognized (default)<br/>
* etc.
* @param boolean $allow_leading_zeroes<br />
* true: ".2.0999" will be recognized<br />
* @param boolean $allow_leading_zeroes<br/>
* true: ".2.0999" will be recognized<br/>
* false: ".2.0999" won't be recognized (default)
* @param int $leading_dot_policy<br />
* 0 (OID_DOT_FORBIDDEN): forbidden<br />
* 1 (OID_DOT_OPTIONAL) : optional (default)<br />
* @param int $leading_dot_policy<br/>
* 0 (OID_DOT_FORBIDDEN): forbidden<br/>
* 1 (OID_DOT_OPTIONAL) : optional (default)<br/>
* 2 (OID_DOT_REQUIRED) : enforced
* @return string|false A regular expression which matches OIDs in dot notation
**/
133,22 → 133,22
* Searches all OIDs in $text and outputs them as array.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-09
* @param string $text<br />
* @param string $text<br/>
* The text to be parsed
* @param int $min_len<br />
* 0="." and greater will be recognized, but not ""<br />
* 1=".2" and greater will be recognized<br />
* 2=".2.999" and greater will be recognized (default)<br />
* @param int $min_len<br/>
* 0="." and greater will be recognized, but not ""<br/>
* 1=".2" and greater will be recognized<br/>
* 2=".2.999" and greater will be recognized (default)<br/>
* etc.
* @param boolean $allow_leading_zeroes<br />
* true: ".2.0999" will be recognized<br />
* @param boolean $allow_leading_zeroes<br/>
* true: ".2.0999" will be recognized<br/>
* false: ".2.0999" won't be recognized (default)
* @param int $leading_dot_policy<br />
* 0 (OID_DOT_FORBIDDEN): forbidden<br />
* 1 (OID_DOT_OPTIONAL) : optional (default)<br />
* @param int $leading_dot_policy<br/>
* 0 (OID_DOT_FORBIDDEN): forbidden<br/>
* 1 (OID_DOT_OPTIONAL) : optional (default)<br/>
* 2 (OID_DOT_REQUIRED) : enforced
* @param boolean $requires_whitespace_delimiters<br />
* true: "2.999" will be recognized, as well as " 2.999 " (default)<br />
* @param boolean $requires_whitespace_delimiters<br/>
* true: "2.999" will be recognized, as well as " 2.999 " (default)<br/>
* false: "2.999!" will be reconigzed, as well as "2.999.c" (this might be used in in documentations with templates)
* @return string[] An array of OIDs in dot notation
**/
164,20 → 164,20
* Returns a full regular expression for detecting OIDs in dot notation inside a text.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-09
* @param int $min_len<br />
* 0="." and greater will be recognized, but not ""<br />
* 1=".2" and greater will be recognized<br />
* 2=".2.999" and greater will be recognized (default)<br />
* @param int $min_len<br/>
* 0="." and greater will be recognized, but not ""<br/>
* 1=".2" and greater will be recognized<br/>
* 2=".2.999" and greater will be recognized (default)<br/>
* etc.
* @param boolean $allow_leading_zeroes<br />
* true: ".2.0999" will be recognized<br />
* @param boolean $allow_leading_zeroes<br/>
* true: ".2.0999" will be recognized<br/>
* false: ".2.0999" won't be recognized (default)
* @param int $leading_dot_policy<br />
* 0 (OID_DOT_FORBIDDEN): forbidden<br />
* 1 (OID_DOT_OPTIONAL) : optional (default)<br />
* @param int $leading_dot_policy<br/>
* 0 (OID_DOT_FORBIDDEN): forbidden<br/>
* 1 (OID_DOT_OPTIONAL) : optional (default)<br/>
* 2 (OID_DOT_REQUIRED) : enforced
* @param boolean $requires_whitespace_delimiters<br />
* true: "2.999" will be recognized, as well as " 2.999 " (default)<br />
* @param boolean $requires_whitespace_delimiters<br/>
* true: "2.999" will be recognized, as well as " 2.999 " (default)<br/>
* false: "2.999!" will be reconigzed, as well as "2.999.c" (this might be used in in documentations with templates)
* @return string The regular expression
**/
198,11 → 198,11
}
 
/**
* Returns the parent of an OID in dot notation or the OID itself, if it is the root.<br />
* Returns the parent of an OID in dot notation or the OID itself, if it is the root.<br/>
* Leading dots and leading zeroes are tolerated.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-16
* @param string $oid<br />
* @param string $oid<br/>
* An OID in dot notation.
* @return string|false The parent OID in dot notation.
**/
239,7 → 239,7
* The OID will not be checked for validity!
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-17
* @param string $oid<br />
* @param string $oid<br/>
* An OID in dot notation.
* @return string[] An array with all parent OIDs.
**/
267,10 → 267,10
* Sorts an array containing OIDs in dot notation.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-09
* @param string[] $ary<br />
* An array of OIDs in dot notation.<br />
* @param string[] $ary<br/>
* An array of OIDs in dot notation.<br/>
* This array will be changed by this method.
* @param boolean $output_with_leading_dot<br />
* @param boolean $output_with_leading_dot<br/>
* true: The array will be normalized to OIDs with a leading dot.
* false: The array will be normalized to OIDs without a leading dot. (default)
**/
311,9 → 311,9
* Checks if two OIDs in dot-notation are equal
* @author Daniel Marschall, ViaThinkSoft
* @version 2020-05-27
* @param string $oidA<br />
* @param string $oidA<br/>
* First OID
* @param string $oidB<br />
* @param string $oidB<br/>
* Second OID
* @return boolean|null True if the OIDs are equal, null if one of the OIDs are invalid
**/
331,10 → 331,10
* Removes leading zeroes from an OID in dot notation.
* @author Daniel Marschall, ViaThinkSoft
* @version 2015-08-17
* @param string $oid<br />
* @param string $oid<br/>
* An OID in dot notation.
* @param boolean $leading_dot<br />
* true: The OID is valid, if it contains a leading dot.<br />
* @param boolean $leading_dot<br/>
* true: The OID is valid, if it contains a leading dot.<br/>
* false (default): The OID is valid, if it does not contain a leading dot.
* 'auto: Allow both
* @return string|false The OID without leading dots, or <code>false</code> if the OID is syntactically wrong.
383,7 → 383,7
* This function tolerates leading dots.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-16
* @param string $oid<br />
* @param string $oid<br/>
* An OID in dot notation.
* @return string|false The top arc of the OID or empty string if it is already the root ('.')
**/
412,12 → 412,12
* This function tolerates leading dots and leading zeroes.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-20
* @param string $a<br />
* @param string $a<br/>
* An OID.
* @param string $b<br />
* @param string $b<br/>
* An OID.
* @return int|false false if both OIDs do not have a child-parent or parent-child relation, e.g. oid_distance('2.999.1.2.3', '2.999.4.5') = false, or if one of the OIDs is syntactially invalid<br />
* >0 if $a is more specific than $b , e.g. oid_distance('2.999.1.2', '2.999') = 2<br />
* @return int|false false if both OIDs do not have a child-parent or parent-child relation, e.g. oid_distance('2.999.1.2.3', '2.999.4.5') = false, or if one of the OIDs is syntactially invalid<br/>
* >0 if $a is more specific than $b , e.g. oid_distance('2.999.1.2', '2.999') = 2<br/>
* <0 if $a is more common than $b , e.g. oid_distance('2.999', '2.999.1.2') = -2
**/
function oid_distance($a, $b) {
451,7 → 451,7
* Leading zeroes are tolerated.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-20
* @param string $oid<br />
* @param string $oid<br/>
* An OID.
* @return string|false The OID with a leading dot or false if the OID is syntactially wrong.
**/
468,7 → 468,7
* Leading zeroes are tolerated.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-20
* @param string $oid<br />
* @param string $oid<br/>
* An OID.
* @return string|false The OID without a leading dot or false if the OID is syntactially wrong.
**/
484,7 → 484,7
* Find the common ancestor of two or more OIDs
* @author Daniel Marschall, ViaThinkSoft
* @version 2020-05-27
* @param string[] $oids<br />
* @param string[] $oids<br/>
* An array of multiple OIDs, e.g. 2.999.1 and 2.999.2.3.4
* @return string|false The common ancestor, e.g. 2.999, or false if there is no common ancestor.
**/
601,7 → 601,7
* Checks if an IRI identifier is valid or not.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-17
* @param string $iri<br />
* @param string $iri<br/>
* An OID in OID-IRI notation, e.g. /Example/test
* @return boolean true if the IRI identifier is valid.
**/
672,7 → 672,7
* Tries to shorten/simplify an IRI by applying "long arcs", e.g. /2/999/123 -> /Example/123 .
* @author Daniel Marschall, ViaThinkSoft
* @version 2020-05-22
* @param string $iri<br />
* @param string $iri<br/>
* An OID in OID-IRI notation, e.g. /Example/test
* @return string|false The modified IRI.
**/
714,7 → 714,7
* Checks if an ASN.1 identifier is valid.
* @author Daniel Marschall, ViaThinkSoft
* @version 2020-05-22
* @param string $id<br />
* @param string $id<br/>
* An ASN.1 identifier, e.g. "example". Not "example(99)" or "99" and not a path like "{ 2 999 }"
* Note: Use asn1_path_valid() for validating a whole ASN.1 notation path.
* @return boolean true, if the identifier is valid: It begins with an lowercase letter and contains only 0-9, a-z, A-Z and "-"
733,7 → 733,7
* This function will fail (return false) if there are unresolved symbols, e.g. {iso test} is not valid while { iso 123 } is valid.
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-17
* @param string $asn1<br />
* @param string $asn1<br/>
* An OID in ASN.1 notation.
* @return boolean true if the identifier is valid.
**/
798,14 → 798,14
}
 
/**
* Converts an OID in ASN.1 notation into an OID in dot notation and tries to resolve well-known identifiers.<br />
* e.g. {joint-iso-itu-t(2) example(999) 1 2 3} --> 2.999.1.2.3<br />
* Converts an OID in ASN.1 notation into an OID in dot notation and tries to resolve well-known identifiers.<br/>
* e.g. {joint-iso-itu-t(2) example(999) 1 2 3} --> 2.999.1.2.3<br/>
* e.g. {iso 3} --> 1.3
* This function does not tolerate leading zeros.
* This function will fail (return false) if there are unresolved symbols, e.g. {iso test} will not be resolved to 1.test
* @author Daniel Marschall, ViaThinkSoft
* @version 2014-12-17
* @param string $asn<br />
* @param string $asn<br/>
* An OID in ASN.1 notation.
* @return string|false An OID in dot notation without leading dot or false if the path is invalid.
**/
862,7 → 862,7
* Gets the last numeric identifier of an ASN.1 notation OID.
* @author Daniel Marschall, ViaThinkSoft
* @version 2020-06-11
* @param string $asn1id<br />
* @param string $asn1id<br/>
* An ASN.1 identifier string, e.g. { 2 example(999) test(1) }
* @return int|false The last numeric identifier arc, e.g. "1" or false if the ID is invalid
**/
875,18 → 875,18
}
 
/**
* "Soft corrects" an invalid ASN.1 identifier.<br />
* "Soft corrects" an invalid ASN.1 identifier.<br/>
* Attention, by "soft correcting" the ID, it is not authoritative anymore, and might not be able to be resolved by ORS.
* @author Daniel Marschall, ViaThinkSoft
* @version 2020-05-22
* @param string $id<br />
* @param string $id<br/>
* An ASN.1 identifier.
* @param boolean $append_id_prefix<br />
* true (default): If the identifier doesn't start with a-Z, the problem will be solved by prepending "id-" to the identifier.<br />
* @param boolean $append_id_prefix<br/>
* true (default): If the identifier doesn't start with a-Z, the problem will be solved by prepending "id-" to the identifier.<br/>
* false: If the identifier doesn't start with a-Z, then the problem cannot be solved (method returns empty string).
* @return string The "soft corrected" ASN.1 identifier.<br />
* Invalid characters will be removed.<br />
* Uncorrectable start elements (0-9 or "-") will be either removed or solved by prepending "id-" (see <code>$append_id_prefix</code>)<br />
* @return string The "soft corrected" ASN.1 identifier.<br/>
* Invalid characters will be removed.<br/>
* Uncorrectable start elements (0-9 or "-") will be either removed or solved by prepending "id-" (see <code>$append_id_prefix</code>)<br/>
* If the identifier begins with an upper case letter, the letter will be converted into lower case.
**/
function oid_soft_correct_id($id, $append_id_prefix = true) {