diff --git a/guest_tools/attestation_sdk/README.md b/guest_tools/attestation_sdk/README.md index fc7a14ac8..9e9cb7b61 100644 --- a/guest_tools/attestation_sdk/README.md +++ b/guest_tools/attestation_sdk/README.md @@ -18,6 +18,7 @@ The Attestation SDK offers developers easy-to-use APIs for implementing attestat - [How to do Perform Attestation](#how-to-do-perform-attestation-1) - [Building Attestation SDK](#building-attestation-sdk) - [APIs](#apis) + - [End-User License Agreement](#end-user-license-agreement) ## Features @@ -53,12 +54,14 @@ If you choose to install the Attestation SDK from the source code instead of a W - Driver version r535 installed. - Ensure that the SKU is supported for Confidential Computing. -2. Follow the instructions in nvTrust/guest_tools/local_gpu_verifier/README.md to install the NVIDIA GPU Local Verifier Python SDK. +2. Install Python 3.7 or later. + +3. Follow the instructions in nvTrust/guest_tools/local_gpu_verifier/README.md to install the NVIDIA GPU Local Verifier Python SDK. -3. Run the following command and ensure that you have the 'verifier' Python module installed. +4. Run the following command and ensure that you have the 'verifier' Python module installed. ``` - pip list | grep verifier - verifier 1.1.0 + pip list | grep nv-local-gpu-verifier + nv-local-gpu-verifier 1.4.0 ``` ### Local GPU Attestation @@ -111,5 +114,6 @@ Please refer to the [sample implementation](tests/RemoteGPUTest.py) | generate_evidence(<-nonce->) | Generate GPU attestation evidence using the Local GPU Verifier Python SDK with a user-provided nonce. | | verify_evidence(<-nonce->, <-evidence->,<-nras_url->) |Verify the evidence with the NVIDIA Remote Attestation Service (NRAS) | +# End-user License Agreement - +By using the Attestation Suite Services, you affirm that you have read the Agreement and agree to its terms. If you do not have the required authority to enter into the Agreement or if you do not accept all Agreement terms and conditions, do not use the Attestation Suite Services. Please see the [End-user License Agreement](https://docs.attestation.nvidia.com/EULA/eula.html) for more information on data collection. diff --git a/guest_tools/attestation_sdk/pyproject.toml b/guest_tools/attestation_sdk/pyproject.toml index 4907c2571..e9bba8604 100644 --- a/guest_tools/attestation_sdk/pyproject.toml +++ b/guest_tools/attestation_sdk/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "nv-attestation-sdk" -version = "1.3.0" +version = "1.4.0" authors = [ {name = "NVIDIA"}, ] @@ -14,7 +14,7 @@ classifiers = [ ] dependencies = [ 'pyjwt ~= 2.7.0', - 'verifier >= 1.2.0', + 'nv-local-gpu-verifier >= 1.2.0', 'requests ~= 2.31.0' ] keywords = [ diff --git a/guest_tools/attestation_sdk/src/nv_attestation_sdk/attestation.py b/guest_tools/attestation_sdk/src/nv_attestation_sdk/attestation.py index 1dc7262c1..809955212 100644 --- a/guest_tools/attestation_sdk/src/nv_attestation_sdk/attestation.py +++ b/guest_tools/attestation_sdk/src/nv_attestation_sdk/attestation.py @@ -55,25 +55,49 @@ def __new__(cls, name=None): @classmethod def set_name(cls, name: str) -> None: + """Set the name of the Attestation client + + Args: + name (str): Attestation client name + """ cls._name = name @classmethod def get_name(cls) -> str: + """Get the name of the Attestation client + + Returns: + str: Attestation client name + """ return cls._name @classmethod def set_nonce_server(cls, url: str) -> None: + """Set nonce server URL (not used yet) + + Args: + url (str): URL of the nonce server + """ cls._nonceServer = url @classmethod def get_nonce_server(cls) -> str: + """Get the nonce Server URL + + Returns: + str: URL of the nonce server + """ return cls._nonceServer @classmethod def add_verifier(cls, dev: Devices, env: Environment, url: str, evidence: str) -> None: - """ - Add a new verifier to SDK configuration. - This will be used during attest and validate_token methods. + """Add a new verifier for Attestation + + Args: + dev (Devices): Type of device to be attestated - GPU, CPU etc. + env (Environment): Type of Attestation - local, remote etc. + url (str): URL of the Attestation Server for Remote Attestation use cases. + evidence (str): Attestation evidence """ if (dev == Devices.GPU and env == Environment.LOCAL) : name = "LOCAL_GPU_CLAIMS" @@ -89,26 +113,21 @@ def add_verifier(cls, dev: Devices, env: Environment, url: str, evidence: str) - @classmethod def get_verifiers(cls) -> list: - """ - Get the list of configured verifiers. + """Get a list of configured verifiers + + Returns: + list: List of verifiers """ return cls._verifiers @classmethod def attest(cls) -> bool: + """Attest the client as per the configured verifiers and evidence policy + + Returns: + bool: Attestation Result """ - Attest the client as per the configured verifiers and evidence policy - """ - # this should consist of doing the following things - # Nonce _generateNonce() - # Evidence generateEvidence(nonce) - # Retrieve quote from vTPM (locally) - # Token verifyEvidence(evidence) - # Evidence -> verifier, validated against policy, returns token - # Status provideEvidence(token) - # Token -> relying party, returns Status - # cls.token = "" for verifier in cls._verifiers: attest_result = True @@ -147,7 +166,6 @@ def attest(cls) -> bool: # NOTE: no verifiers means attestation will be true. weird but makes some sense # NOTE: THIS is where the tokens should be combined in to a single token and then set - #print("full attest_result ... ", attest_result) # NOTE: put a try catch here eatToken = cls._create_EAT() cls.set_token( cls._name, eatToken) @@ -194,11 +212,25 @@ def _create_EAT(cls) -> str: @classmethod def set_token(cls, name: str, eat_token: str) -> None: + """Set result EAT token for a client + + Args: + name (str): Attestation Client name + eat_token (str): EAT token + """ entry = {name: eat_token} cls._tokens.update(entry) @classmethod def get_token(cls, x=None) -> str: + """Get the Attestation EAT token for a client + + Args: + x (_type_, optional): Client name. Defaults to None. + + Returns: + str: EAT token in string format + """ name = "" if x == None: name = cls.get_name() @@ -216,6 +248,15 @@ def get_token(cls, x=None) -> str: @classmethod def _validate_token_internal(cls, policy:str, eat_token: str) -> bool: + """Validate a EAT token using the policy + + Args: + policy (str): Appraisal policy for Attestation results + eat_token (str): EAT token + + Returns: + bool: result + """ attest_result = True if eat_token == "": @@ -268,7 +309,6 @@ def get_verifier_by_name(cls, verifier_name): @classmethod def validate_token(cls, policy:str , x=None) : - if x == None: name = cls.get_name() if name == "": diff --git a/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_local.py b/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_local.py index 8feba1a63..cd8bfb3dd 100644 --- a/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_local.py +++ b/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_local.py @@ -11,8 +11,20 @@ from nv_attestation_sdk import attestation from urllib.parse import urlparse from nv_attestation_sdk.gpu import gpu_utils +from ..utils.config import GPU_ARCH, OCSP_SERVICE_URL, RIM_SERVICE_URL, ALLOW_HOLD_CERT + def validate_gpu_token(verifier, gpu_token: str, policy: str): + """Validate GPU token using a policy + + Args: + verifier (_type_): verifier object + gpu_token (str): EAT token + policy (str): Appraisal policy for attestation results + + Returns: + bool: result + """ if policy == "" or gpu_token == "": return False decoded_token = jwt.decode(gpu_token, algorithms='HS256', verify=False, key="secret") @@ -20,6 +32,14 @@ def validate_gpu_token(verifier, gpu_token: str, policy: str): return gpu_utils.validate_gpu_token_with_policy(decoded_token, auth_rules) def attest(nonce): + """Attest a device locally + + Args: + nonce (str): Nonce as hex string + + Returns: + Attestation result and JWT token + """ attestation_result = False from verifier import cc_admin jwt_token = "" @@ -30,9 +50,9 @@ def attest(nonce): "vbios_rim": None, "user_mode": True, 'rim_root_cert': None, - 'rim_service_url': None, - 'allow_hold_cert': True, - 'ocsp_url': None, + 'rim_service_url': RIM_SERVICE_URL, + 'allow_hold_cert': ALLOW_HOLD_CERT, + 'ocsp_url': OCSP_SERVICE_URL, 'nonce': nonce} attestation_result, jwt_token = cc_admin.attest(params) except Exception as e: @@ -53,7 +73,7 @@ def build_payload(nonce, evidence, cert_chain): encoded_evidence = base64.b64encode(encoded_evidence_bytes) encoded_evidence = encoded_evidence.decode('utf-8') data['evidence'] = encoded_evidence - data['arch'] = 'HOPPER' + data['arch'] = GPU_ARCH data['certificate'] = str(cert_chain) payload = json.dumps(data) return payload diff --git a/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_remote.py b/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_remote.py index 01f92ca2d..319987f99 100644 --- a/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_remote.py +++ b/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/attest_gpu_remote.py @@ -12,16 +12,48 @@ from urllib.parse import urlparse from nv_attestation_sdk.gpu import gpu_utils -def attest(nonce, verifierUrl): +from ..utils.config import REMOTE_VERIFIER_URL, GPU_ARCH + + +def attest(nonce: str, verifierUrl: str): + """Attest a device using the remote Attestation URL + + Args: + nonce (str): Nonce as hex string + verifierUrl (str): Verifier URL + + Returns: + Attestation result and JWT token + """ gpu_evidence_list = generate_evidence(nonce) return verify_evidence(nonce, gpu_evidence_list, verifierUrl) -def create_jwks_url(verifier_url:str): + +def create_jwks_url(verifier_url: str) -> str: + """Generate JWKS URL using the verifier URL + + Args: + verifier_url (str): Verifier URL + + Returns: + str: JWKS URL + """ parsed_url = urlparse(verifier_url) jwks_url = parsed_url.scheme + "://" + parsed_url.netloc + "/" + ".well-known/jwks.json" return jwks_url -def validate_gpu_token(verifier, gpu_token: str, policy: str): + +def validate_gpu_token(verifier, gpu_token: str, policy: str) -> bool: + """Validate GPU token using a policy + + Args: + verifier (_type_): verifier object + gpu_token (str): EAT token + policy (str): Appraisal policy for attestation results + + Returns: + bool: result + """ verifier_url = verifier[attestation.VerifierFields.URL] jwks_url = create_jwks_url(verifier_url) print("***** Validating Signature using JWKS endpont " + jwks_url + " ****** ") @@ -57,40 +89,64 @@ def validate_gpu_token(verifier, gpu_token: str, policy: str): gpu_token, cert.public_key(), algorithms=["ES384"], - options={'verify_iat': False,'verify_nbf': False} + options={'verify_iat': False, 'verify_nbf': False} ) json_formatted_str = json.dumps(decoded_token, indent=2) - print("Decoded Token " , str(json_formatted_str)) + print("Decoded Token ", str(json_formatted_str)) print("***** JWT token signature is valid. *****") auth_rules = gpu_utils.get_auth_rules(policy) return gpu_utils.validate_gpu_token_with_policy(decoded_token, auth_rules) except jwt.ExpiredSignatureError: print("JWT token has expired.") except jwt.InvalidTokenError as e: - print("JWT token signature is invalid.", repr(e )) + print("JWT token signature is invalid.", repr(e)) else: print("No matching key or x5c key found for the provided kid.") return False + def generate_evidence(nonce=""): + """Generate GPU evidence + + Args: + nonce (str, optional): Nonce represented as hex string. Defaults to "". + + Returns: + _type_: GPU evidence + """ print("generate_evidence") from verifier import cc_admin gpu_evidence_list = cc_admin.collect_gpu_evidence(nonce) return gpu_evidence_list -def verify_evidence(nonce, gpu_evidence_list, verifierUrl="https://nras.attestation.nvidia.com/v1/attest/gpu"): + +def verify_evidence(nonce: str, gpu_evidence_list, verifier_url): + """Verify GPU evidence with the Remote Verifier + + Args: + nonce (_type_): Nonce represented as hex string + gpu_evidence_list (_type_): GPU Evidence list + verifierUrl (str, optional): Verifier URL. Defaults to "https://nras.attestation.nvidia.com/v1/attest/gpu". + + Returns: + _type_: _description_ + """ + if not verifier_url: + verifier_url = REMOTE_VERIFIER_URL + attestation_result = False jwt_token = "" headers = { 'Content-Type': 'application/json' } try: - for i , gpu_evidence in enumerate(gpu_evidence_list): + for i, gpu_evidence in enumerate(gpu_evidence_list): gpu_evidence = gpu_evidence_list[i] current_gpu_status = False - payload = build_payload(nonce, gpu_evidence['attestationReportHexStr'],gpu_evidence['certChainBase64Encoded']) + payload = build_payload(nonce, gpu_evidence['attestationReportHexStr'], + gpu_evidence['certChainBase64Encoded']) print("Calling NRAS to attest GPU evidence...") - response = requests.request("POST", verifierUrl, headers=headers, data=payload) + response = requests.request("POST", verifier_url, headers=headers, data=payload) reponse_json = response.json() if response.status_code == 200: print("**** Attestation Successful ****") @@ -109,15 +165,15 @@ def verify_evidence(nonce, gpu_evidence_list, verifierUrl="https://nras.attestat print("\tException: ", e) return attestation_result, jwt_token + def build_payload(nonce, evidence, cert_chain): data = dict() data['nonce'] = nonce - encoded_evidence_bytes = evidence.encode("ascii") - encoded_evidence = base64.b64encode(encoded_evidence_bytes) - encoded_evidence = encoded_evidence.decode('utf-8') + encoded_evidence_bytes = evidence.encode("ascii") + encoded_evidence = base64.b64encode(encoded_evidence_bytes) + encoded_evidence = encoded_evidence.decode('utf-8') data['evidence'] = encoded_evidence - data['arch'] = 'HOPPER' + data['arch'] = GPU_ARCH data['certificate'] = str(cert_chain) payload = json.dumps(data) return payload - diff --git a/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/gpu_utils.py b/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/gpu_utils.py index 9dbd8210d..04228deed 100644 --- a/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/gpu_utils.py +++ b/guest_tools/attestation_sdk/src/nv_attestation_sdk/gpu/gpu_utils.py @@ -1,6 +1,15 @@ import json -def validate_gpu_token_with_policy(token: str, auth_rules: str): +def validate_gpu_token_with_policy(token: str, auth_rules: str) -> bool: + """Validate GPU token using a policy + + Args: + token (str): EAT token + auth_rules (str): policy + + Returns: + bool: result + """ for key in auth_rules: if key in token: if type(auth_rules[key]) is dict: @@ -14,7 +23,15 @@ def validate_gpu_token_with_policy(token: str, auth_rules: str): return False return True -def get_auth_rules(policy: str): +def get_auth_rules(policy: str) -> str: + """Extract Auth rule from the policy + + Args: + policy (str): Policy + + Returns: + str: Auth rules + """ if policy == "": return None policy_obj = json.loads(policy) diff --git a/guest_tools/attestation_sdk/src/nv_attestation_sdk/utils/config.py b/guest_tools/attestation_sdk/src/nv_attestation_sdk/utils/config.py new file mode 100644 index 000000000..7c3694205 --- /dev/null +++ b/guest_tools/attestation_sdk/src/nv_attestation_sdk/utils/config.py @@ -0,0 +1,6 @@ +RIM_SERVICE_URL = "https://rim.attestation.nvidia.com/v1/rim/" +ALLOW_HOLD_CERT = True +OCSP_SERVICE_URL = "https://ocsp.ndis.nvidia.com/" +REMOTE_VERIFIER_URL = "https://nras.attestation.nvidia.com/v1/attest/gpu" +# Planned to move the below to a list of acceptable GPU architectures +GPU_ARCH = "HOPPER" diff --git a/guest_tools/gpu_verifiers/local_gpu_verifier/README.md b/guest_tools/gpu_verifiers/local_gpu_verifier/README.md index e0262e424..f7922d87d 100644 --- a/guest_tools/gpu_verifiers/local_gpu_verifier/README.md +++ b/guest_tools/gpu_verifiers/local_gpu_verifier/README.md @@ -2,69 +2,58 @@ The Verifier is a Python-based tool that validates GPU measurements by comparing an authenticated attestation report containing runtime measurements with authenticated golden measurements. Its purpose is to verify if the software and hardware state of the GPU are in accordance with the intended state. -NOTE: Version 1.0.0 is currently in the Early Access Release (beta) stage, and please note that the APIs are subject to change until the General Availability (GA) release. - -NOTE: In order to use the Verifier tool, please make sure that the confidential compute (CC) is enabled in the system. +## Pre-requisites: + Requires Python 3.7 or later. ## Install -### Create a new Python Virtual Env [Optional] - - python3 -m venv ./prodtest - source ./prodtest/bin/activate +### Step 1: Elevate to Root User Privileges (Optional) -### Install and run Local GPU Verifier as a root user - -If the user wants to run the verifier to set the GPU Ready State based on the Attestation results, they will need to install and execute the tool with administrative privileges (e.g., as a superuser or using root privileges). - - cd local_gpu_verifier - sudo pip3 install . - sudo python3 -m verifier.cc_admin +If you want the verifier to set the GPU Ready State based on the Attestation results, you will need to elevate the user privilegs to root before you execute the rest of the instructions. For use cases where the user does not intend to set the GPU Ready State (e.g., when using the Attestation SDK), you can install and run the Verifier tool without requiring sudo privileges. -Note: If you encounter issues while building the package, please execute the following commands to update to the latest versions of setuptools and pip: + sudo -i - sudo python3 -m pip install --upgrade setuptools - sudo pip install -U pip +### Step 2: Create a new Python Virtual Environment -### Install and run Local GPU Verifier as a non-root user + python3 -m venv ./prodtest + source ./prodtest/bin/activate -For use cases where the user does not intend to set the GPU Ready State (e.g., when using the Attestation SDK), you can install and run the Verifier tool without requiring sudo privileges. +### Step 3: Install and run Local GPU Verifier cd local_gpu_verifier pip3 install . python3 -m verifier.cc_admin -If you encounter any permission issues while building the package, please execute the following commands and then build the package again +### Troubleshooting Installation Issues - cd local_gpu_verifier - rm -r build +- If you encounter any pip related issues while building the package, please execute the following commands to update to the latest versions of setuptools and pip -If you encounter any pip related issues while building the package, please execute the following commands to update to the latest versions of setuptools and pip + python3 -m pip install --upgrade setuptools + pip install -U pip - python3 -m pip install --upgrade setuptools - pip install -U pip +- If you encounter any permission issues while building the package, please execute the following commands and then build the package again + cd local_gpu_verifier + rm -r build ## Usage To run the cc_admin module, use the following command: python3 -m verifier.cc_admin [-h] [-v] [--test_no_gpu] [--driver_rim DRIVER_RIM] [--vbios_rim VBIOS_RIM] [--user_mode] [--nonce] [--allow_hold_cert] - options: - -h, --help show this help message and exit - -v, --verbose Print more detailed output. - --test_no_gpu If there is no gpu and we need to test the verifier, then no nvml apis will be available so, the verifier will use a hardcoded gpu info. - --driver_rim DRIVER_RIM - The path to the driver RIM. If not provided, it will use the default file : "/usr/share/nvidia/rim/RIM_GH100PROD.swidtag" - --vbios_rim VBIOS_RIM - The path to the VBIOS RIM. If not provided, it will try to find the appropriate file in verifier_cc/samples/ directory for the VBIOS ROM flashed onto the GPU. - --user_mode Runs the gpu attestation in user mode. - --allow_hold_cert If the user wants to continue the attestation in case of the OCSP revocation status of the certificate in the RIM files is 'certificate_hold' - --nonce Specify a Nonce for Attestation Report - --rim_root_cert RIM_ROOT_CERT - The absolute path to the root certificate to be used for verifying the certificate chain of the driver and vBIOS RIM certificate chain - --rim_service_url RIM_SERVICE_URL - The URL to be used for fetching driver and vBIOS RIM files. eg: https://rim.nvidia.com/rims/ +| Option | Description | +|---------------------------|---------------------------------------------------------------------------------------------------------------------| +| `-h, --help` | Show this help message and exit | +| `-v, --verbose` | Print more detailed output | +| `--test_no_gpu` | If there is no GPU and we need to test the verifier, no NVML APIs will be available, so the verifier will use hardcoded GPU info | +| `--driver_rim DRIVER_RIM` | The path to the driver RIM. If not provided, it will use the default file: `/usr/share/nvidia/rim/RIM_GH100PROD.swidtag` | +| `--vbios_rim VBIOS_RIM` | The path to the VBIOS RIM. If not provided, it will try to find the appropriate file in `verifier_cc/samples/` directory for the VBIOS ROM flashed onto the GPU | +| `--user_mode` | Runs the GPU attestation in user mode | +| `--allow_hold_cert` | Continue attestation if the OCSP revocation status of the certificate in the RIM files is 'certificate_hold' | +| `--nonce` | Specify a Nonce for Attestation Report | +| `--rim_root_cert RIM_ROOT_CERT` | The absolute path to the root certificate to be used for verifying the certificate chain of the driver and VBIOS RIM certificate chain | +| `--rim_service_url RIM_SERVICE_URL` | The URL to be used for fetching driver and VBIOS RIM files (e.g., `https://rim.nvidia.com/rims/`) | + If you need information about any function, use @@ -83,8 +72,6 @@ of the base RIM. The RIM (Reference Integrity Manifest) is a manifest containing golden measurements for the GPU. You can find the TCG RIM Spec at the following link: [TCG RIM Spec](https://trustedcomputinggroup.org/wp-content/uploads/TCG_RIM_Model_v1p01_r0p16_pub.pdf). The RIM module performs the parsing and schema validation of the base RIM against the SWID tag schema and XML signature schema. It then performs the signature verification of the base RIM. - - ### attestation The Attestation module is capable of extracting the measurements and the measurement signature. It then performs signature verification. DMTF's SPDM 1.1 MEASUREMENT response message is used as the attestation report for APM. You can find the SPDM 1.1 specification at the following link: [SPDM 1.1 Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0274_1.1.3.pdf). @@ -96,4 +83,3 @@ The verifier module utilizes the RIM (Runtime Integrity Measurement) attestation ### cc_admin The cc_admin module retrieves the GPU information, attestation report, and the driver RIM associated with the driver version. It then proceeds with the authentication of the driver RIM and the attestation report. Afterward, it executes the verifier tool to compare the runtime measurements in the attestation report with the golden measurements stored in the driver RIM. - diff --git a/guest_tools/gpu_verifiers/local_gpu_verifier/pyproject.toml b/guest_tools/gpu_verifiers/local_gpu_verifier/pyproject.toml index 79664d2ca..5adbb55ba 100644 --- a/guest_tools/gpu_verifiers/local_gpu_verifier/pyproject.toml +++ b/guest_tools/gpu_verifiers/local_gpu_verifier/pyproject.toml @@ -1,7 +1,7 @@ [project] -name = "verifier" -version = "1.3.0" -description = "A Python-based tool that validates GPU measurements by comparing GPU runtime measurements with authenticated golden measurements" +name = "nv-local-gpu-verifier" +version = "1.4.0" +description = "A Python-based tool that validates GPU measurements by comparing GPU runtime measurements with authenticated golden measurements." authors = [ {name = "NVIDIA"} ] diff --git a/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/cc_admin_utils.py b/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/cc_admin_utils.py index 15c4b2922..7cfa9d4a9 100755 --- a/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/cc_admin_utils.py +++ b/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/cc_admin_utils.py @@ -75,10 +75,10 @@ def extract_fwid(cert): """ A static function to extract the FWID data from the given certificate. Args: - cert (OpenSSL.crypto.X509): The certificate whose FWID data is needed to be fetched. + cert (OpenSSL.crypto.X509): The certificate whose FWID data is needed to be fetched. Returns: - [str]: the FWID as a hex string extracted from the certificate if + [str]: the FWID as a hex string extracted from the certificate if it is present otherwise returns an empty string. """ result = '' @@ -127,7 +127,7 @@ def verify_certificate_chain(cert_chain, settings, mode): cert at the end of the list. settings (config.HopperSettings): the object containing the various config info. mode (): Used to determine if the certificate chain - verification is for the GPU attestation certificate chain or RIM certificate chain + verification is for the GPU attestation certificate chain or RIM certificate chain or the ocsp response certificate chain. Raises: @@ -194,7 +194,7 @@ def ocsp_certificate_chain_validation(cert_chain, settings, mode): cert_chain (list): the list of the input certificates of the certificate chain. settings (config.HopperSettings): the object containing the various config info. mode (): Used to determine if the certificate chain - verification is for the GPU attestation certificate chain or RIM certificate chain + verification is for the GPU attestation certificate chain or RIM certificate chain or the ocsp response certificate chain. Returns: @@ -212,7 +212,7 @@ def ocsp_certificate_chain_validation(cert_chain, settings, mode): for i, cert in enumerate(cert_chain): cert_chain[i] = cert.to_cryptography() - + for i in range(start_index, end_index): request_builder = ocsp.OCSPRequestBuilder() request_builder = request_builder.add_certificate(cert_chain[i], cert_chain[i + 1], SHA384()) @@ -231,7 +231,7 @@ def ocsp_certificate_chain_validation(cert_chain, settings, mode): buffer = ocsp_response.certificates[0].public_bytes(serialization.Encoding.DER)) ocsp_cert_chain = [ocsp_response_leaf_cert] - + for j in range(i, len(cert_chain)): ocsp_cert_chain.append(CcAdminUtils.convert_cert_from_cryptography_to_pyopenssl(cert_chain[j])) @@ -262,12 +262,16 @@ def ocsp_certificate_chain_validation(cert_chain, settings, mode): info_log.error("\t\tCouldn't receive a proper response from the OCSP server.") return False + #OCSP response can have 3 status - Good, Revoked (with a reason) or Unknown if ocsp_response.certificate_status != ocsp.OCSPCertStatus.GOOD: if x509.ReasonFlags.certificate_hold == ocsp_response.revocation_reason and \ BaseSettings.allow_hold_cert and \ (mode == BaseSettings.Certificate_Chain_Verification_Mode.DRIVER_RIM_CERT or BaseSettings.Certificate_Chain_Verification_Mode.VBIOS_RIM_CERT): info_log.warning(f"\t\t\tWARNING: THE CERTIFICATE {cert_chain[i].subject.get_attributes_for_oid(x509.oid.NameOID.COMMON_NAME)[0].value} IS REVOKED WITH THE STATUS AS 'CERTIFICATE_HOLD'.") revoked_status = True + elif ocsp_response.certificate_status == ocsp.OCSPCertStatus.UNKNOWN: + info_log.error(f"\t\t\tTHE {cert_chain[i].subject.get_attributes_for_oid(x509.oid.NameOID.COMMON_NAME)[0].value} certificate revocation status is UNKNOWN") + return False else: info_log.error(f"\t\t\tTHE {cert_chain[i].subject.get_attributes_for_oid(x509.oid.NameOID.COMMON_NAME)[0].value} IS REVOKED FOR REASON : {ocsp_response.revocation_reason}") return False @@ -291,7 +295,7 @@ def send_ocsp_request(data): [cryptography.hazmat.backends.openssl.ocsp._OCSPResponse]: the ocsp response message object. """ if not BaseSettings.OCSP_URL.lower().startswith('https'): - # Raising exception in case of url not starting with http, and not FTP, etc. + # Raising exception in case of url not starting with http, and not FTP, etc. raise ValueError from None https_request = request.Request(BaseSettings.OCSP_URL, data) @@ -346,12 +350,12 @@ def fetch_rim_file(file_id): decoded_str = base64.b64decode(base64_data) return decoded_str.decode('utf-8') except HTTPError: - raise RIMFetchError("Could not fetch the rim file : " + file_id) + raise RIMFetchError("Could not fetch the rim file : " + file_id) @staticmethod def get_vbios_rim_file_id(project, project_sku, chip_sku, vbios_version): - """ A static method to generate the required VBIOS RIM file id which needs to be fetched from the RIM service - according to the vbios flashed onto the system. + """ A static method to generate the required VBIOS RIM file id which needs to be fetched from the RIM service + according to the vbios flashed onto the system. Args: attestation_report (AttestationReport): the object representing the attestation report. @@ -365,8 +369,8 @@ def get_vbios_rim_file_id(project, project_sku, chip_sku, vbios_version): @staticmethod def get_driver_rim_file_id(driver_version): - """ A static method to generate the driver RIM file id to be fetched from the RIM service corresponding to - the driver installed onto the system. + """ A static method to generate the driver RIM file id to be fetched from the RIM service corresponding to + the driver installed onto the system. Args: driver_version (str): the driver version of the installed driver. @@ -442,14 +446,14 @@ def verify_attestation_report(attestation_report_obj, gpu_leaf_certificate, nonc assert isinstance(gpu_leaf_certificate, crypto.X509) assert isinstance(nonce, bytes) and len(nonce) == settings.SIZE_OF_NONCE_IN_BYTES - # Here the attestation report is the concatenated SPDM GET_MEASUREMENTS request with the SPDM GET_MEASUREMENT response message. + # Here the attestation report is the concatenated SPDM GET_MEASUREMENTS request with the SPDM GET_MEASUREMENT response message. request_nonce = attestation_report_obj.get_request_message().get_nonce() - + if len(nonce) > settings.SIZE_OF_NONCE_IN_BYTES or len(request_nonce) > settings.SIZE_OF_NONCE_IN_BYTES: err_msg = "\t\t Length of Nonce is greater than max nonce size allowed." event_log.error(err_msg) raise InvalidNonceError(err_msg) - + # compare the generated nonce with the nonce of SPDM GET MEASUREMENT request message in the attestation report. if request_nonce != nonce: err_msg = "\t\tThe nonce in the SPDM GET MEASUREMENT request message is not matching with the generated nonce." @@ -530,7 +534,7 @@ def validate_and_extract_nonce(nonce_hex_string): return bytes.fromhex(nonce_hex_string) else : raise InvalidNonceError("Invalid Nonce Size. The nonce should be 32 bytes in length represented as Hex String") - + def __init__(self, number_of_gpus): """ It is the constructor for the CcAdminUtils. diff --git a/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/rim/swidSchema2015.xsd b/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/rim/swidSchema2015.xsd index 2112ebd40..f367cb6ad 100755 --- a/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/rim/swidSchema2015.xsd +++ b/guest_tools/gpu_verifiers/local_gpu_verifier/src/verifier/rim/swidSchema2015.xsd @@ -1 +1 @@ - Schema for ISO-IEC 19770-2 Software Identification Tags http://standards.iso.org/iso/19770/-2/2015/schema.xsd Copyright 2015 ISO/IEC, all rights reserved Copyright notice: ISO and IEC grant the users of this Standard the right to use this XSD file free of charge for the purpose of implementing the present Standard. Disclaimer: In no event shall ISO and/or IEC be liable for any damages whatsoever (including, but not limited to, damages for loss of profits, business interruption, loss of information, or any other pecuniary loss) arising out of or related to the use of or inability to use the XSD file. ISO and IEC disclaim all warranties, express or implied, including but not limited to warranties of merchantability and fitness for a particular purpose. 2.0 Represents the root element specifying data about a software component Attributes common to all Elements in this schema Allow xml:lang attribute on any element. Allows any undeclared attributes on any element as long as the attribute is placed in a different namespace. Specifies the organizations related to the software component referenced by this SWID tag. An open-ended collection of elements that can be used to attach arbitrary metadata to an Entity. The name of the organization claiming a particular role in the SWID tag. The regid of the organization. If the regid is unknown, the value "invalid.unavailable" is provided by default (see RFC 6761 for more details on the default value). The relationship between this organization and this tag e.g. tag, softwareCreator, licensor, tagCreator, etc. The role of tagCreator is required for every SWID tag. EntityRole may include any role value, but the pre-defined roles include: aggregator, distributor, licensor, softwareCreator, tagCreator Other roles will be defined as the market uses the SWID tags. this value provides a hexadecimal string that contains a hash (or thumbprint) of the signing entities certificate. The element is used to provide results from a scan of a system where software that does not have a SWID tag is discovered. This information is not provided by the software creator, and is instead created when a system is being scanned and the evidence for why software is believed to be installed on the device is provided in the Evidence element. Date and time the evidence was gathered. Identifier for the device the evidence was gathered from. Represents an individual file Files that are considered important or required for the use of a software component. Typical key files would be those which, if not available on a system, would cause the software not to execute. Key files will typically be used to validate that software referenced by the SWID tag is actually installed on a specific computing device The directory or location where a file was found or can expected to be located. does not include the filename itself. This can be relative path from the 'root' attribute. The filename without any path characters A system-specific root folder that the 'location' attribute is an offset from. If this is not specified the assumption is the 'root' is the same folder as the location of the SWIDTAG. Permits any user-defined attributes in file tags Provides the ability to apply a directory structure to the files defined in a Payload or Evidence element. A Directory element allows one or more directories to be defined in the file structure. A File element that allows one or more files to be specified for a given location. Represents an individual file The file size in bytes of the file The file version Provides process information for data that will show up in a devices process table. The process name as it will be found in the devices process table. The process ID for the executing process - note that this will typically only be provided when the Process element is included as part of Evidence. A container that can be used to provide arbitrary resource information about an application installed on a device, or evidence collected from a device. The type of resource (ie, registrykey, port, rootUrl) This type is used by Payload to provide details on what may rbe installed on a device, and by Evidence to indicate what an inventory process discovered on a device. One or more directory elements One or more File elements One or more Process elements One or more generic resource elements A reference to any another item (can include details that are related to the SWID tag such as details on where software downloads can be found, vulnerability database associations, use rights, etc). This is modeled directly to match the HTML [LINK] element; it is critical for streamlining software discovery scenarios that these are kept consistent. For installation media (rel="installationmedia") - dictates the canonical name for the file. Items with the same artifact name should be considered mirrors of each other (so download from wherever works). The link to the item being referenced. The href can point to several different things, and can be any of the following: - a RELATIVE URI (no scheme) - which is interpreted depending on context (ie, "./folder/supplemental.swidtag" ) - a physical file location with any system-acceptable URI scheme (ie, file:// http:// https:// ftp:// ... etc ) - an URI with "swid:" as the scheme, which refers to another swid by tagId. This URI would need to be resolved in the context of the system by software that can lookup other swidtags.( ie, "swid:2df9de35-0aff-4a86-ace6-f7dddd1ade4c" ) - an URI with "swidpath:" as the scheme, which refers to another swid by an XPATH query. This URI would need to be resolved in the context of the system by software that can lookup other swidtags, and select the appropriate one based on an XPATH query. Examples: swidpath://SoftwareIdentity[Entity/@regid='http://contoso.com'] would retrieve all swidtags that had an entity where the regid was Contoso swidpath://SoftwareIdentity[Meta/@persistentId='b0c55172-38e9-4e36-be86-92206ad8eddb'] would retrieve swidtags that matched the persistentId See XPATH query standard : http://www.w3.org/TR/xpath20/ An attribute defined by the W3C Media Queries Recommendation (see http://www.w3.org/TR/css3-mediaqueries/). A hint to the consumer of the link to what the target item is applicable for. Determines the relative strength of ownership of the target piece of software. The relationship between this SWID and the target file. Relationships can be identified by referencing the IANA registration library - https://www.iana.org/assignments/link-relations/link-relations.xhtml. The IANA MediaType for the target file; this provides the consumer with intelligence of what to expect. See http://www.iana.org/assignments/media-types/media-types.xhtml for more details on link type. Determines if the target software is a hard requirement or not An open-ended collection of key/value data related to this SWID. Permits any user-defined attributes in Meta tags Specifies the organizations related to the software component referenced by this SWID tag. This has a minOccurs of 1 because the spec declares that you must have at least a Entity with role='tagCreator' This element is used to provide results from a scan of a system where software that does not have a SWID tag is discovered. This information is not provided by the software creator, but is instead created when a system is being scanned and the evidence for why software is believed to be installed on the device is provided in the Evidence element. A reference to any another item (can include details that are related to the SWID tag such as details on where software downloads can be found, vulnerability database associations, use rights, etc). Note: This is modelled directly to match the HTML [LINK] element; it is critical for streamlining software discovery scenarios that these are kept consistent. An open-ended collection of key/value data related to this SWID. The items that may be installed on a device when the software is installed. Note that Payload may be a superset of the items installed and, depending on optimization systems for a device, may or may not include every item that could be created or executed on a device when software is installed. In general, payload will be used to indicate the files that may be installed with a software product and will often be a superset of those files (i.e. if a particular optional component is not installed, the files associated with that component may be included in payload, but not installed on the device). Allows any undeclared elements in the SoftwareIdentity element as long as the element is placed in a different namespace. As xs:any supercedes an xs:element declaration, this continues to support digital signatures using the ds:Signature element: Signatures are not a mandatory part of the software identification tag standard, and can be used as required by any tag producer to ensure that sections of a tag are not modified and/or to provide authentication of the signer. If signatures are included in the software identification tag, they shall follow the W3C recommendation defining the XML signature syntax which provides message integrity authentication as well as signer authentication services for data of any type. Set to true, if this attribute specifies that this SWID tag is a collection of information that describes the pre-installation data of software component. Set to true if this SWID describes a product patch or modification to a different software element. media is a hint to the tag consumer to understand what this SWID tag applies to (see the [Link] tags media attribute). This attribute provides the software component name as it would typically be referenced. For example, what would be seen in the add/remove dialog on a Windows device, or what is specified as the name of a packaged software product or a patch identifier name on a Linux device. Specifies that this tag provides supplemental tag data that can be merged with primary tag data to create a complete record of the software information. Supplemental tags will often be provided at install time and may be provided by different entities (such as the tag consumer, or a Value Added Reseller). tagId shall be a globally unique identifier and should be assigned a GUID reference (see ISO/IEC 19770-5 definition for GUID). The tagID provides a unique reference for the specific product, version, edition, revision, etc (essentially, the same binary distribution). If two tagIDs match and the tagCreator is the same, the underlying products they represent are expected to be exactly the same. This allows IT systems to identify if a software item (for example, a patch) is installed simply by referencing the specific tagID value which is likely to be readily available in a software inventory. It is recommended, when possible, that a 16 byte GUID be used for this field as this provides global uniqueness without a significant amount of overhead for space. If use of a 16 byte GUID is not possible, a text based globally unique ID may be constructed, this ID should include a unique naming authority for the tagCreator and sufficient additional details that the tagId is unique for the software product, version, edition, revision, etc. This would likely look as follows (+ is used as a string concatenation symbol): regid + productName + version + edition + revision + ... The tagVersion indicates if a specific release of a software product has more than one tag that can represent that specific release. This may be the case if a software tag producer creates and releases an incorrect tag that they subsequently want to fix, but with no underlying changes to the product the SWID tag represents. This could happen if, for example, a patch is distributed that has a Link reference that does not cover all the various software releases it can patch. A newer SWID tag for that patch can be generated and the tagVersion value incremented to indicate that the data is updated. Underlying development version for the software component. Scheme used for the version number. Some possible common values are: value="alphanumeric" Strictly a string, sorting alphanumericaly value="decimal" A floating point number : ( ie, 1.25 is less than 1.3 ) value="multipartnumeric" Numbers seperated by dots, where the numbers are interpreted as integers (ie, 1.2.3 , 1.4.5.6 , 1.2.3.4.5.6.7 ) value="multipartnumeric+suffix" Numbers seperated by dots, where the numbers are interpreted as integers with an additional string suffix: (ie, 1.2.3a) value="semver" Follows the semver.org spec value="unknown" Unknown, no attempt should be made to order these An open-ended collection of key/value data related to this SWID. The attributes included in this Element are predefined attributes to ensure common usage across the industry. The schema allows for any additional attribute to be included in a SWID tag, though it is recommended that industry norms for new attributes are defined and followed to the degree possible. Identification of the activation status of this software title (e.g. Trial, Serialized, Licensed, Unlicensed, etc). Typically, this is used in supplemental tags. Provides information on which channel this particular software was targeted for (e.g. Volume, Retail, OEM, Academic, etc). Typically used in supplemental tags. The informal or colloquial version of the product (i.e. 2013). Note that this version may be the same through multiple releases of a software product where the version specified in SoftwareEntity is much more specific and will change for each software release. Note that this representation of version is typically used to identify a group of specific software releases that are part of the same release/support infrastructure (i.e. Fabrikam Office 2013). This version is used for string comparisons only and is not compared to be an earlier or later release (that is done via the SoftwareEntity version). A longer, detailed description of the software. This description can be multiple sentences (differentiated from summary which is a very short, one-sentence description). The variation of the product (Extended, Enterprise, Professional, Standard etc) An indicator to determine if there should be accompanying proof of entitlement when a software license reconciliation is completed. A vendor-specific textual key that can be used to reconcile the validity of an entitlement. (e.g. serial number, product or license key). The name of the software tool that created a SWID tag. This element is typically used if tags are created on the fly, or based on a catalogue based analysis for data found on a computing device. A GUID used to represent products installed where the products are related, but may be different versions. See one representation of this value through the use of what, in a windows installation process is referred to as an upgradeCode - http://msdn.microsoft.com/en-us/library/aa372375(v=vs.85).aspx as one example of the use of this value. The base name of the product (e.g. Office, Creative Suites, Websphere, etc). The overall product family this software belongs to. Product family is not used to identify that a product is part of a suite, but is instead used when a set of products that are all related may be installed on multiple different devices. For example, an Enterprise backup system may consist of a backup server, multiple different backup systems that support mail servers, databases and ERP systems as well as individual software items that backup client devices. In this case all software titles that are part of the backup system would have the same productFamily name so they can be grouped together in reporting systems. The informal or colloquial representation of the sub-version of the given product (ie, SP1, R2, RC1, Beta 2, etc). Note that the SoftwareIdentity.version will provide very exact version details, the revision is intended for use in environments where reporting on the informal or colloquial representation of the software is important (for example, if for a certain business process, an organization recognizes that it must have ServicePack 1 or later of a specific product installed on all devices, they can use the revision data value to quickly identify any devices that do not meet this requirement). Depending on how a software organizations distributes revisions, this value could be specified in a primary (if distributed as an upgrade) or supplemental (if distributed as a patch) SWID tag. A short (one-sentence) description of the software. An 8 digit code that provides UNSPSC classification of the software product this SWID tag identifies. For more information see, http://www.unspsc.org/ The version of the UNSPSC code used to define the UNSPSC code value. For more information see, http://www.unspsc.org/. An expression that the document evaluator can use to determine if the target of the link is applicable to the current platform (the host environment) Used as an optimization hint to notify a system that it can ignore something when it's not likely to be used. The format of this string is modeled upon the MediaQuery definition at http://www.w3.org/TR/css3-mediaqueries/ This is one or more EXPRESSIONs where the items are connected with an OPERATOR: media="EXPRESSION [[OPERATOR] [EXPRESSION]...]" EXPRESSION is processed case-insensitive and defined either : (ENVIRONMENT) indicates the presence of the environment or ([PREFIX-]ENVIRONMENT.ATTRIBUTE:VALUE) indicates a comparison of an attribute of the environment. ENVIRONMENT is a text identifier that specifies any software,hardware feature or aspect of the system the software is intended to run in. Common ENVIRONMENTs include (but not limited to): linux windows java powershell ios chipset peripheral ATTRIBUTE is a property of an ENVIRONMENT with a specific value. Common attributes include (but not limited to): version vendor architecture PREFIX is defined as one of: MIN # property has a minimum value of VALUE MAX # property has a maximum value of VALUE if a PREFIX is not provided, then the property should equal VALUE OPERATOR is defined of one of: AND NOT Examples: media="(windows)" # applies to only systems that identify themselves as 'Windows' media="(windows) not (windows.architecture:x64)" # applies to only systems that identify # themselves as windows and are not for an x64 cpu media="(windows) and (min-windows.version:6.1)" # applies to systems that identify themselves as # windows and at least version 6.1 media="(linux) and (linux.vendor:redhat) and (min-linux.kernelversion:3.0)" # applies to systems that identify themselves as # linux, made by redhat and with a kernel version of at least 3.0 media="(freebsd) and (min-freebsd.kernelversion:6.6)" # applies to systems that identify themselves as # freebsd, with a kernel version of at least 6.6 media="(powershell) and (min-powershell.version:3.0)" # applies to systems that have powershell 3.0 or greater Properties are expected to be able to be resolved by the host environment without having to do significant computation. The IANA MediaType for the target href; this provides the SWID tag consumer with intelligence of what to expect. See http://www.iana.org/assignments/media-types/media-types.xhtml for more details on link type. Determines the relative strength of ownership of the target piece of software. If this is uninstalled, then the [Link]'d software should be removed too. If this is uninstalled, then the [Link]'d software should be removed if nobody else is sharing it Determines if the target software is a hard requirement. The [Link]'d software is absolutely required for installation Not absolutely required, but install unless directed not to Not absolutely required, install only when asked \ No newline at end of file + Schema for ISO-IEC 19770-2 Software Identification Tags http://standards.iso.org/iso/19770/-2/2015/schema.xsd Copyright 2015 ISO/IEC, all rights reserved Copyright notice: ISO and IEC grant the users of this Standard the right to use this XSD file free of charge for the purpose of implementing the present Standard. Disclaimer: In no event shall ISO and/or IEC be liable for any damages whatsoever (including, but not limited to, damages for loss of profits, business interruption, loss of information, or any other pecuniary loss) arising out of or related to the use of or inability to use the XSD file. ISO and IEC disclaim all warranties, express or implied, including but not limited to warranties of merchantability and fitness for a particular purpose. 2.0 Represents the root element specifying data about a software component Attributes common to all Elements in this schema Allows any undeclared attributes on any element as long as the attribute is placed in a different namespace. Specifies the organizations related to the software component referenced by this SWID tag. An open-ended collection of elements that can be used to attach arbitrary metadata to an Entity. The name of the organization claiming a particular role in the SWID tag. The regid of the organization. If the regid is unknown, the value "invalid.unavailable" is provided by default (see RFC 6761 for more details on the default value). The relationship between this organization and this tag e.g. tag, softwareCreator, licensor, tagCreator, etc. The role of tagCreator is required for every SWID tag. EntityRole may include any role value, but the pre-defined roles include: aggregator, distributor, licensor, softwareCreator, tagCreator Other roles will be defined as the market uses the SWID tags. this value provides a hexadecimal string that contains a hash (or thumbprint) of the signing entities certificate. The element is used to provide results from a scan of a system where software that does not have a SWID tag is discovered. This information is not provided by the software creator, and is instead created when a system is being scanned and the evidence for why software is believed to be installed on the device is provided in the Evidence element. Date and time the evidence was gathered. Identifier for the device the evidence was gathered from. Represents an individual file Files that are considered important or required for the use of a software component. Typical key files would be those which, if not available on a system, would cause the software not to execute. Key files will typically be used to validate that software referenced by the SWID tag is actually installed on a specific computing device The directory or location where a file was found or can expected to be located. does not include the filename itself. This can be relative path from the 'root' attribute. The filename without any path characters A system-specific root folder that the 'location' attribute is an offset from. If this is not specified the assumption is the 'root' is the same folder as the location of the SWIDTAG. Permits any user-defined attributes in file tags Provides the ability to apply a directory structure to the files defined in a Payload or Evidence element. A Directory element allows one or more directories to be defined in the file structure. A File element that allows one or more files to be specified for a given location. Represents an individual file The file size in bytes of the file The file version Provides process information for data that will show up in a devices process table. The process name as it will be found in the devices process table. The process ID for the executing process - note that this will typically only be provided when the Process element is included as part of Evidence. A container that can be used to provide arbitrary resource information about an application installed on a device, or evidence collected from a device. The type of resource (ie, registrykey, port, rootUrl) This type is used by Payload to provide details on what may rbe installed on a device, and by Evidence to indicate what an inventory process discovered on a device. One or more directory elements One or more File elements One or more Process elements One or more generic resource elements A reference to any another item (can include details that are related to the SWID tag such as details on where software downloads can be found, vulnerability database associations, use rights, etc). This is modeled directly to match the HTML [LINK] element; it is critical for streamlining software discovery scenarios that these are kept consistent. For installation media (rel="installationmedia") - dictates the canonical name for the file. Items with the same artifact name should be considered mirrors of each other (so download from wherever works). The link to the item being referenced. The href can point to several different things, and can be any of the following: - a RELATIVE URI (no scheme) - which is interpreted depending on context (ie, "./folder/supplemental.swidtag" ) - a physical file location with any system-acceptable URI scheme (ie, file:// http:// https:// ftp:// ... etc ) - an URI with "swid:" as the scheme, which refers to another swid by tagId. This URI would need to be resolved in the context of the system by software that can lookup other swidtags.( ie, "swid:2df9de35-0aff-4a86-ace6-f7dddd1ade4c" ) - an URI with "swidpath:" as the scheme, which refers to another swid by an XPATH query. This URI would need to be resolved in the context of the system by software that can lookup other swidtags, and select the appropriate one based on an XPATH query. Examples: swidpath://SoftwareIdentity[Entity/@regid='http://contoso.com'] would retrieve all swidtags that had an entity where the regid was Contoso swidpath://SoftwareIdentity[Meta/@persistentId='b0c55172-38e9-4e36-be86-92206ad8eddb'] would retrieve swidtags that matched the persistentId See XPATH query standard : http://www.w3.org/TR/xpath20/ An attribute defined by the W3C Media Queries Recommendation (see http://www.w3.org/TR/css3-mediaqueries/). A hint to the consumer of the link to what the target item is applicable for. Determines the relative strength of ownership of the target piece of software. The relationship between this SWID and the target file. Relationships can be identified by referencing the IANA registration library - https://www.iana.org/assignments/link-relations/link-relations.xhtml. The IANA MediaType for the target file; this provides the consumer with intelligence of what to expect. See http://www.iana.org/assignments/media-types/media-types.xhtml for more details on link type. Determines if the target software is a hard requirement or not An open-ended collection of key/value data related to this SWID. Permits any user-defined attributes in Meta tags Specifies the organizations related to the software component referenced by this SWID tag. This has a minOccurs of 1 because the spec declares that you must have at least a Entity with role='tagCreator' This element is used to provide results from a scan of a system where software that does not have a SWID tag is discovered. This information is not provided by the software creator, but is instead created when a system is being scanned and the evidence for why software is believed to be installed on the device is provided in the Evidence element. A reference to any another item (can include details that are related to the SWID tag such as details on where software downloads can be found, vulnerability database associations, use rights, etc). Note: This is modelled directly to match the HTML [LINK] element; it is critical for streamlining software discovery scenarios that these are kept consistent. An open-ended collection of key/value data related to this SWID. The items that may be installed on a device when the software is installed. Note that Payload may be a superset of the items installed and, depending on optimization systems for a device, may or may not include every item that could be created or executed on a device when software is installed. In general, payload will be used to indicate the files that may be installed with a software product and will often be a superset of those files (i.e. if a particular optional component is not installed, the files associated with that component may be included in payload, but not installed on the device). Allows any undeclared elements in the SoftwareIdentity element as long as the element is placed in a different namespace. As xs:any supercedes an xs:element declaration, this continues to support digital signatures using the ds:Signature element: Signatures are not a mandatory part of the software identification tag standard, and can be used as required by any tag producer to ensure that sections of a tag are not modified and/or to provide authentication of the signer. If signatures are included in the software identification tag, they shall follow the W3C recommendation defining the XML signature syntax which provides message integrity authentication as well as signer authentication services for data of any type. Set to true, if this attribute specifies that this SWID tag is a collection of information that describes the pre-installation data of software component. Set to true if this SWID describes a product patch or modification to a different software element. media is a hint to the tag consumer to understand what this SWID tag applies to (see the [Link] tags media attribute). This attribute provides the software component name as it would typically be referenced. For example, what would be seen in the add/remove dialog on a Windows device, or what is specified as the name of a packaged software product or a patch identifier name on a Linux device. Specifies that this tag provides supplemental tag data that can be merged with primary tag data to create a complete record of the software information. Supplemental tags will often be provided at install time and may be provided by different entities (such as the tag consumer, or a Value Added Reseller). tagId shall be a globally unique identifier and should be assigned a GUID reference (see ISO/IEC 19770-5 definition for GUID). The tagID provides a unique reference for the specific product, version, edition, revision, etc (essentially, the same binary distribution). If two tagIDs match and the tagCreator is the same, the underlying products they represent are expected to be exactly the same. This allows IT systems to identify if a software item (for example, a patch) is installed simply by referencing the specific tagID value which is likely to be readily available in a software inventory. It is recommended, when possible, that a 16 byte GUID be used for this field as this provides global uniqueness without a significant amount of overhead for space. If use of a 16 byte GUID is not possible, a text based globally unique ID may be constructed, this ID should include a unique naming authority for the tagCreator and sufficient additional details that the tagId is unique for the software product, version, edition, revision, etc. This would likely look as follows (+ is used as a string concatenation symbol): regid + productName + version + edition + revision + ... The tagVersion indicates if a specific release of a software product has more than one tag that can represent that specific release. This may be the case if a software tag producer creates and releases an incorrect tag that they subsequently want to fix, but with no underlying changes to the product the SWID tag represents. This could happen if, for example, a patch is distributed that has a Link reference that does not cover all the various software releases it can patch. A newer SWID tag for that patch can be generated and the tagVersion value incremented to indicate that the data is updated. Underlying development version for the software component. Scheme used for the version number. Some possible common values are: value="alphanumeric" Strictly a string, sorting alphanumericaly value="decimal" A floating point number : ( ie, 1.25 is less than 1.3 ) value="multipartnumeric" Numbers seperated by dots, where the numbers are interpreted as integers (ie, 1.2.3 , 1.4.5.6 , 1.2.3.4.5.6.7 ) value="multipartnumeric+suffix" Numbers seperated by dots, where the numbers are interpreted as integers with an additional string suffix: (ie, 1.2.3a) value="semver" Follows the semver.org spec value="unknown" Unknown, no attempt should be made to order these An open-ended collection of key/value data related to this SWID. The attributes included in this Element are predefined attributes to ensure common usage across the industry. The schema allows for any additional attribute to be included in a SWID tag, though it is recommended that industry norms for new attributes are defined and followed to the degree possible. Identification of the activation status of this software title (e.g. Trial, Serialized, Licensed, Unlicensed, etc). Typically, this is used in supplemental tags. Provides information on which channel this particular software was targeted for (e.g. Volume, Retail, OEM, Academic, etc). Typically used in supplemental tags. The informal or colloquial version of the product (i.e. 2013). Note that this version may be the same through multiple releases of a software product where the version specified in SoftwareEntity is much more specific and will change for each software release. Note that this representation of version is typically used to identify a group of specific software releases that are part of the same release/support infrastructure (i.e. Fabrikam Office 2013). This version is used for string comparisons only and is not compared to be an earlier or later release (that is done via the SoftwareEntity version). A longer, detailed description of the software. This description can be multiple sentences (differentiated from summary which is a very short, one-sentence description). The variation of the product (Extended, Enterprise, Professional, Standard etc) An indicator to determine if there should be accompanying proof of entitlement when a software license reconciliation is completed. A vendor-specific textual key that can be used to reconcile the validity of an entitlement. (e.g. serial number, product or license key). The name of the software tool that created a SWID tag. This element is typically used if tags are created on the fly, or based on a catalogue based analysis for data found on a computing device. A GUID used to represent products installed where the products are related, but may be different versions. See one representation of this value through the use of what, in a windows installation process is referred to as an upgradeCode - http://msdn.microsoft.com/en-us/library/aa372375(v=vs.85).aspx as one example of the use of this value. The base name of the product (e.g. Office, Creative Suites, Websphere, etc). The overall product family this software belongs to. Product family is not used to identify that a product is part of a suite, but is instead used when a set of products that are all related may be installed on multiple different devices. For example, an Enterprise backup system may consist of a backup server, multiple different backup systems that support mail servers, databases and ERP systems as well as individual software items that backup client devices. In this case all software titles that are part of the backup system would have the same productFamily name so they can be grouped together in reporting systems. The informal or colloquial representation of the sub-version of the given product (ie, SP1, R2, RC1, Beta 2, etc). Note that the SoftwareIdentity.version will provide very exact version details, the revision is intended for use in environments where reporting on the informal or colloquial representation of the software is important (for example, if for a certain business process, an organization recognizes that it must have ServicePack 1 or later of a specific product installed on all devices, they can use the revision data value to quickly identify any devices that do not meet this requirement). Depending on how a software organizations distributes revisions, this value could be specified in a primary (if distributed as an upgrade) or supplemental (if distributed as a patch) SWID tag. A short (one-sentence) description of the software. An 8 digit code that provides UNSPSC classification of the software product this SWID tag identifies. For more information see, http://www.unspsc.org/ The version of the UNSPSC code used to define the UNSPSC code value. For more information see, http://www.unspsc.org/. An expression that the document evaluator can use to determine if the target of the link is applicable to the current platform (the host environment) Used as an optimization hint to notify a system that it can ignore something when it's not likely to be used. The format of this string is modeled upon the MediaQuery definition at http://www.w3.org/TR/css3-mediaqueries/ This is one or more EXPRESSIONs where the items are connected with an OPERATOR: media="EXPRESSION [[OPERATOR] [EXPRESSION]...]" EXPRESSION is processed case-insensitive and defined either : (ENVIRONMENT) indicates the presence of the environment or ([PREFIX-]ENVIRONMENT.ATTRIBUTE:VALUE) indicates a comparison of an attribute of the environment. ENVIRONMENT is a text identifier that specifies any software,hardware feature or aspect of the system the software is intended to run in. Common ENVIRONMENTs include (but not limited to): linux windows java powershell ios chipset peripheral ATTRIBUTE is a property of an ENVIRONMENT with a specific value. Common attributes include (but not limited to): version vendor architecture PREFIX is defined as one of: MIN # property has a minimum value of VALUE MAX # property has a maximum value of VALUE if a PREFIX is not provided, then the property should equal VALUE OPERATOR is defined of one of: AND NOT Examples: media="(windows)" # applies to only systems that identify themselves as 'Windows' media="(windows) not (windows.architecture:x64)" # applies to only systems that identify # themselves as windows and are not for an x64 cpu media="(windows) and (min-windows.version:6.1)" # applies to systems that identify themselves as # windows and at least version 6.1 media="(linux) and (linux.vendor:redhat) and (min-linux.kernelversion:3.0)" # applies to systems that identify themselves as # linux, made by redhat and with a kernel version of at least 3.0 media="(freebsd) and (min-freebsd.kernelversion:6.6)" # applies to systems that identify themselves as # freebsd, with a kernel version of at least 6.6 media="(powershell) and (min-powershell.version:3.0)" # applies to systems that have powershell 3.0 or greater Properties are expected to be able to be resolved by the host environment without having to do significant computation. The IANA MediaType for the target href; this provides the SWID tag consumer with intelligence of what to expect. See http://www.iana.org/assignments/media-types/media-types.xhtml for more details on link type. Determines the relative strength of ownership of the target piece of software. If this is uninstalled, then the [Link]'d software should be removed too. If this is uninstalled, then the [Link]'d software should be removed if nobody else is sharing it Determines if the target software is a hard requirement. The [Link]'d software is absolutely required for installation Not absolutely required, but install unless directed not to Not absolutely required, install only when asked \ No newline at end of file