Atlanticbt.com

Search Get in Touch Menu
CSOS
August 27, 2018

Definitive Guide to CSOS Development

capabilities covered
Drupal Magento CMS Solutions Quality Assurance PHP System Architecture Salesforce & CRM Integration WordPress Software Development Hosting Cloud Services .NET

Are you currently developing or planning to develop a Controlled Substance Ordering System, or CSOS? Then you’ve come to the right place. This guide was developed to provide all the information to create such an application in one friendly document. To learn more about how this process took shape, read about Atlantic BT’s web development work for NC Mutual Drug. This work was the inspiration for our writing this guide.

Background for This CSOS Guide

The DEA created the CSOS audit process when client-server architecture was the only viable solution. Audit cases exist for both the “sender” machine and the “receiver” machine (i.e. Audit Cases 1 & 2). Atlantic BT’s implementation is a web application, which performs both the client and server actions. Therefore, the documentation in this guide organizes these cases together. In a true client-server environment, the cases are applied appropriately. Atlantic BT’s implementation involves Windows servers and a .Net solution using C#. Information and examples providing guidance on accomplishing validation will use technology-specific references only when necessary. It should be stated that when signing an order with controlled substances, a single digital file must be utilized for signing. This is similar to the real-life scenario in which you would sign a physical document. In Atlantic BT’s application, an EDI 850 file is constructed for signing, and will be referenced throughout as the “order file.”

Source Documentation CSOS

Many documents exist and are publicly available for CSOS developers:

Note: The CSOS Certificate Management documentation is for owners of the digital certificates. If you note the “Manage CSOS Certificates” section, this documentation was created prior to Windows 8 existing and before Google Chrome was a standard web browser.

Why Does this Guide Use “Audit Cases”?

AtlanticBT used the Drummond Group to perform the CSOS audit. The Drummond Group uses 13 “Audit Cases” to test all requirements for a CSOS application. This guide provides information on the validation needed to pass each case, and how the audit occurs. Please note that the audit cases in this guide were in place at time of AtlanticBT’s audit; the Drummond Group may add or modify these in the future.

Audit Cases 1 & 2

These cases all involve verifying the code and systems use approved FIPS modules.

Validation

  1. Go to the NIST page listing all validated modules: csrc.nist.gov
  2. Find the module your implementation will be using
  3. Be able to show in your code and on your server you are using the module you specify.

Audit Cases 1.1, 2.1 These audit cases validate the cryptographic module residing on the machines used in validation.
Audit Process (Windows) In order to show what version the server is running, open a Command Prompt on the server. Use the “ver” command. AtlanticBT’s solution was deployed on a Windows Server 2012 instance. This is Cert #1894 on on the nist.gov page. Note that this cert correlates to “Software Version 6.2.9200”.

C:\> ver
Microsoft Windows [Version 6.2.9200] C:\
Audit Cases 1.2, 1.3, 2.2, 2.3
Audit Process AtlanticBT showed screenshots of code, and that encryption algorithms were used from Microsoft libraries that were approved within certificate #1894. To prove the code was truly FIPS compliant, the following was performed on a developer machine:

  1. Windows not running in FIPS enabled mode, run validation on a certificate using FIPS approved modules. This should succeed.
  2. Change Windows Mode to FIPS enabled (See Stack Overflow: How to enable FIPS on windows 7)
  3. Windows running in FIPS enabled mode, run validation on a certificate using FIPS approved modules. This should succeed.
  4. Change encryption to a non-FIPS approved method. (This is a temporary code change for auditing purpose only). Run validation on a certificate using non-FIPS approved modules. This should fail.

Audit Case 1.4 This audit case validates that certificates (called “private keys” throughout CSOS documentation) reside in an encrypted fashion whenever stored.
Validation Encrypt any stored instances of certificates. Atlantic BT’s solution utilized the AWS S3 service, which can encrypt files using the AES-256 encryption algorithm. Some solutions may involve using a computer’s Certificate Store, which uses encrypted storage.
Audit Process Show proof on files stored using encryption. If a custom storage solution is implemented, this would involve storing a new certificate and showing the stored file is encrypted.

Audit Case 3 & 4

These audit cases involve signing an order with a valid certificate, passing all validation.
Validation No specific validation needs to be developed, but all other validations must be performed and pass.
Audit Process An order is signed with a valid certificate, and validation succeeds.

Audit Case 5

These audit cases contain many of the certificate-specific validations. They relate to the validations which can be applied to the certificate and information unrelated to the order being signed. In advance of discussing the audit cases, it is important to discuss certificate hierarchy. Many of the test cases involve validating data against the “certificate chain”.
Certificate Structure There is plenty of information on digital certificates concerning their creation, structure, and use. However, simple summaries are difficult to find. That in mind, the following attempts to offer a summary and correlate it specifically to the CSOS requirements. 1) A “Root Certificate” is created. This is used to create other certificates, and in these, the unique “thumbprint” of the root is contained within its metadata. The DEA has created root certificates specifically for use with CSOS certificates. —> There are “private” and “public” portions of certificates. The “private” portion can be used to create other certificates and are never provided (to avoid fraud). The “public” portions can be used (by anyone) to validate a certificate was issued from the root. 2) A “Sub CA” (Certificate Authority) certificate is created from the root certificate, as noted above. The same structure applies—these certificates can be use to create yet other certificates, and the Sub CA “thumbprint” is contained within the metadata. The DEA has created Sub CA certificates which are used to create the personal certificates. 3) Personal certificates are created for use in signing. Therefore, for all CSOS certificates, the “chain” of certificates is as follows: —> Root Certificate —> Sub CA Certificate —> Personal Certificate
Server Setup In order to successfully validate certificates, the system performing validation must have the Root and Sub CA certificates installed. Having access to the certificate files is not enough; these must actually be installed. The official CSOS Root and Sub CA certificates, for use with production, can be found here:
CSOS Certificate Management (deaecom.gov). During development and auditing, a test suite of certificates is used (see: diversiontest.usdoj.gov). The “CA CERT” folder within contains separate Root and Sub CA certificates for use with the test certificates.
Developer Warning: Make sure the test suite root and sub certificates are only installed on local and dev servers, and not installed on production machines. To install certificates on a local (Windows) machine, use the Certificate Manager. This can found by using the Windows Key and searching for “Manage computer certificates”, or using the MMC Snap in (see: How to: View Certificates with the MMC Snap-in)

Root and Sub CA certificates correctly installed on a Wondows Machine
Root and Sub CA certificates correctly installed on a Wondows Machine

In order to verify these certificates are installed correctly, you can use any browser’s certificate management and import a certificate. The following examples use the ValidOrderThree certificate from the test suite of certificates:

The left screen shot shows Root and Sub CA certificates installed correctly. The "certificate chain" is complete and valid with the root certificate at the top. On the right hand side, the Root and Sub CA certificates are not installed correctly. The sub CA certificate cannot be found.
The left screen shot shows Root and Sub CA certificates installed correctly. The “certificate chain” is complete and valid with the root certificate at the top.

On the right hand side, the Root and Sub CA certificates are not installed correctly. The sub CA certificate cannot be found.

Audit Case 5.1 The CSOS requirement for case 5.1 states “The system must determine that an order has not been altered during transmission.” This relates to the original client-server architecture expected when the requirements were established. The order would be created and signed on a client machine, transmitted to a server, and then final processing occurred. This case is designed to verify the data sent from the client machine to the server was not altered. In a web application, however, this may all occur on the same server. The order is submitted and signed through the web application, and all validation could occur prior to final success, all in memory. This is the case for Atlantic BT’s application. In order to provide an auditable result, the code was structured as follows: 1) The order file is digitally signed, which results in a signature file (in memory). This file is a small file containing encrypted (non-readable) data. 2) All other validations are performed on the certificate. 3) Lastly, a verification of the signature file and order file is performed.
Code Reference (.Net) For signing, the RSACryptoServiceProvider.SignHash Method was used. For verification, the RSACryptoServiceProvider.VerifyHash Method was used.
Audit Process In order to show success of this requirement, two signing attempts were shown. This was performed on a local machine using Visual Studio, which allows debugging and breakpoints to modify in-memory data. 1) Successful a. Break after SignHash method, show in-memory order file b. Break before VerifyHash method show in-memory order file hasn’t changed c. Show VerifyHash is successful, thus the sign process succeeds 2) Unsuccessful a. Break after SignHash method, show in-memory order file results b. Modify the order file data c. Break before VerifyHash method show in-memory order file has changed d. Show VerifyHash is unsuccessful, thus the sign process fails In a client-server environment, this could be accomplished by simply using a different order file with the generated signature file for verification. In-memory data modification would not be required.
Audit Case 5.2 This audit case is to validate that the certificate being used to sign the order originated from the DEA for use with signing digital orders.
Chain Building (.Net) First, a valid certificate chain must be determined. Using .Net, a valid X509Certificate2 object is created from the certificate data. Throughout this guide, the certificate being validated will be an X509Certificate2 object. Next (In .Net), a X509Chain is created, and the Build method is used the verify the chain and build the chain in memory. If the Root and Sub CA certificates have not been correctly installed, this method will fail.
Validation To pass validation successfully, it should be verified the thumbprint of the found root certificate matches one of the official DEA CSOS Root Certificate thumbprints. At time of documentation, the two DEA root thumbprints are: “9037640ee5c71e4ced76ed88fefa4e051907f7e7” and “f23190647132a900e634badf2a8f35a95bd383d7” The test suite root certificate thumbprint is: “fb1eb3439c28e14014f2ef942f0bdd636bfef467”
Audit Process In order to show failure for the audit case, a certificate that was not created using a chain originating in a CSOS root certificate must be tested against. There are a few methods to creating a certificate:

When signing an order using any non-CSOS certificate, the signing should fail, passing the audit case.
Audit Case 5.3 This audit case validates the generated signature file from signing. Similar to 5.1, this means a signing process should fail if the signature file is modified in transit, whereas case 5.1 related to the order file.
Audit Process In order to show success of this requirement, two signing attempts were shown. This was performed on a local machine using Visual Studio, which allows debugging and breakpoints to modify in-memory data. 1) Successful a.Break after SignHash method, show in-memory signature file b. Break before VerifyHash method show in-memory signature file hasn’t changed c. Show VerifyHash is successful, thus the sign process succeeds 2) Unsuccessful a. Break after SignHash method, show in-memory signature file results b. Modify the signature file data c. Break before VerifyHash method show in-memory signature file has changed d. Show VerifyHash is unsuccessful, thus the sign process fails In a client-server environment, this could be accomplished by simply using a different signature file with the order file for verification. In-memory data modification would not be required.
Audit Cases 5.4, 5.5, 5.6, 5.7 These audit cases validates the certificate being used to sign the order hasn’t been revoked. The DEA permanently maintains a publicly accessible Certificate Revocation List (CRL) to check for certificate validity. There are four audit cases pertaining to certificates revoked for a variety of reasons; however, the validation is performed the same way for all cases.
Determining the CRL for the Certificate The first step in validation is finding the appropriate CRL. The CRL for any CSOS certificate is contained within the metadata of the certificate itself. Unfortunately, this needs to parsed from within a large string. The screenshot provided shows the URL value of the CRL, but this is only part of a string value which contains other certificate information.
CSOS Development White Paper Using Newlines, “URL=”, “cn=”, and “(“ breakpoints, the domain and other CRL information can be parsed. The domain on it’s own will be used to establish a connection.
Connection An LDAP connection is required to connect to DEA provided CRLs. For .Net, a “LdapConnection” object is utilized. The “Distinguished Name” is required as well, which in the screenshot is all the parameters from “cn=CRL3” through “c=US”, these are the identifiers for the specific CRL.
Validation In order to be validated, a connection must be made, the correct CRL entry must be located, and the certificate being validated must not be found in the CRL. (If it is found, the certificate is revoked.) Therefore, the following checks should be made:
CSOS Development White Paper
Audit Process The audit process for these are straightforward. Revoked certificates from the test suite of certificates are used in signing an order. All attempts should fail.
CRL and ARL Please see Audit Case 5.9 for additional information which builds upon this CRL validation.
Audit Case 5.8 This audit case validates the certificate has not expired.
Validation All certificates have a “Valid To” or expired date within their metadata. If this date has passed, then the certificate has expired. In .Net, there is a “GetExpirationDateString” method. The results can be used to create a Date object for comparison.
CSOS Development White Paper
Audit Process Again, this is straightforward. An expired certificate from the test suite should fail validation.
Audit Case 5.9 This audit case validates that either a Sub CA or root certificate in the certificate chain has not been revoked.
Validation Once a valid certificate chain has been established (See Audit Case 5.2), and the certificate itself has been determined as not revoked, every other certificate in the chain must be found as not revoked. The process developed for Audit Cases 5.3-5.7 can almost be used for these certificates.
However, a disparity exists between the test suite and real-world certificates at time of this documentation. For test suite certificates, this CRL check passed validation. When performing tests against a production certificate, this validation failed. A different attribute was found when using the LDAP connection for these certificates: “authorityrevocationlist;binary”. These connections contained attributes for both the CRL and the ARL. Therefore, the resulting validation occurs for all certificates:

  • Connect to the LDAP
  • Check for the CRL attribute.

* If this was not found, validation fails for being unable to check the CRL. * If the CRL check was successful, and the certificate was found (thus revoked), validation fails. * If the CRL check was successful, and the certificate was not found, processing continues.

  • Check for the ARL attribute.

* If this was not found, validation succeeds. (Because it is not required to check ARL, and this will not exist for personal certificates). * If the ARL check was successful, and the certificate was found (thus revoked), validation fails. * If the ARL check was successful, and the certificate was not found, validation succeeds.
Audit Process A valid certificate linked to a revoked Sub CA certificate from the test suite should fail validation.
Audit Case 5.10 This audit case validates that either a Sub CA or root certificate in the certificate chain has not expired.
Validation Once a valid certificate chain has been established (See Audit Case 5.2), and the certificate itself has been determined as not revoked, every other certificate in the chain must be found as not revoked. The process developed for Audit Cases 5.8 can be used for these certificates.
Audit Process A valid certificate linked to an expired Sub CA certificate from the test suite should fail validation.

Audit Case 6

This audit case pertains to the drugs specified in an order, and that the signing certificate has the authorization to purchase these drugs. The DEA has seven “schedules” or “schedule access” for controlled substances. (See:
Controlled Substance Schedules
) These are 1, 2, 2n, 3, 3n, 4, and 5. Each CSOS certificate contains in its metadata the list of authorized schedules that can be purchased.
Order Schedules The order file which is being signed must contain the list of drugs in the order, and the schedule access for each drug. The list of these schedules must be gathered for comparison.
CSOS Development White Paper
Certificate Schedules Each certificate contains many fields of data. The metadata field for OID “2.16.840.1.101.3.5.4” contains the 8-bit field related to available schedules. (See CSOS Certificate and CRL Profile (PDF) 6.2)
Please note it is only the last 8-bit value that specifies the schedule access. The number of octets in the field may vary, it is always the last octet which should be used.
This 8- bit field correlates to the 7 schedules. (See CSOS Certificate and CRL Profile (PDF) 3.3.4) Bit 0: Schedule 1 Bit 1: Schedule 2 Bit 2: Schedule 2n Bit 3: Schedule 3 Bit 4: Schedule 3n Bit 5: Schedule 4 Bit 6: Schedule 5 Bit 7: Not Used In the provided screenshot, the “03 02 01” does not indicate access to schedules 3, 2, and 1. Instead, the “5e” maps to schedule access. In Hex to binary, “5” maps to “0101” and “e” maps to “1110”. Therefore, the 8 bit field for this certificate is “01011110”. This certificate would have access to all schedules except 1 and 2n.
Validation The order schedules must be compared to the certificate schedules. If the order contains any schedules not approved within the certificate schedules, validation fails.
Audit Process A certificate not authorized to purchase drugs within the test order should fail validation.

Audit Case 7

These audit cases pertain to authorization related to the CSOS application and the signing certificate. Access to the application must require a login, and in-memory retainment of the certificate and certificate password must be tightly controlled.
Audit Case 7.1 A user must login with a username and password into the CSOS application used to create orders containing controlled substances. Creation of these orders are not allowed in applications open to public access. Also, users in the system must be able to be invalidated.
Validation Standard username/password (or biometric) authentication must be implemented on the application.
Audit Process

  • A new user to the system is created
  • Login is successful for the new user
  • An order is created and signed by the new user
  • The user is logged out
  • Access to the application is revoked (via admin or through database changes)
  • Login is unsuccessful

Audit Case 7.2 Separate from application login, a CSOS application is allowed to re-use a user’s certificate for 10 minutes after the user provides certificate credentials. This could be handled in a variety of system architectures. The following lists some, others may also be valid.

  • An individual has a unique login to the system. A single certificate is associated with the account. Access to the entire application is timed out after 10 minutes of inactivity.
  • After a user logs into the application (with any timeout), the user must provide the password for their certificate (possibly a username as well). After successfully signing an order with these credentials, the user could sign another order without re-authentication for 10 minutes, otherwise they have to re-authenticate the certificate.
  • After a user logs into the application (with any timeout), the user must provide the password for the certificate each time they sign an order. This is the approach in the AtlanticBT solution.

Validation As noted above, AtlanticBT’s solution required the user to supply the certificate password on every signing attempt. Other approaches may pass this validation as well.
Audit Process Auditing the solution is a case-by-case basis. For AtlanticBT, showing the certificate password was required on a second order directly after a first order was signed was sufficient.
Audit Case 7.3 If the password for the user’s certificate (private key) is retained in memory, this must be cleared from memory when a timeout occurs (as in Audit Case 7.2).
Validation If the password is retained in memory, it must be cleared on timeout.
Audit Process Not required if password is not retained in memory. Otherwise, code debugging (or some other display mechanism) would be required to verify memory is cleared.

Audit Cases 8 & 9

Computers used to sign and validate orders must be synced with the NIST time servers. There is a 5-minute variance allowed. See NIST Internet Time Servers for a list of NIST time servers. Note that “time.nist.gov” is the global address which should be used.
Validation Any server or computer used in the signing process must be synced with the NIST time servers. For Windows machines, it may enough to set the time server through configuration. (See: How to use Alarms & Clock app “synchronizing with an Internet time server”) Atlantic BT’s solution deployed the web application to AWS EC2 instances. These servers stay in UTC time automatically. Other web servers can be configured to sync explicitly with the time.nist.gov servers. Alternatively, a connection with the NIST time servers can be established at time of signing. Atlantic BT added this as well, and accomplished this by sending a UDP packet, expecting a response, and parsing the response for current date and time. Many methods may achieve the same result. If the difference between the NIST time and the system time is greater than 5 minutes (either ahead or behind) then validation fails.
Audit Process If time server synchronization is (only) used, auditing involves occasionally changing the system time, and returning later to find the time having synced back to NIST time. If at-signing validation is used, the server time can be changed more than five minutes ahead of the NIST servers, and attempt signing an order. Validation should fail.

Audit Case 10

The order file which is being signed must contain a minimum amount of data. This does not have to be verified at time of signing through code, but the audit process involves inspecting the file used in validation.
Validation The order file must contain: A unique tracking number, made of of 2-digit year, ‘X’, and 6 digit number; supplier’s name, address, and DEA number; purchaser’s DEA number, order date, and ordered substances name & strength (or NDC), quantity, and number of packages.
Audit Process Auditors will inspect the order file of a newly created order.

Audit Cases 11 &12

The DEA requires any information related to orders be archived together in a location identifiable to that specific order.
Validation Any solution is valid where this information is stored (for a minimum of 3 years). The order file and signature file should be included at a minimum. Any other data generated specific to a signed order should also be archived. For example, if digital files are generated when an order is acknowledged, or upon physical receipt to the purchaser “checking-in” the contents, these should be archived as well.
Audit Process Auditing the solution is a case-by-case basis. Likely this will involve browsing to the archive location for a newly created order.

Audit Case 13

This audit case verifies the certificate used in signing was issued to an individual associated with the purchaser. A pharmacy (as one example) is provided a DEA number for use with purchasing controlled substances. This number is required to be associated with every order the pharmacy makes. When a certificate is issued to an individual, they are signing orders on behalf of the purchaser. Therefore, the DEA number for a pharmacy is part of the metadata for any individuals signing orders for that pharmacy.
CSOS Development White Paper The DEA number is not explicit in the metadata for the certificate. Instead, a SHA-1 (or SHA-256, see below) hash of the purchaser’s DEA number joined with the certificate serial number is. (See CSOS Certificate and CRL Profile (PDF) 3.3.7)
Validation In order to validate a certificate, the DEA number of purchaser must be known. To validate: 1) Parse the Serial Number from the certificate. This can be done using the certificate’s “subject”. (See screenshot) 2) Concatenate the DEA Number with the Serial Number 3) Create a hash of this string.
Note: The Public Key Infrastructure Analysis document indicates the hashing algorithm is SHA-1. It is undocumented that the “Signature algorithm” field of the certificate indicates whether a SHA-1 or SHA-256 algorithm should be used. The screenshot shows a certificate using the SHA-256. 4) The metadata field for OID “2.16.840.1.101.3.5.7” contains the hashed value for comparison. (See CSOS Certificate and CRL Profile (PDF) 6.2) 5) Compare the hashes. If they match, validation succeeds.
Please note that in development, it was determined there was a whitespace offset of the field in the certificate. Documentation of this offset could not be found. For SHA-256 it was a 2 character offset of hex values “0x04” and “0x20”; for SHA-1 it was a 2 character offset of hex values “0x04” and “0x14”.
Audit Process Signing with a certificate associated with a DEA number different than that of the one used to create the test order should fail validation.

If we can be of any assistance regarding CSOS, please drop us a line here!

capabilities covered
Drupal Magento CMS Solutions Quality Assurance PHP System Architecture Salesforce & CRM Integration WordPress Software Development Hosting Cloud Services .NET

The Atlantic BT Manifesto

The Ultimate Guide To Planning A Complex Web Project

Partner With Us

Ready for modern web technology and a sharp, user-friendly design? We want to give you exactly that. Contact us to get started.

Contact
  • This field is for validation purposes and should be left unchanged.