Security Technical Information

Note that this page is specifically written with technical information in mind. A step by step guide to using this information can be found here.

Web Services Security

CWS uses OpenSSL public/private key encryption for all webservices. Each request sent to CWS is expected to be signed with an RSA private key corresponding to a public key previously added to the system.

Authorization

To access the webservices, a public key must be added along with a corresponding username. The key users are not intertwined with the normal CorEMR users.

Key Generation

OpenSSL is able to generate an RSA keypair. CorEMR itself uses a 4096-bit key and the minimum recommended bitlength is 2048.

Limitations

  • All keys must be in PEM public key format.
  • Usernames are unique and cannot be used more than once for any active key.
  • Once a key is added, it cannot be altered.

Signature

Generation

All request bodies are signed via the associated client's private key using available hashing algorithm and then base64 encoded. For CWS actions that have an empty request body (such as GET requests), an empty string should be signed.

Steps

  1. Get contents.
    • If PUT or POST verbs, use message body.
    • If GET verb, use empty string.
  2. Sign contents with private key using selected hashing algorithm.
  3. base64-encode signed contents.

HTTP Header

A valid signature should be sent in the HTTP "Authorization" header indicating signature generation algorithm and access user in the following format:

Authorization: ALGORITHM Access=USER, Signature=SIGNATURE

  1. ALGORITHM indicates an available signature generation algorithm. See algorithm table below for available algorithms.
  2. USER is the assigned key username previously added to the system.
  3. SIGNATURE is the generated signature value per request.

None of the pieces are escaped.

Available Signature Generation Algorithms

CWS Version Algorithm Authorization Header Value
V1 SHA1 CWS-SHA1
V2 SHA1 CWS-SHA1
V2 SHA256 CWS-SHA256