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