]> mesur.io

United States mprorock@mesur.io

Self-Issued Consulting

United States michael_b_jones@hotmail.com https://self-issued.info/

Security Secure Patterns for Internet CrEdentials COSE CBOR Object Signing and Encryption CWT CBOR Web Token Claims This document defines claims to support traceability of physical goods across supply chains, focusing on items such as bills of lading, transport modes, and container manifests. These claims standardize the encoding of essential logistics and transport metadata, facilitating enhanced transparency and accountability in global supply chains. These claims are registered for use in both CBOR Web Tokens (CWTs) and JSON Web Tokens (JWTs). About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Secure Patterns for Internet CrEdentials Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction This document defines a set of claims intended to enable the traceability of physical goods across various stages of transportation and storage. These claims capture critical information necessary for documenting the movement of goods in supply chains, thereby supporting regulatory compliance and operational efficiency. These claims are defined for both CBOR Web Tokens (CWTs) and JSON Web Tokens (JWTs) . These claims are informed by the following documents, among others: ACE Automated Broker Interface (ABI) CBP and Trade Automated Interface Requirements (CATAIR) , Integrated Track and Trace for Multi-Modal Transportation , and Traceability Vocabulary v1.0: A vocabulary for traceability in supply chains .

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Security Considerations These claims are designed to enhance transparency in supply chain tracking but should be handled securely to prevent unauthorized access to sensitive data. Confidentiality and integrity of these claims must be considered, particularly when shared across untrusted or unsecured networks. Use of selective disclosure techniques and careful consideration of data minimization requirements SHOULD be considered when using these claims.

IANA Considerations

CBOR Web Token (CWT) Claims This specification registers the following claims in the IANA "CBOR Web Token (CWT) Claims" registry established by .

Goods Identifier

• Claim Name: product_id
• Claim Description: A unique identifier for the physical product(s) or shipment being tracked. May correspond to SKU, product ID, or batch number.
• JWT Claim Name: product_id
• Claim Key: TBD (requested assignment 320)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Shipment ID

• Claim Name: shipment_id
• Claim Description: Unique identifier assigned to a specific shipment.
• JWT Claim Name: shipment_id
• Claim Key: TBD (requested assignment 321)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Bill of Lading Number

• Claim Name: bill_of_lading_number
• Claim Description: Identifier for the bill of lading associated with the goods.
• JWT Claim Name: bill_of_lading_number
• Claim Key: TBD (requested assignment 322)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Transport Mode

• Claim Name: transport_mode
• Claim Description: Mode of transport used for the shipment.
• JWT Claim Name: transport_mode
• Claim Key: TBD (requested assignment 323)
• Claim Value Type: text string (recommended values: “air,” “sea,” “rail,” “truck”)
• Change Controller: IETF
• Reference: of this specification

Container ID

• Claim Name: container_id
• Claim Description: Unique identifier for the container used in the shipment.
• JWT Claim Name: container_id
• Claim Key: TBD (requested assignment 324)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Origin Location

• Claim Name: origin_location
• Claim Description: Geographical origin of the goods, represented as an alpha-2 country code string or specific address
• JWT Claim Name: origin_location
• Claim Key: TBD (requested assignment 325)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Destination Location

• Claim Name: destination_location
• Claim Description: Final destination of the goods in the shipment.
• JWT Claim Name: destination_location
• Claim Key: TBD (requested assignment 326)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Carrier ID

• Claim Name: carrier_id
• Claim Description: Identifier for the carrier or logistics provider responsible for the shipment.
• JWT Claim Name: carrier_id
• Claim Key: TBD (requested assignment 327)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Estimated Delivery Date

• Claim Name: estimated_delivery_date
• Claim Description: Expected delivery date for the shipment, represented as an date and time string
• JWT Claim Name: estimated_delivery_date
• Claim Key: TBD (requested assignment 328)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Customs Declaration Number

• Claim Name: customs_declaration_number
• Claim Description: Identifier for the customs declaration associated with the shipment.
• JWT Claim Name: customs_declaration_number
• Claim Key: TBD (requested assignment 329)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Commodity Description

• Claim Name: commodity_description
• Claim Description: Description of the commodity or goods being transported.
• JWT Claim Name: commodity_description
• Claim Key: TBD (requested assignment 330)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

HS Code

• Claim Name: hs_code
• Claim Description: Harmonized System (HS) code for the goods.
• JWT Claim Name: hs_code
• Claim Key: TBD (requested assignment 331)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Gross Weight

• Claim Name: gross_weight
• Claim Description: Gross weight of the shipment, in kilograms.
• JWT Claim Name: gross_weight
• Claim Key: TBD (requested assignment 332)
• Claim Value Type: integer
• Change Controller: IETF
• Reference: of this specification

Temperature Min Requirement

• Claim Name: temperature_requirement_min
• Claim Description: Minimum temperature (in Celsius) required for transport or storage of the goods.
• JWT Claim Name: temperature_requirement_min
• Claim Key: TBD (requested assignment 333)
• Claim Value Type: float
• Change Controller: IETF
• Reference: of this specification

Temperature Max Requirement

• Claim Name: temperature_requirement_max
• Claim Description: Maximum temperature (in Celsius) required for transport or storage of the goods.
• JWT Claim Name: temperature_requirement_max
• Claim Key: TBD (requested assignment 334)
• Claim Value Type: float
• Change Controller: IETF
• Reference: of this specification

Last Known Location

• Claim Name: last_known_location
• Claim Description: Most recent location update for the goods.
• JWT Claim Name: last_known_location
• Claim Key: TBD (requested assignment 335)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Tariff Code

• Claim Name: tariff_code
• Claim Description: Tariff code applicable to the goods, including national tariff classifications or specific duty codes.
• JWT Claim Name: tariff_code
• Claim Key: TBD (requested assignment 336)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Country of Origin

• Claim Name: country_of_origin
• Claim Description: The country where the goods were produced or manufactured, represented as an alpha-2 country code string
• JWT Claim Name: country_of_origin
• Claim Key: TBD (requested assignment 337)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Customs Value

• Claim Name: customs_value
• Claim Description: Declared value of the goods for customs purposes, typically in the transaction currency.
• JWT Claim Name: customs_value
• Claim Key: TBD (requested assignment 338)
• Claim Value Type: float
• Change Controller: IETF
• Reference: of this specification

Currency Code

• Claim Name: currency_code
• Claim Description: Currency code for the customs value and other monetary amounts, represented as an alpha-3 currency code string
• JWT Claim Name: currency_code
• Claim Key: TBD (requested assignment 339)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Import/Export License Number

• Claim Name: license_number
• Claim Description: License or permit number required for the import or export of the goods.
• JWT Claim Name: license_number
• Claim Key: TBD (requested assignment 340)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Sanctions Reference

• Claim Name: sanctions_reference
• Claim Description: Reference to applicable sanctions lists or regulations affecting the goods or involved parties.
• JWT Claim Name: sanctions_reference
• Claim Key: TBD (requested assignment 341)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Legal Jurisdiction

• Claim Name: legal_jurisdiction
• Claim Description: Legal jurisdiction(s) governing the transaction, represented as an alpha-2 country code string or specific legal identifiers
• JWT Claim Name: legal_jurisdiction
• Claim Key: TBD (requested assignment 342)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Importer Code

• Claim Name: importer_code
• Claim Description: Code identifying the importer, such as a VAT number or EORI number.
• JWT Claim Name: importer_code
• Claim Key: TBD (requested assignment 343)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Exporter Code

• Claim Name: exporter_code
• Claim Description: Code identifying the exporter, such as a VAT number or EORI number.
• JWT Claim Name: exporter_code
• Claim Key: TBD (requested assignment 344)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

International Commercial Terms

• Claim Name: incoterms
• Claim Description: International commercial terms defining responsibilities between buyer and seller, e.g., "FOB," "CIF."
• JWT Claim Name: incoterms
• Claim Key: TBD (requested assignment 345)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Regulatory Compliance Codes

• Claim Name: regulatory_compliance_codes
• Claim Description: Codes indicating compliance with specific regulations or standards (e.g., safety certifications, environmental standards).
• JWT Claim Name: regulatory_compliance_codes
• Claim Key: TBD (requested assignment 346)
• Claim Value Type: array of text strings
• Change Controller: IETF
• Reference: of this specification

Additional Documents Required

• Claim Name: additional_documents_required
• Claim Description: List of additional documents required for customs clearance, such as certificates of origin or inspection reports.
• JWT Claim Name: additional_documents_required
• Claim Key: TBD (requested assignment 347)
• Claim Value Type: array of text strings
• Change Controller: IETF
• Reference: of this specification

Freight Charges

• Claim Name: freight_charges
• Claim Description: Transportation costs associated with the shipment, used for customs valuation.
• JWT Claim Name: freight_charges
• Claim Key: TBD (requested assignment 348)
• Claim Value Type: float
• Change Controller: IETF
• Reference: of this specification

Insurance Charges

• Claim Name: insurance_charges
• Claim Description: Insurance costs for the shipment, used in determining customs value.
• JWT Claim Name: insurance_charges
• Claim Key: TBD (requested assignment 349)
• Claim Value Type: float
• Change Controller: IETF
• Reference: of this specification

Packing Costs

• Claim Name: packing_costs
• Claim Description: Costs associated with packing the goods, relevant for customs valuation.
• JWT Claim Name: packing_costs
• Claim Key: TBD (requested assignment 350)
• Claim Value Type: float
• Change Controller: IETF
• Reference: of this specification

Place of Loading

• Claim Name: place_of_loading
• Claim Description: Location where the goods were loaded for shipment, often a port or warehouse.
• JWT Claim Name: place_of_loading
• Claim Key: TBD (requested assignment 351)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Place of Discharge

• Claim Name: place_of_discharge
• Claim Description: Location where the goods are scheduled to be unloaded.
• JWT Claim Name: place_of_discharge
• Claim Key: TBD (requested assignment 352)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

Consignee Information

• Claim Name: consignee_information
• Claim Description: Information about the consignee, including name, address, and contact details.
• JWT Claim Name: consignee_information
• Claim Key: TBD (requested assignment 353)
• Claim Value Type: map
• Change Controller: IETF
• Reference: of this specification

Consignor Information

• Claim Name: consignor_information
• Claim Description: Information about the consignor, including name, address, and contact details.
• JWT Claim Name: consignor_information
• Claim Key: TBD (requested assignment 354)
• Claim Value Type: map
• Change Controller: IETF
• Reference: of this specification

Customs Declaration Date

• Claim Name: customs_declaration_date
• Claim Description: Date when the customs declaration was made, represented as an date and time string
• JWT Claim Name: customs_declaration_date
• Claim Key: TBD (requested assignment 355)
• Claim Value Type: text string
• Change Controller: IETF
• Reference: of this specification

JSON Web Token (JWT) Claims This specification registers the following claims in the IANA "JSON Web Token Claims" registry established by .

Goods Identifier

• Claim Name: product_id
• Claim Description: A unique identifier for the physical product(s) or shipment being tracked. May correspond to SKU, product ID, or batch number.
• Change Controller: IETF
• Reference: of this specification

Shipment ID

• Claim Name: shipment_id
• Claim Description: Unique identifier assigned to a specific shipment.
• Change Controller: IETF
• Reference: of this specification

Bill of Lading Number

• Claim Name: bill_of_lading_number
• Claim Description: Identifier for the bill of lading associated with the goods.
• Change Controller: IETF
• Reference: of this specification

Transport Mode

• Claim Name: transport_mode
• Claim Description: Mode of transport used for the shipment.
• Change Controller: IETF
• Reference: of this specification

Container ID

• Claim Name: container_id
• Claim Description: Unique identifier for the container used in the shipment.
• Change Controller: IETF
• Reference: of this specification

Origin Location

• Claim Name: origin_location
• Claim Description: Geographical origin of the goods, represented as an alpha-2 country code string or specific address
• Change Controller: IETF
• Reference: of this specification

Destination Location

• Claim Name: destination_location
• Claim Description: Final destination of the goods in the shipment.
• Change Controller: IETF
• Reference: of this specification

Carrier ID

• Claim Name: carrier_id
• Claim Description: Identifier for the carrier or logistics provider responsible for the shipment.
• Change Controller: IETF
• Reference: of this specification

Estimated Delivery Date

• Claim Name: estimated_delivery_date
• Claim Description: Expected delivery date for the shipment, represented as an date and time string
• Change Controller: IETF
• Reference: of this specification

Customs Declaration Number

• Claim Name: customs_declaration_number
• Claim Description: Identifier for the customs declaration associated with the shipment.
• Change Controller: IETF
• Reference: of this specification

Commodity Description

• Claim Name: commodity_description
• Claim Description: Description of the commodity or goods being transported.
• Change Controller: IETF
• Reference: of this specification

HS Code

• Claim Name: hs_code
• Claim Description: Harmonized System (HS) code for the goods.
• Change Controller: IETF
• Reference: of this specification

Gross Weight

• Claim Name: gross_weight
• Claim Description: Gross weight of the shipment, in kilograms.
• Change Controller: IETF
• Reference: of this specification

Temperature Min Requirement

• Claim Name: temperature_requirement_min
• Claim Description: Minimum temperature (in Celsius) required for transport or storage of the goods.
• Change Controller: IETF
• Reference: of this specification

Temperature Max Requirement

• Claim Name: temperature_requirement_max
• Claim Description: Maximum temperature (in Celsius) required for transport or storage of the goods.
• Change Controller: IETF
• Reference: of this specification

Last Known Location

• Claim Name: last_known_location
• Claim Description: Most recent location update for the goods.
• Change Controller: IETF
• Reference: of this specification

Tariff Code

• Claim Name: tariff_code
• Claim Description: Tariff code applicable to the goods, including national tariff classifications or specific duty codes.
• Change Controller: IETF
• Reference: of this specification

Country of Origin

• Claim Name: country_of_origin
• Claim Description: The country where the goods were produced or manufactured, represented as an alpha-2 country code string
• Change Controller: IETF
• Reference: of this specification

Customs Value

• Claim Name: customs_value
• Claim Description: Declared value of the goods for customs purposes, typically in the transaction currency.
• Change Controller: IETF
• Reference: of this specification

Currency Code

• Claim Name: currency_code
• Claim Description: Currency code for the customs value and other monetary amounts, represented as an alpha-3 currency code string
• Change Controller: IETF
• Reference: of this specification

Import/Export License Number

• Claim Name: license_number
• Claim Description: License or permit number required for the import or export of the goods.
• Change Controller: IETF
• Reference: of this specification

Sanctions Reference

• Claim Name: sanctions_reference
• Claim Description: Reference to applicable sanctions lists or regulations affecting the goods or involved parties.
• Change Controller: IETF
• Reference: of this specification

Legal Jurisdiction

• Claim Name: legal_jurisdiction
• Claim Description: Legal jurisdiction(s) governing the transaction, represented as an alpha-2 country code string or specific legal identifiers
• Change Controller: IETF
• Reference: of this specification

Importer Code

• Claim Name: importer_code
• Claim Description: Code identifying the importer, such as a VAT number or EORI number.
• Change Controller: IETF
• Reference: of this specification

Exporter Code

• Claim Name: exporter_code
• Claim Description: Code identifying the exporter, such as a VAT number or EORI number.
• Change Controller: IETF
• Reference: of this specification

International Commercial Terms

• Claim Name: incoterms
• Claim Description: International commercial terms defining responsibilities between buyer and seller, e.g., "FOB," "CIF."
• Change Controller: IETF
• Reference: of this specification

Regulatory Compliance Codes

• Claim Name: regulatory_compliance_codes
• Claim Description: Codes indicating compliance with specific regulations or standards (e.g., safety certifications, environmental standards).
• Change Controller: IETF
• Reference: of this specification

Additional Documents Required

• Claim Name: additional_documents_required
• Claim Description: List of additional documents required for customs clearance, such as certificates of origin or inspection reports.
• Change Controller: IETF
• Reference: of this specification

Freight Charges

• Claim Name: freight_charges
• Claim Description: Transportation costs associated with the shipment, used for customs valuation.
• Change Controller: IETF
• Reference: of this specification

Insurance Charges

• Claim Name: insurance_charges
• Claim Description: Insurance costs for the shipment, used in determining customs value.
• Change Controller: IETF
• Reference: of this specification

Packing Costs

• Claim Name: packing_costs
• Claim Description: Costs associated with packing the goods, relevant for customs valuation.
• Change Controller: IETF
• Reference: of this specification

Place of Loading

• Claim Name: place_of_loading
• Claim Description: Location where the goods were loaded for shipment, often a port or warehouse.
• Change Controller: IETF
• Reference: of this specification

Place of Discharge

• Claim Name: place_of_discharge
• Claim Description: Location where the goods are scheduled to be unloaded.
• Change Controller: IETF
• Reference: of this specification

Consignee Information

• Claim Name: consignee_information
• Claim Description: Information about the consignee, including name, address, and contact details.
• Change Controller: IETF
• Reference: of this specification

Consignor Information

• Claim Name: consignor_information
• Claim Description: Information about the consignor, including name, address, and contact details.
• Change Controller: IETF
• Reference: of this specification

Customs Declaration Date

• Claim Name: customs_declaration_date
• Claim Description: Date when the customs declaration was made, represented as an date and time string
• Change Controller: IETF
• Reference: of this specification

References Normative References JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. CBOR Web Token (CWT) is a compact means of representing claims to be transferred between two parties. The claims in a CWT are encoded in the Concise Binary Object Representation (CBOR), and CBOR Object Signing and Encryption (COSE) is used for added application-layer security protection. A claim is a piece of information asserted about a subject and is represented as a name/value pair consisting of a claim name and a claim value. CWT is derived from JSON Web Token (JWT) but uses CBOR rather than JSON. ISO ISO ISO In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References IANA n.d. IANA n.d. U.S. Customs and Border Protection United Nations Centre for Trade Facilitation and Electronic Business (UN/CEFACT)

Acknowledgments A.J. Stein contributed to this specification.

Document History -01

• Updated CWT Claims registrations to supply all fields in the registration template.
• Fixed IANA Considerations header, as suggested by A.J. Stein.
• Added references for ISO specs.
• Specified the use of alpha-2 country code strings and alpha-3 currency code strings.
• Added references to sources of traceability claims.
• Added Michael B. Jones as an author.

-00

• Initial individual draft