LibItsSecurity_Functions.ttcn

                  return f_verifyGnSecuredMessageSignature_ecdsaBrainpoolP256r1(p_securedMessage, v_issuer, p_certificate.toBeSigned.verifyKeyIndicator.verificationKey.ecdsaBrainpoolP256r1);
                } else if (ischosen(p_securedMessage.content.signedData.signature_.ecdsaBrainpoolP384r1Signature)) {
                  return f_verifyGnSecuredMessageSignature_ecdsaBrainpoolP384r1(p_securedMessage, v_issuer, p_certificate.toBeSigned.verifyKeyIndicator.verificationKey.ecdsaBrainpoolP384r1);
                } else if (ischosen(p_securedMessage.content.signedData.signature_.ecdsaNistP256Signature)) {
                  return f_verifyGnSecuredMessageSignature_ecdsaNistP256(p_securedMessage, v_issuer, p_certificate.toBeSigned.verifyKeyIndicator.verificationKey.ecdsaNistP256);
                }
                
                return false;
            } // End of function f_verifyGnSecuredOtherMessageWithDeviceCertificate
            
        } // End of group deviceSignatureHelpers
        
        group sspPermissions {
          
          function f_verifySspPermissions(
                                          in SequenceOfPsidSsp p_issuer_ssp_permissions,
                                          in SequenceOfPsidSsp p_subordinate_ssp_permissions,
                                          in boolean p_strict_checks := false
          ) return boolean {
            // Local variables
            var integer v_idx := 0;
            
            log(">>> f_verifySspPermissions: p_issuer_ssp_permissions:", p_issuer_ssp_permissions);
            log(">>> f_verifySspPermissions: p_subordinate_ssp_permissions: ", p_subordinate_ssp_permissions);
            
            for (v_idx := 0; v_idx < lengthof(p_issuer_ssp_permissions); v_idx := v_idx + 1) {
              var PsidSsp v_issuerPsidSsp := p_issuer_ssp_permissions[v_idx];
              var PsidSsp v_subordinatePsidSsp;
              var boolean v_found := false;
              var integer v_jdx := 0;
              log("f_verifySspPermissions: v_issuerPsidSsp: ", v_issuerPsidSsp);
              // 1. Check permission from issuer is present
              for (v_jdx := 0; v_jdx < lengthof(p_subordinate_ssp_permissions); v_jdx := v_jdx + 1) {
                log("f_verifySspPermissions: match=", match(v_issuerPsidSsp, m_appPermissions(p_subordinate_ssp_permissions[v_jdx].psid, p_subordinate_ssp_permissions[v_jdx].ssp)));
                // 1. Check the version
                if (p_subordinate_ssp_permissions[v_jdx].ssp.bitmapSsp[0] != '01'O) {
                  log("f_verifySspPermissions: Wrong SSP version control (1 is expected): ", p_subordinate_ssp_permissions[v_jdx].ssp.bitmapSsp[0]);
                  return false;
                }
                // 2. Check the version
                if (match(v_issuerPsidSsp, m_appPermissions(p_subordinate_ssp_permissions[v_jdx].psid, p_subordinate_ssp_permissions[v_jdx].ssp)) == true) {
                  v_subordinatePsidSsp := p_subordinate_ssp_permissions[v_jdx];
                  v_found := true;
                  break;
                }
              } // End of 'for' statement
              if (v_found == false) {
                log("f_verifySspPermissions: Permission set not found: ", v_issuerPsidSsp);
                if (p_strict_checks == true) {
                  return false;
                } else {
                  return true;
                }
              }
              // 2. Validate bits mask
              if (ispresent(v_issuerPsidSsp.ssp)) {
                if (ispresent(v_subordinatePsidSsp.ssp) == false) {
                  log("f_verifySspPermissions: Ssp shall not be omitted: ", v_issuerPsidSsp);
                  if (p_strict_checks == true) {
                    return false;
                  }
                }
                if ((ischosen(v_issuerPsidSsp.ssp.bitmapSsp) == false) or (ischosen(v_subordinatePsidSsp.ssp.bitmapSsp) == false)) {
                  log("f_verifySspPermissions: Wrong variant : ", v_issuerPsidSsp, " / ", v_subordinatePsidSsp);
                  if (p_strict_checks == true) {
                    return false;
                  }
                }
                if (lengthof(v_issuerPsidSsp.ssp.bitmapSsp) < lengthof(v_subordinatePsidSsp.ssp.bitmapSsp)) {
                  log("f_verifySspPermissions: Ssp not be compliant: ", v_issuerPsidSsp.ssp, " / ", v_subordinatePsidSsp.ssp);
                  if (p_strict_checks == true) {
                    return false;
                  }
                } else {
                  var charstring v_issuerSsp := bit2str(oct2bit(v_issuerPsidSsp.ssp.bitmapSsp));
                  var charstring v_subordinateSsp := bit2str(oct2bit(v_subordinatePsidSsp.ssp.bitmapSsp));
                  
                  for (var integer i := 0; i < lengthof(v_issuerSsp); i := i + 1) {
                    if (v_issuerSsp[i] == "1") { // TODO How to check Permission using SspBitmask/SspValue
                      if (v_subordinateSsp[i] != "1") {
                        log("f_verifySspPermissions: Ssp bitmask mismatch at index: ", i);
                        return false;
                      }
                    } // else, no restriction, subordinate certificate can have any value.
                  } // End of 'for' statement
                }
              }
            } // End of 'for' statement
            
            return true;
          } // End of function f_verifySspPermissions
          
        } // End of group  sspPermissions
        
        group messageGetters {
            
            /**
            * @desc    return Ieee1609Dot2Data header field of given type or null if none
            * @param   p_msg the Ieee1609Dot2Data
            * @param   p_type header field type
            * @return  HeaderInfo of given type if any or null
            */
            function f_getMsgHeaderInfo(
                                        in template(omit) Ieee1609Dot2Data p_securedMessage,
                                        out HeaderInfo p_return
            ) return boolean {
                var integer v_length;
                var Ieee1609Dot2Data v_securedMessage;
                
                if (not isvalue(p_securedMessage)) {
                    testcase.stop(__SCOPE__ & " can not handle omitted secured message values");
                }
                v_securedMessage := valueof(p_securedMessage);
                if (ischosen(v_securedMessage.content.signedData)) {
                    p_return := v_securedMessage.content.signedData.tbsData.headerInfo;
                    return true;
                }

                log("f_getMsgHeaderField: return false");
                return false;
            }
            
            /**
            * @desc    return SignerIdentifier Ieee1609Dot2Data field
            */
            function f_getMsgSignerIdentifier (
                                               in template(omit) Ieee1609Dot2Data p_securedMessage,
                                               out SignerIdentifier p_signerIdentifier
            ) return boolean {
                if (not isvalue(p_securedMessage)) {
                    testcase.stop(__SCOPE__ & " can not handle omitted secured message values");
                }
                
                if (ischosen(p_securedMessage.content.signedData)) {
                    p_signerIdentifier := valueof(p_securedMessage.content.signedData.signer);
                    return true;
                }
                
                log("f_getMsgSignerIdentifier: return false");
                return false;
            }
            
        } // End of group messageGetters
        
        group certificateGetters {
            
            /**
             * @desc Set the generation location as defined in Draft ETSI TS 103 097 V1.1.14 Clause 7.2 Security profile for DENMs
             * @param p_latitude    The latitude value of the ITS-S position
             * @param p_longitude   The longitude value of the ITS-S position
             * @param p_elevation   The elevation value of the ITS-S position
             * @verdict Unchanged
             */
            function f_setGenerationLocation(
                                             in SecLatitude p_latitude,
                                             in SecLongitude p_longitude,
                                             in SecElevation p_elevation := 0
            ) runs on ItsSecurityBaseComponent {
                vc_location := {
                    p_latitude,
                    p_longitude,
                    p_elevation
                }
            } // End of function f_setGenerationLocation

            /**
            * @desc    Load in memory cache the certificates available
            * @param   p_configId      A configuration identifier
            * @remark  This method SHALL be call before any usage of certificates
            * @return  true on success, false otherwise
            */
            function f_loadCertificates(
                                        in charstring p_configId
            ) runs on ItsSecurityBaseComponent return boolean {
                var charstring v_certificate_id;
              
                // Setup certificates memory cache
                if (fx_loadCertificates(PX_CERTIFICATE_POOL_PATH, p_configId) == true) {
                  // Setup security component variables
                  if (f_readCertificate(PX_CERT_FOR_TS, vc_atCertificate) == true) {
                    var HashedId8 v_issuer;
//                    log("Issuer: ", vc_atCertificate.issuer);
                    if (ischosen(vc_atCertificate.issuer.sha256AndDigest)) {
                      v_issuer := vc_atCertificate.issuer.sha256AndDigest;
                    } else if (ischosen(vc_atCertificate.issuer.sha384AndDigest)) {
                      v_issuer := vc_atCertificate.issuer.sha384AndDigest;
                    } else {
                      log("AT certificate cannot be issued by CA");
                      return false;
                    }
                    log("Selected issuer: ", v_issuer);
                    if (f_getCertificateFromDigest(v_issuer, vc_aaCertificate, v_certificate_id)) {
                      if (f_readSigningKey(cc_taCert_A, vc_signingPrivateKey) == true) {
                        f_readEncryptingKey(cc_taCert_A, vc_encryptPrivateKey);
                        return true;
                      }
                      log("f_loadCertificates: Failed to load signing key for ", cc_taCert_A);
                    } else {
                      log("f_loadCertificates: Failed to load AA certificate for ", cc_taCert_A);
                    }
                  } else {
                    log("f_loadCertificates: Failed to load AT certificate for ", cc_taCert_A);
                  }
                } else {
                  log("f_loadCertificates: Failed to load certificates from ", PX_CERTIFICATE_POOL_PATH);
                }
                return false;
            } // End of function f_loadCertificates
            
            /**
            * @desc    Unload from memory cache the certificates available
            * @return  true on success, false otherwise
            */
            function f_unloadCertificates() runs on ItsSecurityBaseComponent return boolean {
                // Reset security component variables
                vc_signingPrivateKey := ''O;
                vc_encryptPrivateKey := ''O;
                // Clear certificates memory cache
                return fx_unloadCertificates();
            } // End of function f_unloadCertificates
            
            /**
             * @desc    Read the specified certificate
             * @param   p_certificate_id the certificate identifier
             * @param   p_certificate   the expected certificate
             * @return  true on success, false otherwise
             */
            function f_readCertificate(
                                       in charstring p_certificate_id,
                                       out EtsiTs103097Certificate p_certificate
            ) return boolean {
                var octetstring v_certificate;
                
                if (fx_readCertificate(p_certificate_id, v_certificate) == true) {
                    var bitstring v_oct2bit;
                    var integer v_result;
                    
                    v_oct2bit := oct2bit(v_certificate);
                    v_result := decvalue(v_oct2bit, p_certificate);
                    if (v_result == 0) {
                        return true;
                    }
                }
                
                log("f_readCertificate: Failed to retrieve ", p_certificate_id);
                return false;
            } // End of function f_readCertificate

            /**
             * @desc    Read the specified certificate
             * @param   p_certificate_id the certificate identifier
             * @param   p_digest        the digest of the certificate
             * @return  true on success, false otherwise
             */
            function f_getCertificateDigest(
                                            in charstring p_certificate_id,
                                            out HashedId8 p_digest
            ) return boolean {
                if (not fx_readCertificateDigest(p_certificate_id, p_digest)){
                    log("f_getCertificateDigest: Failed to retrieve digest for ", p_certificate_id);
                    return false;
                }
                return true;
            } // End of function f_getCertificateDigest
            
            /**
             * @desc    Read the whole-hash of the certificate
             * @param   p_certificate_id the certificate identifier
             * @param   p_hash          the whole-hash of the certificate
             * @return  true on success, false otherwise
             */
            function f_getCertificateHash(
                                          in charstring p_certificate_id,
                                          out octetstring p_hash
                                          ) return boolean {
                log(">>> f_getCertificateHash: ", p_certificate_id);
                
                if (not fx_readCertificateHash(p_certificate_id, p_hash)){
                    log("f_getCertificateHash: Failed to retrieve digest for ", p_certificate_id);
                    return false;
                }
                return true;
            } // End of function f_getCertificateHash
            
            /**
             * @desc    Read the whole-hash of the certificate SHA 256
             * @param   p_certificate_id the certificate identifier
             * @param   p_hash          the whole-hash of the certificate using SHA 256
             * @return  true on success, false otherwise
             */
            function f_getCertificateHash256(
                                             in charstring p_certificate_id,
                                             out Oct32 p_hash
            ) return boolean {
                if (not fx_readCertificateHash256(p_certificate_id, p_hash)){
                    log("f_getCertificateHash256: Failed to retrieve digest for ", p_certificate_id);
                    return false;
                }
                return true;
            } // End of function f_getCertificateHash256
            
            function f_getCertificateFromDigest(
                                                in HashedId8 p_digest, 
                                                out EtsiTs103097Certificate p_certificate,
                                                out charstring p_certificate_id
            ) return boolean {
                if (not(fx_readCertificateFromDigest(p_digest, p_certificate_id))) {
                    log("f_getCertificateFromDigest: Failed to retrieve digest for ", p_digest);
                    return false;
                }
                if (not(f_readCertificate(p_certificate_id, p_certificate))) {
                    log("f_getCertificateFromDigest: Failed to retrieve digest for ", p_certificate_id);
                    return false;
                }
                return true;
            } // End of function f_getCertificateFromDigest
            
            function f_getCertificateFromHashedId3(
                                                   in HashedId3 p_digest, 
                                                   out EtsiTs103097Certificate p_certificate
            ) return boolean {
                var charstring v_certificate_id;
                if (not(fx_readCertificateFromHashedId3(p_digest, v_certificate_id))) {
                    log("f_getCertificateFromHashedId3: Failed to retrieve digest for ", p_digest);
                    return false;
                }
                if (not(f_readCertificate(v_certificate_id, p_certificate))) {
                    log("f_getCertificateFromHashedId3: Failed to retrieve digest for ", v_certificate_id);
                    return false;
                }
                return true;
            } // End of function f_getCertificateFromHashedId3
            
            function f_getCertificateIssuer(
                                            in IssuerIdentifier p_issuer
            ) return HashedId8 {
                if (ischosen(p_issuer.sha256AndDigest)) {
                    return p_issuer.sha256AndDigest;
                } else if (ischosen(p_issuer.sha256AndDigest)) {
                    return p_issuer.sha256AndDigest;
                }
                return int2oct(0, 8);
            }
            
            function f_getHashAlgorithm(
                                        in IssuerIdentifier p_issuer
            ) return HashAlgorithm {
                if (ischosen(p_issuer.sha256AndDigest)) {
                    return sha256;
                } else if (ischosen(p_issuer.sha256AndDigest)) {
                    return sha384;
                }
                return p_issuer.self_;
            }
            
            /**
            * @desc    Read the signing private key for the specified certificate
            * @param   p_keysId            the keys identifier
            * @param   p_signingPrivateKey the signing private key
            * @return  true on success, false otherwise
            */
            function f_readSigningKey(
                                       in charstring p_keysId,
                                       out Oct32 p_signingPrivateKey
            ) return boolean {
                return fx_readSigningKey(p_keysId, p_signingPrivateKey);
            } // End of function f_readSigningKey
            
            /**
            * @desc    Read the encrypting private keys for the specified certificate
            * @param   p_keysId            the keys identifier
            * @param   p_encryptPrivateKey the encrypt private key
            * @return  true on success, false otherwise
            */
            function f_readEncryptingKey(
                                         in charstring p_keysId,
                                         out Oct32 p_encryptPrivateKey
            ) return boolean {
                return fx_readEncryptingKey(p_keysId, p_encryptPrivateKey);
            } // End of function f_readEncryptingKey
            
            function f_getCertificateValidityRestriction(
                                                         in template (value) EtsiTs103097Certificate p_cert,
                                                         out template (value) ValidityPeriod p_validityPeriod,
                                                         out template (omit) GeographicRegion p_geographicRegion
            ) return boolean {
                p_validityPeriod := valueof(p_cert.toBeSigned.validityPeriod);
                if (ispresent(p_cert.toBeSigned.region)) {
                    p_geographicRegion := valueof(p_cert.toBeSigned.region);
                } else {
                    p_geographicRegion := omit;
                }
                return true;
            } // End of function f_getCertificateValidityRestriction
            
        }// End of group certificateGetters
        
        group certificatesCaching {
            
            function f_createCertificatesCaching(
                                                 in SequenceOfCertificate p_certificates, 
                                                 out CertificatesCaching p_certificatesCaching
            ) return boolean {
                p_certificatesCaching := { };
                for (var integer v_counter := 0; v_counter < lengthof(p_certificates); v_counter := v_counter + 1) {
                    var CertificatesCachingItem v_item;
                    v_item.certificate := p_certificates[v_counter];
                    v_item.hashedId8 := f_calculateDigestSha256FromCertificate(v_item.certificate);
                    p_certificatesCaching[v_counter] := v_item;
                } // End of 'for' statement
                
                return true;
            }
            
            function f_getCertificateFromCaching(
                                                 in CertificatesCaching p_certificatesCaching, 
                                                 in HashedId8 p_hashedId8, 
                                                 out EtsiTs103097Certificate p_certificate
            ) return boolean {
                for (var integer v_counter := 0; v_counter < lengthof(p_certificatesCaching); v_counter := v_counter + 1) { 
                    if (match(p_certificatesCaching[v_counter].hashedId8, p_hashedId8) == true) {
                        p_certificate := p_certificatesCaching[v_counter].certificate;
                        return true;
                    }
                } // End of 'for' statement
                
                return false;
            }
            
            function f_getCertificatesCachingItem(
                                                  in CertificatesCaching p_certificatesCaching, 
                                                  in UInt8 p_index, 
                                                  out EtsiTs103097Certificate p_certificate
            ) return boolean {
                if (lengthof(p_certificatesCaching) < p_index) {
                    p_certificate := p_certificatesCaching[p_index].certificate;
                    return true;
                }
                
                return false;
            }
            
            function f_getCertificatesCachingItemSize(
                                                      in CertificatesCaching p_certificatesCaching
            ) return UInt8 {
                return lengthof(p_certificatesCaching);
            }
            
        }// End of group certificatesCaching
        
        
    } // End of group helpersFunctions

    group externalFunctions {
        
        group signing {
            
            /**
             * @desc    Produces a 256-bit (32-byte) hash value
             * @param   p_toBeHashedData Data to be used to calculate the hash value
             * @return  The hash value
             */
            external function fx_hashWithSha256(in octetstring p_toBeHashedData) return Oct32;
            
            /**
             * @desc    Produces a 384-bit (48-byte) hash value
             * @param   p_toBeHashedData Data to be used to calculate the hash value
             * @return  The hash value
             */
            external function fx_hashWithSha384(in octetstring p_toBeHashedData) return Oct48;
            
            /**
             * @desc    Produces a Elliptic Curve Digital Signature Algorithm (ECDSA) signature
             * @param   p_toBeSignedSecuredMessage  The data to be signed
             * @param   p_certificateIssuer           The whole-hash issuer certificate or int2oct(0, 32) in case of self signed certificate
             * @param   p_privateKey                The private key
             * @return  The signature value
             */
            external function fx_signWithEcdsaNistp256WithSha256(in octetstring p_toBeSignedSecuredMessage, in Oct32 p_certificateIssuer, in Oct32 p_privateKey) return octetstring;
            
            /**
             * @desc    Produces a Elliptic Curve Digital Signature Algorithm (ECDSA) signature
             * @param   p_toBeSignedSecuredMessage    The data to be signed
             * @param   p_certificateIssuer           The whole-hash issuer certificate or int2oct(0, 32) in case of self signed certificate
             * @param   p_privateKey                  The private key for signature
             * @return  The signature value
             */
            external function fx_signWithEcdsaBrainpoolp256r1WithSha256(in octetstring p_toBeSignedSecuredMessage, in Oct32 p_certificateIssuer, in Oct32 p_privateKey) return octetstring;
            
            /**
             * @desc    Produces a Elliptic Curve Digital Signature Algorithm (ECDSA) signature
             * @param   p_certificateIssuer           The whole-hash issuer certificate or int2oct(0, 32) in case of self signed certificate
             * @param   p_privateKey                  The private key for signature
             * @return  The signature value
             */
            external function fx_signWithEcdsaBrainpoolp384r1WithSha384(in octetstring p_toBeSignedSecuredMessage, in Oct48 p_certificateIssuer, in Oct48 p_privateKey) return octetstring;
            
            /**
             * @desc    Verify the signature of the specified data
             * @param   p_toBeVerifiedData          The data to be verified
             * @param   p_certificateIssuer         The whole-hash issuer certificate or int2oct(0, 32) in case of self signed certificate
             * @param   p_signature                 The signature
             * @param   p_ecdsaNistp256PublicKeyCompressed   The compressed public key
             * @param   p_compressed_mode            The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @return  true on success, false otherwise
             */
            external function fx_verifyWithEcdsaNistp256WithSha256(in octetstring p_toBeVerifiedData, in Oct32 p_certificateIssuer, in octetstring p_signature, in Oct32 p_ecdsaNistp256PublicKeyCompressed, in integer p_compressed_mode) return boolean;
            
            /**
             * @desc    Verify the signature of the specified data
             * @param   p_toBeVerifiedData          The data to be verified
             * @param   p_certificateIssuer         The whole-hash issuer certificate or int2oct(0, 32) in case of self signed certificate
             * @param   p_signature                 The signature
             * @param   p_ecdsaNistp256PublicKeyX   The public key (x coordinate)
             * @param   p_ecdsaNistp256PublicKeyY   The public key (y coordinate)
             * @return  true on success, false otherwise
             */
            external function fx_verifyWithEcdsaNistp256WithSha256_1(in octetstring p_toBeVerifiedData, in Oct32 p_certificateIssuer, in Oct64 p_signature, in Oct32 p_ecdsaNistp256PublicKeyX, in Oct32 p_ecdsaNistp256PublicKeyY) return boolean;
            
            /**
             * @desc    Verify the signature of the specified data
             * @param   p_toBeVerifiedData          The data to be verified
             * @param   p_certificateIssuer         The whole-hash issuer certificate or int2oct(0, 32) in case of self signed certificate
             * @param   p_signature                 The signature
             * @param   p_ecdsaBrainpoolp256PublicKeyCompressed   The compressed public key
             * @param   p_compressed_mode            The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @return  true on success, false otherwise
             */
            external function fx_verifyWithEcdsaBrainpoolp256r1WithSha256(in octetstring p_toBeVerifiedData, in Oct32 p_certificateIssuer, in Oct64 p_signature, in Oct32 p_ecdsaBrainpoolp256PublicKeyCompressed, in integer p_compressed_mode) return boolean;
            
            /**
             * @desc    Verify the signature of the specified data
             * @param   p_toBeVerifiedData          The data to be verified
             * @param   p_certificateIssuer         The certificate issuer
             * @param   p_signature                 The signature
             * @param   p_ecdsaBrainpoolp256PublicKeyX   The public key (x coordinate)
             * @param   p_ecdsaBrainpoolp256PublicKeyY   The public key (y coordinate)
             * @return  true on success, false otherwise
             */
            external function fx_verifyWithEcdsaBrainpoolp256r1WithSha256_1(in octetstring p_toBeVerifiedData, in Oct32 p_certificateIssuer, in Oct64 p_signature, in Oct32 p_ecdsaBrainpoolp256PublicKeyX, in Oct32 p_ecdsaBrainpoolp256PublicKeyY) return boolean;
            
            /**
             * @desc    Verify the signature of the specified data
             * @param   p_toBeVerifiedData          The data to be verified
             * @param   p_certificateIssuer         The certificate issuer
             * @param   p_signature                 The signature
             * @param   p_ecdsaBrainpoolp384PublicKeyCompressed   The compressed public key
             * @param   p_compressed_mode            The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @return  true on success, false otherwise
             */
            external function fx_verifyWithEcdsaBrainpoolp384r1WithSha384(in octetstring p_toBeVerifiedData, in Oct48 p_certificateIssuer, in Oct96 p_signature, in Oct48 p_ecdsaBrainpoolp384PublicKeyCompressed, in integer p_compressed_mode) return boolean;
            
            /**
             * @desc    Verify the signature of the specified data
             * @param   p_toBeVerifiedData          The data to be verified
             * @param   p_certificateIssuer         The hash of the canonical certificate issuer
             * @param   p_signature                 The signature
             * @param   p_ecdsaBrainpoolp384PublicKeyX   The public key (x coordinate)
             * @param   p_ecdsaBrainpoolp384PublicKeyY   The public key (y coordinate)
             * @return  true on success, false otherwise
             */
            external function fx_verifyWithEcdsaBrainpoolp384r1WithSha384_1(in octetstring p_toBeVerifiedData, in Oct48 p_certificateIssuer, in Oct96 p_signature, in Oct48 p_ecdsaBrainpoolp384PublicKeyX, in Oct48 p_ecdsaBrainpoolp384PublicKeyY) return boolean;
            
            /**
             * @desc    Produce a new public/private key pair based on Elliptic Curve Digital Signature Algorithm (ECDSA) algorithm.
             *          This function should not be used by the ATS
             * @param   p_privateKey    The new private key value
             * @param   p_publicKeyX    The new public key value (x coordinate)
             * @param   p_publicKeyX    The new public key value (y coordinate)
             * @param   p_publicKeyCompressed The compressed public keys
             * @param   p_compressed_mode The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @return  true on success, false otherwise
             */
            external function fx_generateKeyPair_nistp256(out Oct32 p_privateKey, out Oct32 p_publicKeyX, out Oct32 p_publicKeyY, out Oct32 p_publicKeyCompressed, out integer p_compressed_mode) return boolean;
            
            /**
             * @desc    Produce a new public/private key pair based on Elliptic Curve Digital Signature Algorithm (ECDSA) algorithm.
             *          This function should not be used by the ATS
             * @param   p_privateKey    The new private key value
             * @param   p_publicKeyX    The new public key value (x coordinate)
             * @param   p_publicKeyX    The new public key value (y coordinate)
             * @param   p_publicKeyCompressed The compressed public keys
             * @param   p_compressed_mode The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @return  true on success, false otherwise
             */
            external function fx_generateKeyPair_brainpoolp256r1(out Oct32 p_privateKey, out Oct32 p_publicKeyX, out Oct32 p_publicKeyY, out Oct32 p_publicKeyCompressed, out integer p_compressed_mode) return boolean;
            
            /**
             * @desc    Produce a new public/private key pair based on Elliptic Curve Digital Signature Algorithm (ECDSA) algorithm.
             *          This function should not be used by the ATS
             * @param   p_privateKey    The new private key value
             * @param   p_publicKeyX    The new public key value (x coordinate)
             * @param   p_publicKeyX    The new public key value (y coordinate)
             * @param   p_publicKeyCompressed The compressed public keys
             * @param   p_compressed_mode The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @return  true on success, false otherwise
             */
            external function fx_generateKeyPair_brainpoolp384r1(out Oct48 p_privateKey, out Oct48 p_publicKeyX, out Oct48 p_publicKeyY, out Oct48 p_publicKeyCompressed, out integer p_compressed_mode) return boolean;
            
            external function fx_get_uncompressed_key_nistp256(in Oct32 p_privateKey, in Oct32 p_publicKeyCompressed, in integer p_compressed_mode, out Oct32 p_publicKeyY) return boolean;
            external function fx_get_uncompressed_key_brainpoolp256r1(in Oct32 p_privateKey, in Oct32 p_publicKeyCompressed, in integer p_compressed_mode, out Oct32 p_publicKeyY) return boolean;
            external function fx_get_uncompressed_key_brainpoolp384r1(in Oct48 p_privateKey, in Oct48 p_publicKeyCompressed, in integer p_compressed_mode, out Oct48 p_publicKeyY) return boolean;
            
        } // End of group signing
        
        group encryption {
            
            external function fx_hmac_sha256(in octetstring p_k, in octetstring p_m) return octetstring;
            
            /**
             * @desc    This function validates AES128 CCM encryption based on IEEE Std 1609.2-20XX Annex D.6.1 AES-CCM-128
             * @param[in] The symmetric AES 128 encryption key 
             * @param[in] The initial vector (aka nonce)
             * @param[in] The raw payload
             * @return  The encrypted payload
             */
            external function fx_encrypt_aes_128_ccm_test(in octetstring p_k, in octetstring p_n, in octetstring p_pt) return octetstring;
            
            /**
             * @desc    TThis function validates AES128 CCM encryption based on AES-GCM-256
             * @param[in] The symmetric AES 128 encryption key 
             * @param[in] The initial vector (aka nonce)
             * @param[in] The raw payload
             * @return  The encrypted payload
             */
            external function fx_encrypt_aes_128_gcm_test(in octetstring p_k, in octetstring p_n, in octetstring p_pt) return octetstring;
            
            /**
             * @desc    This function validates AES128 CCM decryption based on IEEE Std 1609.2-20XX Annex D.6.1 AES-CCM-128
             * @param[in] The symmetric AES 128 encryption key 
             * @param[in] The initial vector (aka nonce)
             * @param[in] The cyphered payload
             * @return  The raw payload
             */
            external function fx_decrypt_aes_128_ccm_test(in octetstring p_k, in octetstring p_n, in octetstring p_pt) return octetstring;
            
            /**
             * @desc    Produces a Elliptic Curve Digital Encrytion Algorithm (ECIES) encryption using Nist-P256 algorithm
             * @param   p_toBeEncryptedSecuredMessage    The data to be encrypted
             * @param   p_recipientsPublicKeyCompressed  The Recipient's compressed public key
             * @param   p_compressed_mode                 The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @param   p_publicEphemeralKeyCompressed   The generated ephemeral compressed key
             * @param   p_ephemeralKeyModeCompressed     The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @param   p_encrypted_sym_key              The encrypted AES 128 CCM symmetric key
             * @param   p_authentication_vector          The tag of the AES 128 CCM symmetric key encryption
             * @param   p_nonce                          The nonce vector of the AES 128 CCM symmetric key encryption
             * @return  The encrypted message
             */
            external function fx_encryptWithEciesNistp256WithSha256(in octetstring p_toBeEncryptedSecuredMessage, in Oct32 p_recipientsPublicKeyCompressed, in integer p_compressed_mode, in octetstring p_salt, out Oct32 p_publicEphemeralKeyCompressed, out integer p_ephemeralKeyModeCompressed, out Oct16 p_aes_sym_key, out Oct16 p_encrypted_sym_key, out Oct16 p_authentication_vector, out Oct12 p_nonce) return octetstring;
            
            external function fx_test_encryptWithEciesNistp256WithSha256(in octetstring p_toBeEncryptedSecuredMessage, in Oct32 p_privateEphemeralKey, in Oct32 p_recipientPublicKeyX, in Oct32 p_recipientPublicKeyY, in octetstring p_salt, out Oct32 p_publicEphemeralKeyX, out Oct32 p_publicEphemeralKeyY, out Oct16 p_aes_sym_key, out Oct16 p_encrypted_sym_key, out Oct16 p_authentication_vector, out Oct12 p_nonce) return octetstring;
            
            /**
             * @desc    Produces a Elliptic Curve Digital Encrytion Algorithm (ECIES) decryption using Nist-P256 algorithm
             * @param   p_encryptedSecuredMessage    The data to be decrypted
             * @param   p_publicEphemeralKeyCompressed   The generated ephemeral compressed key
             * @param   p_ephemeralKeyModeCompressed     The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @param   p_encrypted_sym_key              The encrypted AES 128 CCM symmetric key
             * @param   p_authentication_vector          The tag of the AES 128 CCM symmetric key encryption
             * @param   p_nonce                          The nonce vector of the AES 128 CCM symmetric key encryption
             * @return  The decrypted message
             */
            external function fx_decryptWithEciesNistp256WithSha256(in octetstring p_encryptedSecuredMessage, in Oct32 p_privateEncKey, in Oct32 p_publicEphemeralKeyCompressed, in integer p_ephemeralKeyModeCompressed, in Oct16 p_encrypted_sym_key, in Oct16 p_authentication_vector, in Oct12 p_nonce, in Oct32 p_salt, out Oct16 p_aes_sym_enc_key) return octetstring;
            
            /**
             * @desc    Produces a Elliptic Curve Digital Encrytion Algorithm (ECIES) encryption using Brainpool-P256 algorithm
             * @param   p_toBeEncryptedSecuredMessage    The data to be encrypted
             * @param   p_recipientsPublicKeyCompressed  The Recipient's compressed public key
             * @param   p_compressed_mode                 The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @param   p_publicEphemeralKeyCompressed   The generated ephemeral compressed key
             * @param   p_ephemeralKeyModeCompressed     The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @param   p_encrypted_sym_key              The encrypted AES 128 CCM symmetric key
             * @param   p_authentication_vector          The tag of the AES 128 CCM symmetric key encryption
             * @param   p_nonce                          The nonce vector of the AES 128 CCM symmetric key encryption
             * @return  The encrypted message
             */
            external function fx_encryptWithEciesBrainpoolp256r1WithSha256(in octetstring p_toBeEncryptedSecuredMessage, in Oct32 p_recipientsPublicKeyCompressed, in integer p_compressed_mode, in octetstring p_salt, out Oct32 p_publicEphemeralKeyCompressed, out integer p_ephemeralKeyModeCompressed, out Oct16 p_aes_sym_key, out Oct16 p_encrypted_sym_key, out Oct16 p_authentication_vector, out Oct12 p_nonce) return octetstring;
            
            external function fx_test_encryptWithEciesBrainpoolp256r1WithSha256(in octetstring p_toBeEncryptedSecuredMessage, in Oct32 p_privateEphemeralKey, in Oct32 p_recipientPublicKeyX, in Oct32 p_recipientPublicKeyY, in octetstring p_salt, out Oct32 p_publicEphemeralKeyX, out Oct32 p_publicEphemeralKeyY, out Oct16 p_aes_sym_key, out Oct16 p_encrypted_sym_key, out Oct16 p_authentication_vector, out Oct12 p_nonce) return octetstring;
            
            /**
             * @desc    Produces a Elliptic Curve Digital Encrytion Algorithm (ECIES) decryption using Brainpool-P256 algorithm
             * @param   p_encryptedSecuredMessage    The data to be decrypted
             * @param   p_publicEphemeralKeyCompressed   The generated ephemeral compressed key
             * @param   p_ephemeralKeyModeCompressed     The compressed mode, 0 if the latest bit of Y-coordinate is 0, 1 otherwise
             * @param   p_encrypted_sym_key              The encrypted AES 128 CCM symmetric key
             * @param   p_authentication_vector          The tag of the AES 128 CCM symmetric key encryption
             * @param   p_nonce                          The nonce vector of the AES 128 CCM symmetric key encryption
             * @return  The decrypted message
             */
            external function fx_decryptWithEciesBrainpoolp256r1WithSha256(in octetstring p_encryptedSecuredMessage, in Oct32 p_privateEncKey, in Oct32 p_publicEphemeralKeyCompressed, in integer p_ephemeralKeyModeCompressed, in Oct16 p_encrypted_sym_key, in Oct16 p_authentication_vector, in Oct12 p_nonce, in Oct32 p_salt, out Oct16 p_aes_sym_enc_key) return octetstring;
            
        } // End of group encryption
        
        group certificatesLoader {
            
            /**
            * @desc    Load in memory cache the certificates available in the specified directory
            * @param   p_rootDirectory Root directory to access to the certificates identified by the certificate ID
            * @param   p_configId      A configuration identifier
            * @remark  This method SHALL be call before any usage of certificates
            * @return  true on success, false otherwise
            */
            external function fx_loadCertificates(in charstring p_rootDirectory, in charstring p_configId) return boolean;
            external function fx_store_certificate(in charstring p_cert_id, in octetstring p_cert, in octetstring p_private_key, in octetstring p_public_key_x, in octetstring p_public_key_y, in octetstring p_public_key_compressed, in integer p_public_key_compressed_mode, in octetstring p_hash, in octetstring p_hash_256, in octetstring p_hashid8, in octetstring p_issuer, in template (omit) octetstring p_private_enc_key, in template (omit) octetstring p_public_enc_key_x, in template (omit) octetstring p_public_enc_key_y, in template (omit) octetstring p_public_enc_compressed_key, in template (omit) integer p_public_enc_key_compressed_mode) return boolean;
            
            /**
             * @desc    Unload from memory cache the certificates
             * @return  true on success, false otherwise
             */
            external function fx_unloadCertificates() return boolean;
            
            /**
             * @desc    Read the specified certificate
             * @param   p_certificate_id the certificate identifier
             * @param   p_certificate   the expected certificate
             * @return  true on success, false otherwise
             */
            external function fx_readCertificate(in charstring p_certificate_id, out octetstring p_certificate) return boolean;

            /**
             * @desc    Read the specified certificate digest
             * @param   p_certificate_id the certificate identifier
             * @param   p_digest   the expected certificate
             * @return  true on success, false otherwise
             */
            external function fx_readCertificateDigest(in charstring p_certificate_id, out HashedId8 p_digest) return boolean;
            
            /**
             * @desc    Read the whole-hash of the specified certificate
             * @param   p_certificate_id the certificate identifier
             * @param   p_hash          the whole-hash of the certificate
             * @return  true on success, false otherwise
             */
            external function fx_readCertificateHash(in charstring p_certificate_id, out octetstring p_hash) return boolean;
            
            /**
             * @desc    Read the whole-hash of the specified certificate using SHA 256
             * @param   p_certificate_id the certificate identifier
             * @param   p_hash          the whole-hash of the certificate
             * @return  true on success, false otherwise
             */
            external function fx_readCertificateHash256(in charstring p_certificate_id, out Oct32 p_hash) return boolean;
            
            external function fx_readCertificateFromDigest(in HashedId8 p_digest, out charstring p_certificate_id) return boolean;
            
            external function fx_readCertificateFromHashedId3(in HashedId3 p_digest, out charstring p_certificate_id) return boolean;
            
            /**
             * @desc    Read the private keys for the specified certificate
             * @param   p_keysId            the keys identifier
             * @param   p_signingPrivateKey the signing private key
             * @return  true on success, false otherwise
             */

            external function fx_readSigningKey(in charstring p_keysId, out Oct32 p_signingPrivateKey) return boolean;

            /**
            * @desc    Read the private keys for the specified certificate
            * @param   p_keysId            the keys identifier
            * @param   p_encryptPrivateKey the encrypt private key
            * @return  true on success, false otherwise
            */

            external function fx_readEncryptingKey(in charstring p_keysId, out Oct32 p_encryptingPrivateKey) return boolean;

        } // End of group certificatesLoader
        
        group geodesic {
            
            /**
            * @desc    Check that given polygon doesn't have neither self-intersections nor holes.
            * @param   p_region   Polygonal Region
            * @return  true on success, false otherwise
            * @verdict Unchanged
            */
            external function fx_isValidPolygonalRegion(in PolygonalRegion p_region) return boolean;
            
            /**
            * @desc Check if a polygonal region is inside another one
            * @param p_parent  The main polygonal region
            * @param p_region  The polygonal region to be included
            * @return true on success, false otherwise
            * @verdict Unchanged
            */
            external function fx_isPolygonalRegionInside(in PolygonalRegion p_parent, in PolygonalRegion p_region) return boolean;
            
            /**
            * @desc Check that the location is inside a circular region
            * @param p_region      The circular region to consider
            * @param p_location    The device location
            * @return true on success, false otherwise
            * @verdict Unchanged
            */
            external function fx_isLocationInsideCircularRegion(in CircularRegion p_region, in ThreeDLocation p_location) return boolean;
            
            /**
            * @desc Check that the location is inside a rectangular region
            * @param p_region      The rectangular region to consider
            * @param p_location    The device location
            * @return true on success, false otherwise
            * @verdict Unchanged
            */
            external function fx_isLocationInsideRectangularRegion(in SequenceOfRectangularRegion p_region, in ThreeDLocation p_location) return boolean;
            
            /**
            * @desc Check that the location is inside a polygonal region
            * @param p_region      The polygonal region to consider
            * @param p_location    The device location
            * @return true on success, false otherwise
            * @verdict Unchanged
            */
            external function fx_isLocationInsidePolygonalRegion(in PolygonalRegion p_region, in ThreeDLocation p_location) return boolean;
            
            /**
            * @desc Check if the location is inside an identified region
            * @param p_region      The identified region to consider
            * @param p_location    The device location
            * @return true on success, false otherwise
            * @verdict Unchanged
            */
            external function fx_isLocationInsideIdentifiedRegion(in IdentifiedRegion p_region, in ThreeDLocation p_location) return boolean;
            
            /**
            * @desc Check if the location is inside an undefined region
            * @param p_region      The identified region to consider
            * @param p_location    The device location
            * @return true on success, false otherwise
            * @verdict Unchanged
            */
            external function fx_isLocationInsideOtherRegion(in octetstring p_region, in ThreeDLocation p_location) return boolean; 
            
            /**
             * @desc    Check that p_circular_region_1 circular region is included into p_circular_region_2 circular region
             * @param   p_circular_region_1    Circular region 1
             * @param   p_circular_region_2    Circular region 2
             *
             * @return  true on success, false otherwise
             */
            external function fx_areCirclesInside(in CircularRegion p_circular_region_1, in CircularRegion p_circular_region_2) return boolean;
            
            /**
             * @desc    Check that p_rectanglar_region_1 rectangular region is included into p_rectanglar_region_2 rectangular region
             * @param   p_rectanglar_region_1    Rectangular region 1
             * @param   p_rectanglar_region_2    Rectangular region 2
             *
             * @return  true on success, false otherwise
             */
            external function fx_areRectanglesInside(in SequenceOfRectangularRegion p_rectanglar_region_1, in SequenceOfRectangularRegion p_rectanglar_region_2) return boolean;
            
            /**
             * @desc    Check that p_polygonal_region_1 polygonal region is included into p_polygonal_region_2 polygonal region
             * @param   p_polygonal_region_1    Polygonal region 1
             * @param   p_polygonal_region_2    Polygonal region 2
             *
             * @return  true on success, false otherwise
             */
            external function fx_arePolygonsInside(in PolygonalRegion p_polygonal_region_1, in PolygonalRegion p_polygonal_region_2) return boolean;
            
            /**
            * @desc Convert a spacial coordinate from DMS to Dms
            * @param p_degrees The degrees (D)
            * @param p_minutes The minutes (M)
            * @param p_seconds The seconds (S)
            * @param p_latlon  The latitude/longitude: (N|S|E|W)
            * @return The decimal coordinate on success, 0.0, otherwise
            * @verdict Unchanged
            */
            external function fx_dms2dd(in Int p_degrees, in Int p_minutes, in float p_seconds, in Oct1 p_latlon) return float;
            
        } // End of group geodesic
        
    } // End of group externalFunctions
    
    group geometryFunctions {
        
        function f_checkRegionValidityRestiction(
                                                 in EtsiTs103097Certificate p_cert, 
                                                 in EtsiTs103097Certificate p_cert_issuer
        ) return boolean {
            var ValidityPeriod v_cert_region, v_cert_issuer_region;
            var boolean v_cert_issuer_region_result;
            
            /* FIXME To be reviewed v_cert_issuer_region_result := f_getCertificateValidityRestriction(p_cert_issuer, e_region, v_cert_issuer_region);
            if (f_getCertificateValidityRestriction(p_cert, e_region, v_cert_region) == false) {
                if (v_cert_issuer_region_result == true) {
                    if (v_cert_issuer_region.validity.region.region_type != e_none) {
                        return false;
                    }
                }
            } else if (
                        (v_cert_issuer_region_result == true) and 
                        (v_cert_issuer_region.validity.region.region_type != e_none)
            ) {
                if (v_cert_region.validity.region.region_type == e_circle) {
                    if (v_cert_issuer_region.validity.region.region_type == e_circle) {
                        // Check v_cert_region 'circle' is inside v_cert_issuer_region 'circle'
                        if (f_areCirclesInside(v_cert_region.validity.region.region.circular_region, v_cert_issuer_region.validity.region.region.circular_region) == false) {
                            log("*** " & testcasename() & ": FAIL: Issuer and issuing certificates circle area does not match ***");
                            return false;
                        }
                    }
                } else if (v_cert_region.validity.region.region_type == e_rectangle) {
                    if (v_cert_issuer_region.validity.region.region_type == e_rectangle) {
                        // Check v_cert_region 'rectangle' is inside v_cert_issuer_region 'rectangle'
                        if (f_areRectanglesInside(v_cert_region.validity.region.region.rectangular_region, v_cert_issuer_region.validity.region.region.rectangular_region) == false) {
                            log("*** " & testcasename() & ": FAIL: Issuer and issuing certificates rectangle area does not match ***");
                            return false;
                        }
                    }
                } else if (v_cert_region.validity.region.region_type == e_polygon) {
                    if (v_cert_issuer_region.validity.region.region_type == e_polygon) {
                        // Check v_cert_region 'polygon' is inside v_cert_issuer_region 'polygon'
                        if (f_arePolygonsInside(v_cert_region.validity.region.region.polygonal_region, v_cert_issuer_region.validity.region.region.polygonal_region) == false) {
                            log("*** " & testcasename() & ": FAIL: Issuer and issuing certificates polygon area does not match ***");
                            return false;
                        }
                    }
                } else if (v_cert_region.validity.region.region_type == e_id) {
                    // Check id_region
                    if (not match (v_cert_region.validity.region, mw_geographicRegion_identified(mw_identifiedRegion_iso3166_any))) { 
                        log("*** " & testcasename() & ": FAIL: Identified region is not conformed to ISO 3166-1 ***");
                        return false;
                    }
                    if (not match (v_cert_region.validity.region, mw_geographicRegion_identified(mw_identifiedRegion_un_stats_any))) {
                        log("*** " & testcasename() & ": FAIL: Identified region is not conformed to United Nations Statistics Division ***");
                        return false;
                    }
                    // Check region_dictionary
                    if (not match (v_cert_region.validity.region.region.id_region.region_dictionary, v_cert_issuer_region.validity.region.region.id_region.region_dictionary)) {
                        log("*** " & testcasename() & ": FAIL: Issuer and issuing 'region_dictionary' field does not match ***");
                        return false;
                    }
                    // Check region_identifier
                    if (not match (v_cert_region.validity.region.region.id_region.region_identifier, v_cert_issuer_region.validity.region.region.id_region.region_identifier)) {
                        log("*** " & testcasename() & ": FAIL: Issuer and issuing 'region_identifier' field does not match ***");
                        return false;
                    }
                    // Check local_region
                    if (
                        (not match (v_cert_issuer_region.validity.region.region.id_region.local_region, v_cert_region.validity.region.region.id_region.local_region)) or 
                        (not match (v_cert_issuer_region.validity.region.region.id_region.local_region, 0))
                    ) {
                        log("*** " & testcasename() & ": FAIL: Issuer and issuing 'local_region' field does not match ***");
                        return false;
                    }
                }
            }*/
            
            return true;
        } // End of function f_checkRegionValidityRestiction
        
        /**
         * @desc    Check that p_circular_region_1 circular region is included into p_circular_region_2 circular region
         * @param   p_circular_region_1    Circular region 1
         * @param   p_circular_region_2    Circular region 2
         *
         * @return  true on success, false otherwise
         */
        function f_areCirclesInside(
                                    in CircularRegion p_circular_region_1, 
                                    in CircularRegion p_circular_region_2
        ) return boolean {
            return fx_areCirclesInside(p_circular_region_1, p_circular_region_2);
        }
        
        /**
         * @desc    Check that p_rectanglar_region_1 rectangular region is included into p_rectanglar_region_2 rectangular region
         * @param   p_rectanglar_region_1    Rectangular region 1
         * @param   p_rectanglar_region_2    Rectangular region 2
         *
         * @return  true on success, false otherwise
         */
        function f_areRectanglesInside(
                                       in SequenceOfRectangularRegion p_rectanglar_region_1, 
                                       in SequenceOfRectangularRegion p_rectanglar_region_2
        ) return boolean {
            return fx_areRectanglesInside(p_rectanglar_region_1, p_rectanglar_region_2);
        }
        
        /**
         * @desc    Check that p_polygonal_region_1 polygonal region is included into p_polygonal_region_2 polygonal region
         * @param   p_polygonal_region_1    Polygonal region 1
         * @param   p_polygonal_region_2    Polygonal region 2
         *
         * @return  true on success, false otherwise
         */
        function f_arePolygonsInside(
                                     in PolygonalRegion p_polygonal_region_1, 
                                     in PolygonalRegion p_polygonal_region_2
        ) return boolean {
            return fx_arePolygonsInside(p_polygonal_region_1, p_polygonal_region_2);
        }
        
        /**
         * @desc    Check that given location is valid
         * @param   p_location    location to be checked
         * @return  true on success, false otherwise
         */
        function f_isValidTwoDLocation(