storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/cmd/crypto/doc.go (about) 1 // MinIO Cloud Storage, (C) 2015, 2016, 2017, 2018 MinIO, Inc. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // Package crypto implements AWS S3 related cryptographic building blocks 16 // for implementing Server-Side-Encryption (SSE-S3) and Server-Side-Encryption 17 // with customer provided keys (SSE-C). 18 // 19 // All objects are encrypted with an unique and randomly generated 'ObjectKey'. 20 // The ObjectKey itself is never stored in plaintext. Instead it is only stored 21 // in a sealed from. The sealed 'ObjectKey' is created by encrypting the 'ObjectKey' 22 // with an unique key-encryption-key. Given the correct key-encryption-key the 23 // sealed 'ObjectKey' can be unsealed and the object can be decrypted. 24 // 25 // 26 // ## SSE-C 27 // 28 // SSE-C computes the key-encryption-key from the client-provided key, an 29 // initialization vector (IV) and the bucket/object path. 30 // 31 // 1. Encrypt: 32 // Input: ClientKey, bucket, object, metadata, object_data 33 // - IV := Random({0,1}²⁵⁶) 34 // - ObjectKey := SHA256(ClientKey || Random({0,1}²⁵⁶)) 35 // - KeyEncKey := HMAC-SHA256(ClientKey, IV || 'SSE-C' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) 36 // - SealedKey := DAREv2_Enc(KeyEncKey, ObjectKey) 37 // - enc_object_data := DAREv2_Enc(ObjectKey, object_data) 38 // - metadata <- IV 39 // - metadata <- SealedKey 40 // Output: enc_object_data, metadata 41 // 42 // 2. Decrypt: 43 // Input: ClientKey, bucket, object, metadata, enc_object_data 44 // - IV <- metadata 45 // - SealedKey <- metadata 46 // - KeyEncKey := HMAC-SHA256(ClientKey, IV || 'SSE-C' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) 47 // - ObjectKey := DAREv2_Dec(KeyEncKey, SealedKey) 48 // - object_data := DAREv2_Dec(ObjectKey, enc_object_data) 49 // Output: object_data 50 // 51 // 52 // ## SSE-S3 53 // 54 // SSE-S3 can use either a master key or a KMS as root-of-trust. 55 // The en/decryption slightly depens upon which root-of-trust is used. 56 // 57 // ### SSE-S3 and single master key 58 // 59 // The master key is used to derive unique object- and key-encryption-keys. 60 // SSE-S3 with a single master key works as SSE-C where the master key is 61 // used as the client-provided key. 62 // 63 // 1. Encrypt: 64 // Input: MasterKey, bucket, object, metadata, object_data 65 // - IV := Random({0,1}²⁵⁶) 66 // - ObjectKey := SHA256(MasterKey || Random({0,1}²⁵⁶)) 67 // - KeyEncKey := HMAC-SHA256(MasterKey, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) 68 // - SealedKey := DAREv2_Enc(KeyEncKey, ObjectKey) 69 // - enc_object_data := DAREv2_Enc(ObjectKey, object_data) 70 // - metadata <- IV 71 // - metadata <- SealedKey 72 // Output: enc_object_data, metadata 73 // 74 // 2. Decrypt: 75 // Input: MasterKey, bucket, object, metadata, enc_object_data 76 // - IV <- metadata 77 // - SealedKey <- metadata 78 // - KeyEncKey := HMAC-SHA256(MasterKey, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) 79 // - ObjectKey := DAREv2_Dec(KeyEncKey, SealedKey) 80 // - object_data := DAREv2_Dec(ObjectKey, enc_object_data) 81 // Output: object_data 82 // 83 // 84 // ### SSE-S3 and KMS 85 // 86 // SSE-S3 requires that the KMS provides two functions: 87 // 1. Generate(KeyID) -> (Key, EncKey) 88 // 2. Unseal(KeyID, EncKey) -> Key 89 // 90 // 1. Encrypt: 91 // Input: KeyID, bucket, object, metadata, object_data 92 // - Key, EncKey := Generate(KeyID) 93 // - IV := Random({0,1}²⁵⁶) 94 // - ObjectKey := SHA256(Key, Random({0,1}²⁵⁶)) 95 // - KeyEncKey := HMAC-SHA256(Key, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) 96 // - SealedKey := DAREv2_Enc(KeyEncKey, ObjectKey) 97 // - enc_object_data := DAREv2_Enc(ObjectKey, object_data) 98 // - metadata <- IV 99 // - metadata <- KeyID 100 // - metadata <- EncKey 101 // - metadata <- SealedKey 102 // Output: enc_object_data, metadata 103 // 104 // 2. Decrypt: 105 // Input: bucket, object, metadata, enc_object_data 106 // - KeyID <- metadata 107 // - EncKey <- metadata 108 // - IV <- metadata 109 // - SealedKey <- metadata 110 // - Key := Unseal(KeyID, EncKey) 111 // - KeyEncKey := HMAC-SHA256(Key, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) 112 // - ObjectKey := DAREv2_Dec(KeyEncKey, SealedKey) 113 // - object_data := DAREv2_Dec(ObjectKey, enc_object_data) 114 // Output: object_data 115 // 116 package crypto