Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/object-storage.rst @ 463:fae16ea8b13c
new AWS params
| author | Alain Mazy <alain@mazy.be> |
|---|---|
| date | Thu, 09 Jul 2020 10:44:52 +0200 |
| parents | a4ed4e883337 |
| children | 5ea70331c0be |
| rev | line source |
|---|---|
| 451 | 1 .. _object-storage: |
| 2 | |
| 3 | |
| 4 Cloud Object Storage plugins | |
| 5 ============================ | |
| 6 | |
| 7 .. contents:: | |
| 8 | |
| 9 | |
| 10 Introduction | |
| 11 ------------ | |
| 12 | |
| 13 Osimis freely provides the `source code | |
| 14 <https://hg.orthanc-server.com/orthanc-object-storage/file/default/>`__ of 3 plugins | |
| 15 to store the Orthanc files in `Object Storage <https://en.wikipedia.org/wiki/Object_storage>`__ | |
| 16 at the 3 main providers: `AWS <https://aws.amazon.com/s3/>`__, | |
| 17 `Azure <https://azure.microsoft.com/en-us/services/storage/blobs/>`__ & | |
| 18 `Google Cloud <https://cloud.google.com/storage>`__ | |
| 19 | |
| 20 Storing Orthanc files in object storage and your index SQL in a | |
| 21 managed database allows you to have a stateless Orthanc that does | |
| 22 not store any data in its local file system which is highly recommended | |
| 23 when deploying an application in the cloud. | |
| 24 | |
| 25 | |
|
459
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
26 Pre-compiled binaries |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
27 --------------------- |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
28 |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
29 These plugins are used to interface Orthanc with commercial and |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
30 proprietary cloud services that you accept to pay. As a consequence, |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
31 the Orthanc project doesn't freely provide pre-compiled binaries for |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
32 Docker, Windows, Linux or OS X. These pre-compiled binaries do exist, |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
33 but are reserved to the companies who have subscribed to a |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
34 `professional support contract |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
35 <https://www.osimis.io/en/services.html#cloud-plugins>`__ by |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
36 Osimis. Although you are obviously free to compile these plugins by |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
37 yourself (instructions are given below), purchasing such support |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
38 contracts makes the Orthanc project sustainable in the long term, to |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
39 the benefit of the worldwide community of medical imaging. |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
40 |
|
a4ed4e883337
highlighting the pre-compiled binaries for google, aws and azure
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
453
diff
changeset
|
41 |
| 451 | 42 Compilation |
| 43 ----------- | |
| 44 | |
| 45 .. highlight:: text | |
| 46 | |
| 47 The procedure to compile the plugins is quite similar of that for the | |
| 48 :ref:`core of Orthanc <compiling>` although they usually require | |
| 49 some prerequisites. The documented procedure has been tested only | |
| 50 on a Debian Buster machine. | |
| 51 | |
| 52 The compilation of each plugin produces a shared library that contains | |
| 53 the plugin. | |
| 54 | |
| 55 | |
| 56 AWS S3 plugin | |
| 57 ^^^^^^^^^^^^^ | |
| 58 | |
| 59 Prerequisites: Compile the AWS C++ SDK:: | |
| 60 | |
| 61 $ mkdir ~/aws | |
| 62 $ cd ~/aws | |
| 63 $ git clone https://github.com/aws/aws-sdk-cpp.git | |
| 64 $ | |
| 65 $ mkdir -p ~/aws/builds/aws-sdk-cpp | |
| 66 $ cd ~/aws/builds/aws-sdk-cpp | |
| 67 $ cmake -DBUILD_ONLY="s3;transfer" ~/aws/aws-sdk-cpp | |
| 68 $ make -j 4 | |
| 69 $ make install | |
| 70 | |
| 71 Prerequisites: Install `vcpkg <https://github.com/Microsoft/vcpkg>`__ dependencies:: | |
| 72 | |
| 73 $ ./vcpkg install cryptopp | |
| 74 | |
| 75 Compile:: | |
| 76 | |
| 77 $ mkdir -p build/aws | |
| 78 $ cd build/aws | |
| 79 $ cmake -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]\scripts\buildsystems\vcpkg.cmake ../../orthanc-object-storage/Aws | |
| 80 | |
| 81 Azure Blob Storage plugin | |
| 82 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 83 | |
| 84 Prerequisites: Install `vcpkg <https://github.com/Microsoft/vcpkg>`__ dependencies:: | |
| 85 | |
| 86 $ ./vcpkg install cpprestsdk | |
| 87 | |
| 88 | |
| 89 Compile:: | |
| 90 | |
| 91 $ mkdir -p build/azure | |
| 92 $ cd build/azure | |
| 93 $ cmake -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]\scripts\buildsystems\vcpkg.cmake ../../orthanc-object-storage/Azure | |
| 94 | |
| 95 Google Storage plugin | |
| 96 ^^^^^^^^^^^^^^^^^^^^^ | |
| 97 | |
| 98 Prerequisites: Install `vcpkg <https://github.com/Microsoft/vcpkg>`__ dependencies:: | |
| 99 | |
| 100 $ ./vcpkg install google-cloud-cpp | |
| 101 $ ./vcpkg install cryptopp | |
| 102 | |
| 103 Compile:: | |
| 104 | |
| 105 $ mkdir -p build/google | |
| 106 $ cd build/google | |
| 107 $ cmake -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]\scripts\buildsystems\vcpkg.cmake ../../orthanc-object-storage/google | |
| 108 | |
| 109 | |
| 110 Configuration | |
| 111 ------------- | |
| 112 | |
| 113 .. highlight:: json | |
| 114 | |
| 115 AWS S3 plugin | |
| 116 ^^^^^^^^^^^^^ | |
| 117 | |
| 118 Sample configuration:: | |
| 119 | |
| 120 "AwsS3Storage" : { | |
| 121 "BucketName": "test-orthanc-s3-plugin", | |
| 122 "Region" : "eu-central-1", | |
| 123 "AccessKey" : "AKXXX", | |
| 463 | 124 "SecretKey" : "RhYYYY", |
| 125 "Endpoint": "", // optional - currently in mainline version only: custom endpoint | |
| 126 "ConnectionTimeout": 30, // optional - currently in mainline version only: connection timeout in seconds | |
| 127 "RequestTimeout": 1200 // optional - currently in mainline version only: request timeout in seconds (max time to upload/download a file) | |
| 451 | 128 } |
| 129 | |
| 130 Azure Blob Storage plugin | |
| 131 ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 132 | |
| 133 Sample configuration:: | |
| 134 | |
| 135 "AzureBlobStorage" : { | |
| 136 "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=xxxxxxxxx;AccountKey=yyyyyyyy===;EndpointSuffix=core.windows.net", | |
| 137 "ContainerName" : "test-orthanc-storage-plugin" | |
| 138 } | |
| 139 | |
| 140 | |
| 141 Google Storage plugin | |
| 142 ^^^^^^^^^^^^^^^^^^^^^ | |
| 143 | |
| 144 Sample configuration:: | |
| 145 | |
| 146 "GoogleCloudStorage" : { | |
| 147 "ServiceAccountFile": "/path/to/googleServiceAccountFile.json", | |
| 148 "BucketName": "test-orthanc-storage-plugin" | |
| 149 } | |
| 150 | |
| 151 | |
| 452 | 152 Sample setups |
| 153 ------------- | |
| 154 | |
| 155 You'll find sample deployments and more info in the `Orthanc Setup Samples repository <https://bitbucket.org/osimis/orthanc-setup-samples/src/master/#markdown-header-for-osimisorthanc-pro-image-users>`__ . | |
| 156 | |
| 157 | |
| 451 | 158 Client-side encryption |
| 159 ---------------------- | |
| 160 | |
| 161 Although all cloud providers already provide encryption at rest, the plugins provide | |
| 162 an optional layer of client-side encryption . It is very important that you understand | |
| 163 the scope and benefits of this additional layer of encryption. | |
| 164 | |
| 165 Rationale | |
| 166 ^^^^^^^^^ | |
| 167 | |
| 168 Encryption at rest provided by cloud providers basically compares with a file-system disk encryption. | |
| 169 If someone has access to the disk, he won't have access to your data without the encryption key. | |
| 170 | |
| 171 With cloud encryption at rest only, if someone has access to the "api-key" of your storage or if one | |
| 172 of your admin inadvertently make your storage public, `PHI <https://en.wikipedia.org/wiki/Protected_health_information>`__ will leak. | |
| 173 | |
| 174 Once you use client-side encryption, you'll basically store packets of meaningless bytes on the cloud infrastructure. | |
| 175 So, if an "api-key" leaks or if the storage is misconfigured, packets of bytes will leak but not PHI since | |
| 176 no one will be able to decrypt them. | |
| 177 | |
| 178 Another advantage is that these packets of bytes might eventually not be considered as PHI anymore and eventually | |
| 179 help you meet your local regulations (Please check your local regulations). | |
| 180 | |
| 181 However, note that, if you're running entirely in a cloud environment, your decryption keys will still | |
| 182 be stored on the cloud infrastructure (VM disks - process RAM) and an attacker could still eventually gain access to this keys. | |
| 183 | |
| 184 If Orthanc is running in your infrastructure with the Index DB on your infrastructure, and files are store in the cloud, | |
| 185 the master keys will remain on your infrastructure only and there's no way the data stored in the cloud could be decrypted outside your infrastructure. | |
| 186 | |
| 187 Also note that, although the cloud providers also provide client-side encryption, we, as an open-source project, | |
| 188 wanted to provide our own implementation on which you'll have full control and extension capabilities. | |
| 189 This also allows us to implement the same logic on all cloud providers. | |
| 190 | |
| 191 Our encryption is based on well-known standards (see below). Since it is documented and the source code is open-source, | |
| 192 feel-free to have your security expert review it before using it in a production environment. | |
| 193 | |
| 194 Technical details | |
| 195 ^^^^^^^^^^^^^^^^^ | |
| 196 | |
| 197 Orthanc saves 2 kind of files: DICOM files and JSON summaries of DICOM files. Both files contain PHI. | |
| 198 | |
| 452 | 199 When configuring the plugin, you'll have to provide a **Master Key** that we can also call the **Key Encryption Key (KEK)**. |
| 451 | 200 |
| 452 | 201 For each file being saved, the plugin will generate a new **Data Encryption Key (DEK)**. This DEK, encrypted with the KEK will be pre-pended to the file. |
| 451 | 202 |
| 203 If, at any point, your KEK leaks or you want to rotate your KEKs, you'll be able to use a new one to encrypt new files that are being added | |
| 204 and still use the old ones to decrypt data. You could then eventually start a side script to remove usages of the leaked/obsolete KEKs. | |
| 205 | |
| 206 To summarize: | |
| 207 | |
| 452 | 208 - We use `Crypto++ <https://www.cryptopp.com/>`__ to perform all encryptions. |
| 451 | 209 - All keys (KEK and DEK) are AES-256 keys. |
| 210 - DEKs and IVs are encrypted by KEK using CTR block cipher using a null IV. | |
| 211 - data is encrypted by DEK using GCM block cipher that will also perform integrity check on the whole file. | |
| 212 | |
| 213 The format of data stored on disk is therefore the following: | |
| 214 | |
| 215 - **VERSION HEADER**: 2 bytes: identify the structure of the following data currently `A1` | |
| 216 - **MASTER KEY ID**: 4 bytes: a numerical ID of the KEK that was used to encrypt the DEK | |
| 217 - **EIV**: 32 bytes: IV used by DEK for data encryption; encrypted by KEK | |
| 218 - **EDEK**: 32 bytes: the DEK encrypted by the KEK. | |
| 219 - **CIPHER TEXT**: variable length: the DICOM/JSON file encrypted by the DEK | |
| 220 - **TAG**: 16 bytes: integrity check performed on the whole encrypted file (including header, master key id, EIV and EDEK) | |
| 221 | |
| 222 Configuration | |
| 223 ^^^^^^^^^^^^^ | |
| 224 | |
| 225 .. highlight:: text | |
| 226 | |
| 227 AES Keys shall be 32 bytes long (256 bits) and encoded in base64. Here's a sample OpenSSL command to generate such a key:: | |
| 228 | |
| 229 openssl rand -base64 -out /tmp/test.key 32 | |
| 230 | |
| 231 Each key must have a unique id that is a uint32 number. | |
| 232 | |
| 233 .. highlight:: json | |
| 234 | |
| 235 Here's a sample configuration file of the `StorageEncryption` section of the plugins:: | |
| 236 | |
| 237 { | |
| 238 "StorageEncryption" : { | |
| 239 "Enable": true, | |
| 240 "MasterKey": [3, "/path/to/master.key"], // key id - path to the base64 encoded key | |
| 241 "PreviousMasterKeys" : [ | |
| 242 [1, "/path/to/previous1.key"], | |
| 243 [2, "/path/to/previous2.key"] | |
| 244 ], | |
| 245 "MaxConcurrentInputSize" : 1024 // size in MB | |
| 246 } | |
| 247 } | |
| 248 | |
| 249 **MaxConcurrentInputSize**: Since the memory used during encryption/decryption can grow up to a bit more | |
| 250 than 2 times the input, we want to limit the number of threads doing concurrent processing according | |
| 251 to the available memory instead of the number of concurrent threads. Therefore, if you're currently | |
| 252 ingesting small files, you can have a lot of thread working together while, if you're ingesting large | |
| 253 files, threads might have to wait before receiving a "slot" to access the encryption module. |