CMS has adopted the following business rules governing the use of Web Services (WS) within the CMS Processing Environments. To comply with TRA standards, a SOAP or REST Web Service must adhere to the following business rules. Where appropriate, related CMS ARS controls are identified to provide supporting guidance for associated business rules.
BR-WS-1: Describe All Services
CMS requires documentation of Web Services, regardless of implementation technology, in a system’s ICD (or equivalent). This includes a description of the service’s functional and non-functional characteristics, as follows:
-
Functional characteristics
- Preconditions
- Post-conditions
- Assumptions
- Constraints
- Inputs and Outputs
-
Non-functional characteristics
- Performance characteristics
- Capacity characteristics
- Transactional characteristics
- Security characteristics
- Privacy implications, including PII, PHI, etc.
Service developers should consider submitting descriptions of their high-level services to the CMS Enterprise Architects to be documented in the HHS Enterprise Architecture Repository (HEAR). Through this activity, CMS documents the relationship between shared technology services, business services, and organizations.
In addition to these universal documentation requirements, all Web Services must satisfy the following SOAP- and REST-specific requirements.
Related CMS ARS Security Controls include: , PT-2 - Authority to Process Personally Identifiable Information, PT-3 - Personally Identifiable Information Processing Purposes, RA-3 - Risk Assessment, RA-8 -Privacy Impact Assessments, SA-1 - Policy and Procedures, SA-4 - Acquisition Process, SA-9 - External System Services, CA-2 - Control Assessments, PM-21 - Accounting of Disclosures and SI-18 - Personally Identifiable Information Quality Operations.
SOAP Rules
A SOAP Web Service must expose its service contract using WSDL, and must document its service contract. The service contract must describe the following items:
- Actions
- Data (including media types)
- Messages
- Interfaces
The documentation may be in the developer’s own template. Examples appear at: Amazon SQS template snippets and at 2012-11-05/QueueService.wsdl (describing the WSDL and human-readable documentation for the Simple Queuing Service).
REST Rules
A REST Web Service must document its service contract by describing the following items:
- The resources
- The operations that each resource supports
- The representations (content types, which include MIME types) of the resource
- The input and output parameters in the URI that reference each resource
- The HTTP headers associated with the operations
The webpage may be in the developer’s own template. An example appears at Amazon S3 template snippets for the Simple Storage Service (S3).
Rationale:
CMS Web Services must have a human-readable specification for Web Service consumers and providers. It is not sufficient to provide the web service schemas. The specification must explain the pre-conditions, assumptions, and post-conditions of using a given web service. This information helps service consumers understand the functional and non-functional capabilities and limitations of each service.
The use of machine-readable specifications makes it possible to validate web services and share them more easily between service consumers and service providers.
In addition, it is highly recommended that implementations follow de facto industry standards, such as Swagger, Web Application Description Language (WADL), RESTful API Modeling Language (RAML), or JSON Schema to provide specification of REST Web Services.
BR-WS-2: Services Must Use Standard Invocations
SOAP Rule
A SOAP Web Service must use SOAP formatting in accordance with the WS-* standards. If CMS adopts a set of standard SOAP header elements, these must be included in all SOAP Web Services.
REST Rule
A REST Web Service must comply with HTTP 1.1 (RFC 9112) or later and use compliant headers and HTTP method names.
Rationale:
A Web Service must be invoked and respond in a standard way to achieve the broadest application and encourage reuse.
BR-WS-3: Services Must Validate Input and Outputs
It is mandatory to validate input parameters for security, bug trapping, and catching illegal user inputs. CMS requires both syntactic and semantic validation. Semantic validation must include type, format, references, value, context, and applicability.
SOAP Rules
A Web Service must use XML Schema Definition to validate syntactically and structurally any XML data received.
REST Rules
The REST Rules regarding XML are the same as the SOAP Rules. For JSON, the service developer is responsible for both syntactic and semantic validation.
Rationale:
Validation of inputs and outputs contributes to better security, privacy, testing, bug detection, and spam prevention. “Improper enforcement of message or data structure” is a common weakness according to the Common Weakness Enumeration.
Recommendation:
Architects should use XML-aware network elements (such as IBM DataPower or F5) to validate XML and JSON objects rather than developing custom validation code.
Related CMS ARS Security Controls include: SI-10 - Information Input Validation.
BR-WS-4: Use TRB-Approved Data Zone Mediation and Data Access Services to Access Data in the Data Zone
BR-WS-5: Messages Must Include Timestamp and Originator
SOAP Rule
A SOAP message must contain a current timestamp using ISO 8601 [Universal Time Code (UTC)] and identify the sender.
REST Rule
A REST message must contain a current timestamp using ISO 8601 (UTC) and identify the sender.
Rationale:
For usage logging, debugging, and security, each service invocation and response needs an origination timestamp and originator (identifier). Using such timestamps makes it easier for CMS security to perform event correlation because other CMS logs employ UTC.
Related CMS ARS Security Controls include: AU-7 - Audit Record Reduction and Report Generation.
BR-WS-6: Services Must Use Open Data Formats
SOAP Rule
A SOAP message must implement Unicode Transformation Format (UTF) 8-bit (UTF-8) and must not contain embedded binary objects in the body. If binary objects are small enough, they must be encoded, for example, by Base 64 encoding. Binary objects that are too large to send efficiently in a SOAP message must be sent using a protocol such as Direct Internet Message Encapsulation (DIME) or Message Transmission Optimization Mechanism (MTOM).
REST Rule
A REST message body may contain UTF-8 encoded text, XML, JSON, YAML, multimedia, or other open textual or binary formats (such as HL7, FHIR, XBRL, ACORD.)
Rationale:
Avoid proprietary data formats because they limit reuse and may introduce unintended vendor lock-in.
BR-WS-7: Web Services Must Follow CMS Encryption Policy
CMS TRA Network Services, Security Services Business Rules based on the CMS ARS policy for determining when network communications must, should, or should not be encrypted. These rules apply equally to Web Services traffic and content, regardless of underlying implementation technology. In addition, all cryptography must be performed using validated FIPS-140-2 security modules.
Related CMS ARS Security Controls include: AC-3 - Access Enforcement, SC-8 - Transmission Confidentiality and Integrity, and SC-13 - Cryptographic Protection.
Rationale:
Adherence to CMS TRA guidance ensures consistency across CMS Web Services.
BR-WS-8: SOAP-Based Services Must Comply with WS-* Standards
A SOAP Web Service must comply with WS-* standards, and thus, should be able to accept WS-* payloads and extensions for security, reliability, and transactions as required.
Rationale:
Following industry standards is the best way to improve interoperability.
BR-WS-9: Inter-Zone Web Services Must Transverse a Mediated Service
Access to a Web Service from outside of the same zone must traverse a service that employs mediation principles.
Active mediation is required between a service consumer and a service provider. That is, this component actively validates requests and does not simply function as a pass-through. In practice, mediation is often implemented using an enterprise messaging service, ESB, or XML appliance. Alternative implementations may be proposed.
Rationale:
A single entry point has several advantages. First, it decouples the service consumer from the service provider. The service consumer does not know how many instances of the service exist behind the mediation service, thus allowing the service provider to scale the service with multiple service provider instances. Second, it requires only one firewall rule to allow entry. This reduces network administration burden. Finally, the entry point is a natural location for monitoring and control.
The mediated service could be the sole occupant of the Presentation zone for an application if it performs active mediation, challenging requests for validation and access control.
BR-WS-10: Web Services Must Be Version Numbered
All CMS Web Services, regardless of implementation technology, must have a published version number that can be (1) checked by client applications, (2) explicitly requested by client applications, and (3) distinguishable from older or newer versions of the same Web Service.
Rationale:
A change to the semantics without change to the interface specification still means altering the version of the Web Service to reflect the change to semantics. In other words, the version does not solely apply to the interface but to the service as a whole.
Following a versioning scheme decouples release cycles for service consumers and service providers. As the number of service consumers increases, the difficulty in coordinating release cycles between producers and consumers increases dramatically. Please refer to the “Web Services Versioning” approach.
BR-WS-11: Use Certificate-Based Mutual Authentication for Machine-to-Machine Web Services
CMS requires cryptographic certificate-based mutual authentication to perform machine-to-machine communications.
This rule is relaxed if both consumer and provider are communicating over the CMSNet / Core Virtual Routing Forwarding (VRF) network, in CMS data centers under current CMS Authorization To Operate, and the message would not traverse the Internet, even over a Virtual Private Network.
Rationale:
This rule meets the requirements set forth in the CMS Risk Management Handbook, Volume III, Standard 3.1 CMS Authentication Standards.
Using mutual certificates ensures end-point authentication and eliminates the need to store usernames and passwords in the clear on servers communicating with CMS.
The rationale for relaxing the requirement is a risk-based decision for messaging between trusted data centers over a trusted network.
BR-WS-12: Messages Must Pass through All Intermediate Zones
A web service message must pass through each intermediate zone on the way to and from its destination. A zone is defined by the partition created by virtual or physical firewalls where security challenges have been implemented. The CMS TRA requires that at least three separate security challenges be implemented to protect CMS data.
Rationale:
This preserves the integrity of the CMS TRA Multi-Zone Architecture’s Defense-in-Depth strategy. All requests and responses pass through each of the intermediate zones, affording opportunity for CMS security infrastructure to inspect and analyze messages.
Thus, if a message or transaction originates in Internet and will be processed in the Data Zone of a CMS Processing Environment, it must traverse the Presentation, and Application Zones before reaching the Data Zone. No shortcuts are permitted. Likewise, the response must traverse each intermediate zone before reaching the Internet. In the cloud environment, where the zones may not be so clearly defined, the responses must pass through the same zones as the request.
BR-WS-13: CMS Public APIs Must Be Published
All CMS Publicly accessible APIs must be documented on the CMS Developer tools website.
Rationale:
This makes finding CMS APIs easier for external developers.