//------------------------------------------------------------------------------
// <copyright file="Purpose.cs" company="Microsoft">
//     Copyright (c) Microsoft Corporation.  All rights reserved.
// </copyright>                                                                
//------------------------------------------------------------------------------

namespace System.Web.Security.Cryptography {
    using System;
    using System.Collections.Generic;
    using System.IO;
    using System.Text;

    // Represents a purpose that can be passed to a cryptographic routine to control key derivation / ciphertext modification.
    // This is hardening the crypto routines to prevent playing ciphertext off of components that didn't generate them.
    //
    // !! IMPORTANT !!
    // The built-in purposes do not contain privileged information and are not meant to be treated as secrets. Any external
    // person can disassemble our code or look directly at our source to see what our Purpose objects are used for.
    //
    // PrimaryPurpose: This is a well-known string that identifies the reason for this Purpose. The pattern we use
    // is that PrimaryPurpose is the name of the consumer, making each consumer's Purpose unique.
    //
    // SpecificPurposes: These are extra optional strings that further differentiate Purpose objects that might have the
    // same PrimaryPurpose. The pattern we use is that if a single consumer has multiple Purposes, he can use
    // SpecificPurposes to uniquely identify them. The information here is generally not secret (we can put the type of
    // the currently executing Page here, for example), but it is valid to seed this property with a secret obtained
    // at runtime (such as a nonce shared between two parties).

    internal sealed class Purpose {

        // predefined purposes
        public static readonly Purpose AnonymousIdentificationModule_Ticket = new Purpose("AnonymousIdentificationModule.Ticket");
        public static readonly Purpose AssemblyResourceLoader_WebResourceUrl = new Purpose("AssemblyResourceLoader.WebResourceUrl");
        public static readonly Purpose FormsAuthentication_Ticket = new Purpose("FormsAuthentication.Ticket");
        public static readonly Purpose WebForms_Page_PreviousPageID = new Purpose("WebForms.Page.PreviousPageID");
        public static readonly Purpose RolePrincipal_Ticket = new Purpose("RolePrincipal.Ticket");
        public static readonly Purpose ScriptResourceHandler_ScriptResourceUrl = new Purpose("ScriptResourceHandler.ScriptResourceUrl");

        // predefined ViewState purposes; they won't be used as-is (they're combined with the page information)
        public static readonly Purpose WebForms_ClientScriptManager_EventValidation = new Purpose("WebForms.ClientScriptManager.EventValidation");
        public static readonly Purpose WebForms_DetailsView_KeyTable = new Purpose("WebForms.DetailsView.KeyTable");
        public static readonly Purpose WebForms_GridView_DataKeys = new Purpose("WebForms.GridView.DataKeys");
        public static readonly Purpose WebForms_GridView_SortExpression = new Purpose("WebForms.GridView.SortExpression");
        public static readonly Purpose WebForms_HiddenFieldPageStatePersister_ClientState = new Purpose("WebForms.HiddenFieldPageStatePersister.ClientState");
        public static readonly Purpose WebForms_ScriptManager_HistoryState = new Purpose("WebForms.ScriptManager.HistoryState");
        public static readonly Purpose WebForms_SessionPageStatePersister_ClientState = new Purpose("WebForms.SessionPageStatePersister.ClientState");

        // predefined miscellaneoous purposes; they won't be used as-is (they're combined with other specificPurposes)
        public static readonly Purpose User_MachineKey_Protect = new Purpose("User.MachineKey.Protect"); // used by the MachineKey static class Protect / Unprotect methods
        public static readonly Purpose User_ObjectStateFormatter_Serialize = new Purpose("User.ObjectStateFormatter.Serialize"); // used by ObjectStateFormatter.Serialize() if called manually

        public readonly string PrimaryPurpose;
        public readonly string[] SpecificPurposes;

        private byte[] _derivedKeyLabel;
        private byte[] _derivedKeyContext;

        public Purpose(string primaryPurpose, params string[] specificPurposes)
            : this(primaryPurpose, specificPurposes, null, null) {
        }

        // ctor for unit testing
        internal Purpose(string primaryPurpose, string[] specificPurposes, CryptographicKey derivedEncryptionKey, CryptographicKey derivedValidationKey) {
            PrimaryPurpose = primaryPurpose;
            SpecificPurposes = specificPurposes ?? new string[0];
            DerivedEncryptionKey = derivedEncryptionKey;
            DerivedValidationKey = derivedValidationKey;
            SaveDerivedKeys = (SpecificPurposes.Length == 0);
        }

        // The cryptographic keys that were derived from this Purpose.
        internal CryptographicKey DerivedEncryptionKey { get; private set; }
        internal CryptographicKey DerivedValidationKey { get; private set; }

        // Whether the derived key should be saved back to this Purpose object by the ICryptoService,
        // e.g. because this Purpose will be used over and over again. We assume that any built-in
        // Purpose object that is passed without any specific purposes is intended for repeated use,
        // hence the ICryptoService will try to cache cryptographic keys as a performance optimization.
        // If specific purposes have been specified, they were likely generated at runtime, hence it
        // is not appropriate for the keys to be cached in this instance.
        internal bool SaveDerivedKeys { get; set; }

        // Returns a new Purpose which is the specified Purpose plus the specified SpecificPurpose.
        // Leaves the original Purpose unmodified.
        internal Purpose AppendSpecificPurpose(string specificPurpose) {
            // Append the specified specificPurpose to the existing list
            string[] newSpecificPurposes = new string[SpecificPurposes.Length + 1];
            Array.Copy(SpecificPurposes, newSpecificPurposes, SpecificPurposes.Length);
            newSpecificPurposes[newSpecificPurposes.Length - 1] = specificPurpose;
            return new Purpose(PrimaryPurpose, newSpecificPurposes);
        }

        // Returns a new Purpose which is the specified Purpose plus the specified SpecificPurposes.
        // Leaves the original Purpose unmodified.
        internal Purpose AppendSpecificPurposes(IList<string> specificPurposes) {
            // No specific purposes to add
            if (specificPurposes == null || specificPurposes.Count == 0) {
                return this;
            }

            // Append the specified specificPurposes to the existing list
            string[] newSpecificPurposes = new string[SpecificPurposes.Length + specificPurposes.Count];
            Array.Copy(SpecificPurposes, newSpecificPurposes, SpecificPurposes.Length);
            specificPurposes.CopyTo(newSpecificPurposes, SpecificPurposes.Length);
            return new Purpose(PrimaryPurpose, newSpecificPurposes);
        }

        public CryptographicKey GetDerivedEncryptionKey(IMasterKeyProvider masterKeyProvider, KeyDerivationFunction keyDerivationFunction) {
            // has a key already been stored?
            CryptographicKey actualDerivedKey = DerivedEncryptionKey;
            if (actualDerivedKey == null) {
                CryptographicKey masterKey = masterKeyProvider.GetEncryptionKey();
                actualDerivedKey = keyDerivationFunction(masterKey, this);

                // only save the key back to storage if this Purpose is configured to do so
                if (SaveDerivedKeys) {
                    DerivedEncryptionKey = actualDerivedKey;
                }
            }

            return actualDerivedKey;
        }

        public CryptographicKey GetDerivedValidationKey(IMasterKeyProvider masterKeyProvider, KeyDerivationFunction keyDerivationFunction) {
            // has a key already been stored?
            CryptographicKey actualDerivedKey = DerivedValidationKey;
            if (actualDerivedKey == null) {
                CryptographicKey masterKey = masterKeyProvider.GetValidationKey();
                actualDerivedKey = keyDerivationFunction(masterKey, this);

                // only save the key back to storage if this Purpose is configured to do so
                if (SaveDerivedKeys) {
                    DerivedValidationKey = actualDerivedKey;
                }
            }

            return actualDerivedKey;
        }

        // Returns a label and context suitable for passing into the SP800-108 KDF.
        internal void GetKeyDerivationParameters(out byte[] label, out byte[] context) {
            // The primary purpose can just be used as the label directly, since ASP.NET
            // is always in full control of the primary purpose (it's never user-specified).
            if (_derivedKeyLabel == null) {
                _derivedKeyLabel = CryptoUtil.SecureUTF8Encoding.GetBytes(PrimaryPurpose);
            }

            // The specific purposes (which can contain nonce, identity, etc.) are concatenated
            // together to form the context. The BinaryWriter class prepends each element with
            // a 7-bit encoded length to guarantee uniqueness.
            if (_derivedKeyContext == null) {
                using (MemoryStream stream = new MemoryStream())
                using (BinaryWriter writer = new BinaryWriter(stream, CryptoUtil.SecureUTF8Encoding)) {
                    foreach (string specificPurpose in SpecificPurposes) {
                        writer.Write(specificPurpose);
                    }
                    _derivedKeyContext = stream.ToArray();
                }
            }

            label = _derivedKeyLabel;
            context = _derivedKeyContext;
        }

    }
}