با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
در عمل، Tink اشیاء Key را برای نمایش کلیدها و اشیاء Parameters را برای نمایش Parameters فراهم می کند. به عنوان مثال، در جاوا، ما اشیاء AesGcmKey برای نمایش کلیدهای AES GCM داریم.
در این قسمت نحوه طراحی این اشیاء در جاوا و نحوه تعامل آنها را توضیح می دهیم.
Parameters اشیاء
AES GCM را در نظر بگیرید، یک طرح رمزگذاری AEAD که به طور گسترده مورد استفاده قرار می گیرد. Tink یک شی AesGcmParameters را با اطلاعات لازم برای ایجاد یک AesGcmKey فراهم می کند که در ادامه توضیح خواهیم داد. سلسله مراتب پارامترها در جاوا به صورت زیر است:
publicabstractclassParameters{publicabstractbooleanhasIdRequirement();}publicabstractclassAeadParametersextendsParameters{}publicfinalclassAesGcmParametersextendsAeadParameters{/** * The Variant specified how ciphertexts are [tagged](/tink/design/keysets#tagging_ciphertexts). */publicstaticfinalclassVariant{...}/** A helper object to create new AesGcmParameters. */publicstaticfinalclassBuilder{...}publicintgetKeySizeBytes(){...}publicintgetIvSizeBytes(){...}publicintgetTagSizeBytes(){...}publicVariantgetVariant(){...}publicOutputPrefixTypegetOutputPrefixType(){...}publicbooleanequals(Objectobject){...}publicinthashCode(){...}}
همانطور که در بخش Keysets، Tagging Ciphertexts توضیح داده شد، برخی از کلیدها زمانی که در یک مجموعه کلید قرار دارند، یک الزام در شناسه خود دارند. هر شیء Parameters دارای یک متد hasIdRequirement است که مشخص می کند آیا کلید ایجاد شده توسط این شیء Parameters چنین id مورد نیازی خواهد داشت یا خیر.
شیء AesGcmParameters متدهای getKeySizeBytes() ، getIvSizeBytes() و getTagSizeBytes() را ارائه می دهد. اینها طول کلید استفاده شده، طول IV استفاده شده و طول تگ تولید شده را بر حسب بایت برمی گرداند. در حالی که Tink برخی از این توابع را برای کامل بودن فراهم می کند، همیشه اجازه ایجاد Aead را برای هر انتخابی نمی دهد. به عنوان مثال، در حال حاضر تنها 12 بایت IV برای AES GCM پشتیبانی می شود.
شیء AesGcmParameters همچنین برای روش‌های تعریف‌شده قبلی (و روش‌های استاندارد جاوا equals و hashCode که عمل خوبی در نظر گرفته می‌شود) لغو می‌کند.
در نهایت، متدهای ایستا را برای ایجاد اشیاء جدید AeadParameters فراهم می کند. اینها ورودی ها را تأیید می کنند، یعنی بررسی می کنند که اندازه یکی از 16، 24 یا 32 باشد.
اشیاء کلیدی
تینک همچنین یک سلسله مراتب کلیدی دارد. با وجود مثال ما از AES GCM، به نظر می رسد:
متد getIdRequirementOrNull شناسه ای را که این کلید باید داشته باشد برمی گرداند یا اگر نیازی وجود نداشته باشد null برمی گرداند. (چنین الزامی در مورد کلید از این واقعیت ناشی می شود که Tink در برخی موارد متن های رمزی یا امضا را با رشته 0x01<id> پیشوند می دهد، به بخش برچسب گذاری متن رمزی مراجعه کنید).
این همیشه با نتیجه getParameters().hasIdRequirement() مطابقت دارد و پیاده‌کننده‌های کلاس‌های کلید جدید باید از این اطمینان حاصل کنند.
پیاده‌سازی‌های Key همچنین باید روشی equalsKey برای مقایسه کلیدهای مختلف ارائه کنند. چنین روشی اغلب مفید است: برای مثال هنگام آزمایش اشتقاق کلید، فرد علاقه مند است اطمینان حاصل کند که استفاده مکرر از مشتق، همان شی کلید را به دست می دهد. همچنین، یک KMS ممکن است بخواهد بررسی کند که آیا هر یک از کلیدهایی که به کاربران مختلف ارائه می دهد برابر هستند یا نه (که گاهی اوقات اگر کاربران کلیدها را به اشتراک بگذارند و چندین بار آنها را در همان KMS آپلود کنند اتفاق می افتد). قابل توجه است که ما متد جاوا equals را نادیده نمی گیریم، زیرا این امر مستلزم نادیده گرفتن hashCode است و هیچ راهی برای پیاده سازی hashCode به روشی ایمن و سازگار با equals بدون ایجاد فرضیات اثبات نشده وجود ندارد.
در مرحله بعد، به یک متد getParameters() نیاز داریم. این به کاربران اجازه می دهد تا اطلاعات اصلی در مورد پارامترهای مورد استفاده برای ایجاد کلید را دریافت کنند.
در نهایت، AesGcmKey یک متد getKeyBytes دارد که مواد کلید خام را برمی گرداند. چنین روش‌هایی برای کلاس‌های کلیدی بسیار معمولی هستند: آنها مختص نوع هستند و دسترسی به مواد کلیدی زیرین را فراهم می‌کنند. با استفاده از آن ها، کاربران می توانند اصولاً به عنوان مثال، کلید اولیه را که توسط کلید نشان داده شده است، پیاده سازی کنند، یا کلید را سریالی کنند تا آن را روی دیسک ذخیره کنند یا از طریق شبکه ارسال کنند. خود کلید مسئول محافظت از مواد کلیدی در برابر دسترسی غیرمجاز است. به عنوان مثال، SecretBytes به یک نشانه دسترسی برای ارائه واقعی مطالب نیاز دارد (به کنترل دسترسی مراجعه کنید).
کلیدهای نامتقارن
برای موارد اولیه نامتقارن، Tink از دو کلاس کلید، یکی برای خصوصی و دیگری برای کلیدهای عمومی استفاده می کند. برای پارامترها، استفاده از یک کلاس راحت تر است (زیرا فقط یک کلاس وجود دارد که می تواند برای تولید کلیدها استفاده شود).
Tink همچنین دارای یک رابط PrivateKey با تابع اضافی getPublicKey() است.
تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eTink uses \u003ccode\u003eKey\u003c/code\u003e objects to represent keys and \u003ccode\u003eParameters\u003c/code\u003e objects to represent parameters, organizing them in class hierarchies for different cryptographic primitives like AES GCM.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eParameters\u003c/code\u003e objects contain information like key size, IV size, tag size, and whether the key requires an ID; they are used to create corresponding \u003ccode\u003eKey\u003c/code\u003e objects.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eKey\u003c/code\u003e objects provide access to key material, parameters, and ID requirements, with methods like \u003ccode\u003egetKeyBytes\u003c/code\u003e and \u003ccode\u003egetParameters\u003c/code\u003e ensuring secure access and key management.\u003c/p\u003e\n"],["\u003cp\u003eAsymmetric primitives utilize separate key classes for private and public keys, with a \u003ccode\u003ePrivateKey\u003c/code\u003e interface including a \u003ccode\u003egetPublicKey()\u003c/code\u003e function for key pair management.\u003c/p\u003e\n"],["\u003cp\u003eKey equality is checked using \u003ccode\u003eequalsKey\u003c/code\u003e rather than overriding Java's \u003ccode\u003eequals\u003c/code\u003e method to avoid potential security issues related to hash code implementation and key comparisons.\u003c/p\u003e\n"]]],["Tink utilizes `Key` objects for keys and `Parameters` objects for configuration. `AesGcmParameters` specifies AES GCM parameters like key, IV, and tag sizes and whether an ID is required. `AesGcmKey` implements `AeadKey`, providing methods for accessing raw key material (`getKeyBytes`), associated parameters, and any required ID. Key classes also implement `equalsKey` to compare keys and `getParameters` to retrieve parameter information. Asymmetric primitives employ distinct private and public key classes with shared `Parameters` and a `getPublicKey` method on `PrivateKey`.\n"],null,["# Key and Parameters Objects\n\n| This section describes the future design of Tink. The current status may depend on the programming language used.\n\nIn practice, Tink provides `Key` objects to represent\n[keys](/tink/design/keys) and `Parameters` objects to represent `Parameters`.\nFor example, in Java, we have `AesGcmKey` objects to\nrepresent AES GCM keys.\n\nIn this section, we explain how these objects are designed in Java and how they\ninteract.\n\n`Parameters` objects\n--------------------\n\nConsider AES GCM, a widely used AEAD encryption scheme.\nTink provides an `AesGcmParameters` object with the necessary information to\ncreate a `AesGcmKey`, which we explain later.\nThe parameters hierarchy in Java looks as follows: \n\n public abstract class Parameters {\n public abstract boolean hasIdRequirement();\n }\n\n public abstract class AeadParameters extends Parameters {}\n\n public final class AesGcmParameters extends AeadParameters {\n /**\n * The Variant specified how ciphertexts are [tagged](/tink/design/keysets#tagging_ciphertexts).\n */\n public static final class Variant {...}\n /** A helper object to create new AesGcmParameters. */\n public static final class Builder {...}\n\n public int getKeySizeBytes() {...}\n public int getIvSizeBytes() {...}\n public int getTagSizeBytes() {...}\n\n public Variant getVariant() {...}\n\n public OutputPrefixType getOutputPrefixType() {...}\n public boolean equals(Object object) {...}\n public int hashCode() {...}\n }\n\nAs explained in the section\n[Keysets, Tagging Ciphertexts](/tink/design/keysets#tagging_ciphertexts),\nsome keys have a requirement on their id, when they are in a keyset. Every\n`Parameters` object has a method `hasIdRequirement` which specifies whether the\nkey created by this `Parameters` object will have such a required id, or not.\n\nThe `AesGcmParameters` object next provides methods `getKeySizeBytes()`,\n`getIvSizeBytes()`, and `getTagSizeBytes()`. These return the lengths of\nthe key used, the length of the IV used, and the length of the produced tag,\nin bytes. While Tink provides some of these functions for completeness, it\ndoes not always allow creating `Aead`s for every choice. For example, currently\nonly 12 byte IVs are supported for AES GCM.\n\nThe `AesGcmParameters` object also provides overrides for the previously\ndefined methods (and the Java standard methods `equals` and `hashCode`\nwhich is considered good practice).\n\nFinally, it provides static methods to create new `AeadParameters` objects.\nThese validate the inputs, i.e., they check that the size is one of 16, 24,\nor 32.\n\nKey objects\n-----------\n\nTink also has a key hierarchy. Remaining with our example of AES GCM, it looks\nlike this: \n\n public abstract class Key {\n public abstract Parameters getParameters();\n public abstract @Nullable Integer getIdRequirementOrNull();\n public abstract boolean equalsKey(Key other);\n }\n\n public abstract class AeadKey extends Key {\n public abstract AeadParameters getParameters();\n public abstract Bytes getOutputPrefix();\n }\n\n public final class AesGcmKey implements AeadKey {\n public SecretBytes getKeyBytes();\n public abstract Bytes getOutputPrefix();\n public AesGcmParameters getParameters();\n public @Nullable Integer getIdRequirementOrNull();\n public boolean equalsKey(Key object);\n }\n\nThe method `getIdRequirementOrNull` returns the id which this key needs to have,\nor `null` if there is no requirement.\n(Such a requirement on the key comes from the fact that Tink in some cases\nprefixes ciphertexts or signatures with the string `0x01\u003cid\u003e`, see the section\non [ciphertext tagging](/tink/design/keysets#tagging_ciphertexts)).\n\nThis will always be consistent with the result of\n`getParameters().hasIdRequirement()` and implementers of new\nkey classes need to ensure this.\n\nImplementations of `Key` also need to provide a method `equalsKey` to\ncompare different keys. Such\na method is often useful: for example when testing key derivation, one is\ninterested in ensuring that repeated application of the derivation yields\nthe same key object. Also, a KMS might want to check if any of the keys it\nprovides to different users are equal (which happens sometimes if users share\nkeys and upload them to the same KMS multiple times). It is notable that we\ndo not override the Java method `equals`, because this would require us to\noverride `hashCode`, and there is no way to implement `hashCode` in a safe\nway compatible with `equals` without making unproven assumptions.\n\nNext, we require a method `getParameters()`. This allows users to get the\noriginal information about the Parameters used to create the key.\n\nFinally, `AesGcmKey` has a method `getKeyBytes` which returns the raw key material.\nSuch methods are very typical for key classes: they are specific to the type,\nand provide access to the underlying key material. Using those, users\ncan in principle e.g. implement the primitive represented by the key,\nor serialize the key in order to store it on disk or send it over the\nnetwork. The key itself is responsible for protecting the key material against\nunauthorized access. For example, `SecretBytes` requires an access token to\nactually provide the material\n(see [Access Control](/tink/design/access_control)).\n\nAsymmetric Keys\n---------------\n\nFor asymmetric primitives, Tink uses two Key classes, one for private and one\nfor public keys. For the Parameters, it is more convenient to use the same\nclass (as there is only one class which can be used to generate the keys).\n\nTink also has an interface `PrivateKey` with the additional\nfunction `getPublicKey()`."]]
