কীমাস্টার ফাংশন

এই পৃষ্ঠাটি কীমাস্টার হার্ডওয়্যার অ্যাবস্ট্রাকশন লেয়ার (HALs) বাস্তবায়নকারীদের সহায়তা করার জন্য বিশদ প্রদান করে। এটি API-এর প্রতিটি ফাংশন কভার করে এবং কোন কীমাস্টার সংস্করণে সেই ফাংশনটি উপলব্ধ এবং ডিফল্ট বাস্তবায়ন বর্ণনা করে। ট্যাগগুলির জন্য, কীমাস্টার ট্যাগ পৃষ্ঠাটি দেখুন।

সাধারণ বাস্তবায়ন নির্দেশিকা

নিম্নলিখিত নির্দেশিকাগুলি API-এর সমস্ত ফাংশনে প্রযোজ্য৷

ইনপুট পয়েন্টার পরামিতি

সংস্করণ : 1, 2

ইনপুট পয়েন্টার পরামিতি যা প্রদত্ত কলের জন্য ব্যবহৃত হয় না তা NULL হতে পারে। কলারকে স্থানধারক প্রদান করার প্রয়োজন নেই। উদাহরণস্বরূপ, কিছু কী প্রকার এবং মোড inParams আর্গুমেন্ট থেকে শুরু করার জন্য কোনো মান ব্যবহার নাও করতে পারে, তাই কলার inParams NULL এ সেট করতে পারে বা একটি খালি প্যারামিটার সেট প্রদান করতে পারে। কলাররা অব্যবহৃত পরামিতিও প্রদান করতে পারে এবং কীমাস্টার পদ্ধতিতে ত্রুটি প্রকাশ করা উচিত নয়।

যদি একটি প্রয়োজনীয় ইনপুট পরামিতি NULL হয়, তাহলে কীমাস্টার পদ্ধতিগুলি ErrorCode::UNEXPECTED_NULL_POINTER ফেরত দেবে।

Keymaster 3 থেকে শুরু করে, কোন পয়েন্টার প্যারামিটার নেই। সমস্ত পরামিতি মান বা const রেফারেন্স দ্বারা পাস করা হয়.

আউটপুট পয়েন্টার পরামিতি

সংস্করণ : 1, 2

ইনপুট পয়েন্টার প্যারামিটারের মতো, অব্যবহৃত আউটপুট পয়েন্টার প্যারামিটার NULL হতে পারে। যদি একটি পদ্ধতির একটি আউটপুট প্যারামিটারে ডেটা ফেরত দিতে হয় যা NULL বলে পাওয়া যায়, তাহলে এটি ErrorCode::OUTPUT_PARAMETER_NULL ।

Keymaster 3 থেকে শুরু করে, কোন পয়েন্টার প্যারামিটার নেই। সমস্ত পরামিতি মান বা const রেফারেন্স দ্বারা পাস করা হয়.

API অপব্যবহার

সংস্করণ : 1, 2, 3

কলকারীরা এমন অনেক উপায়ে অনুরোধ করতে পারে যা অর্থহীন বা বোকা কিন্তু প্রযুক্তিগতভাবে ভুল নয়। এই ধরনের ক্ষেত্রে ব্যর্থ হওয়ার জন্য বা ডায়াগনস্টিক ইস্যু করার জন্য কীমাস্টার বাস্তবায়নের প্রয়োজন নেই। খুব ছোট কীগুলির ব্যবহার, অপ্রাসঙ্গিক ইনপুট প্যারামিটারের স্পেসিফিকেশন, IV বা ননসেসের পুনঃব্যবহার, কোন উদ্দেশ্য ছাড়াই কী তৈরি করা (অতএব অকেজো) এবং এই জাতীয়গুলি বাস্তবায়ন দ্বারা নির্ণয় করা উচিত নয়। প্রয়োজনীয় পরামিতি বাদ দেওয়া, অবৈধ প্রয়োজনীয় পরামিতিগুলির স্পেসিফিকেশন এবং অনুরূপ ত্রুটিগুলি নির্ণয় করা আবশ্যক।

কীমাস্টার মডিউলগুলিতে কলগুলি বুদ্ধিমান এবং দরকারী তা নিশ্চিত করা অ্যাপস, ফ্রেমওয়ার্ক এবং অ্যান্ড্রয়েড কীস্টোরের দায়িত্ব৷

ফাংশন

হার্ডওয়্যার বৈশিষ্ট্যগুলি পান

সংস্করণ : 3

নতুন getHardwareFeatures পদ্ধতি ক্লায়েন্টদের কাছে অন্তর্নিহিত সুরক্ষিত হার্ডওয়্যারের কিছু গুরুত্বপূর্ণ বৈশিষ্ট্য প্রকাশ করে। পদ্ধতিটি কোন আর্গুমেন্ট নেয় না এবং চারটি মান প্রদান করে, সমস্ত বুলিয়ান:

  • isSecure true যদি কীগুলি সুরক্ষিত হার্ডওয়্যারে (TEE, ইত্যাদি) সংরক্ষণ করা হয় এবং কখনই এটি ছেড়ে না যায়।
  • supportsEllipticCurve true যদি হার্ডওয়্যার NIST বক্ররেখা (P-224, P-256, P-384, এবং P-521) সহ উপবৃত্তাকার কার্ভ ক্রিপ্টোগ্রাফি সমর্থন করে।
  • Symmetric Cryptography supportsSymmetricCryptography true যদি হার্ডওয়্যার AES এবং HMAC সহ সিমেট্রিক ক্রিপ্টোগ্রাফি সমর্থন করে।
  • supportsAttestation true যদি হার্ডওয়্যার কিমাস্টার পাবলিক কী প্রত্যয়ন শংসাপত্র তৈরি করে, একটি সুরক্ষিত পরিবেশে ইনজেকশন করা কী দিয়ে স্বাক্ষরিত।

এই পদ্ধতিটি যে ত্রুটির কোডগুলি ফেরত দিতে পারে তা হল ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED বা একটি ত্রুটি কোড যা সুরক্ষিত হার্ডওয়্যারের সাথে যোগাযোগ করতে ব্যর্থতার ইঙ্গিত দেয়।

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

সজ্জিত করা

সংস্করণ : 2

এই ফাংশনটি Keymaster 2-এ চালু করা হয়েছিল এবং Keymaster 3-এ অবমুক্ত করা হয়েছিল, কারণ এই তথ্য সিস্টেমের বৈশিষ্ট্য ফাইলগুলিতে পাওয়া যায়, এবং প্রস্তুতকারক বাস্তবায়ন স্টার্টআপের সময় সেই ফাইলগুলি পড়ে।

কীমাস্টার কনফিগার করে। এই পদ্ধতিটি ডিভাইসটি খোলার পরে এবং এটি ব্যবহার করার আগে একবার বলা হয়। এটি কীমাস্টারকে KM_TAG_OS_VERSION এবং KM_TAG_OS_PATCHLEVEL প্রদান করতে ব্যবহৃত হয়। এই পদ্ধতিটি বলা না হওয়া পর্যন্ত, অন্যান্য সমস্ত পদ্ধতি KM_ERROR_KEYMASTER_NOT_CONFIGURED করে। এই পদ্ধতি দ্বারা প্রদত্ত মানগুলি শুধুমাত্র প্রতি বুটে একবার কীমাস্টার দ্বারা গৃহীত হয়। পরবর্তী কলগুলি ফিরে KM_ERROR_OK , কিন্তু কিছুই করে না৷

যদি কীমাস্টার বাস্তবায়ন সুরক্ষিত হার্ডওয়্যারে হয় এবং প্রদত্ত OS সংস্করণ এবং প্যাচ স্তরের মানগুলি বুটলোডার দ্বারা সুরক্ষিত হার্ডওয়্যারের সাথে প্রদত্ত মানগুলির সাথে মেলে না (অথবা যদি বুটলোডার মান প্রদান না করে), তবে এই পদ্ধতিটি KM_ERROR_INVALID_ARGUMENT , এবং অন্য সবগুলি প্রদান করে পদ্ধতিগুলি KM_ERROR_KEYMASTER_NOT_CONFIGURED ফেরত দেওয়া অব্যাহত রাখে।

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

addRngEntropy

সংস্করণ : 1, 2, 3

এই ফাংশনটি Keymaster 1-এ add_rng_entropy হিসাবে চালু করা হয়েছিল এবং Keymaster 3 তে নামকরণ করা হয়েছিল।

কী, IV, ইত্যাদির জন্য এলোমেলো সংখ্যা তৈরি করার জন্য Keymaster 1 বাস্তবায়ন দ্বারা ব্যবহৃত পুলে কলার-প্রদত্ত এনট্রপি যোগ করে।

কীমাস্টার বাস্তবায়নের জন্য তাদের পুলে প্রদত্ত এনট্রপি সুরক্ষিতভাবে মিশ্রিত করতে হবে, এতে অবশ্যই একটি হার্ডওয়্যার র্যান্ডম নম্বর জেনারেটর থেকে অভ্যন্তরীণভাবে জেনারেট করা এনট্রপি থাকতে হবে। মিক্সিং পরিচালনা করা উচিত যাতে একজন আক্রমণকারী যার হয় addRngEntropy বিট বা হার্ডওয়্যার-উত্পাদিত বিটগুলির সম্পূর্ণ নিয়ন্ত্রণ রয়েছে, তবে উভয়ই নয়, এনট্রপি পুল থেকে উৎপন্ন বিটগুলির পূর্বাভাস দেওয়ার ক্ষেত্রে কোনও অ-নগণ্য সুবিধা নেই৷

কীমাস্টার বাস্তবায়ন যেগুলি তাদের অভ্যন্তরীণ পুলে এনট্রপি অনুমান করার চেষ্টা করে অনুমান করে যে addRngEntropy দ্বারা প্রদত্ত ডেটাতে কোনও এনট্রপি নেই। কীমাস্টার বাস্তবায়ন ErrorCode::INVALID_INPUT_LENGTH ফেরত দিতে পারে যদি তাদের একটি কলে 2 KiB-এর বেশি ডেটা দেওয়া হয়।

কী তৈরি করুন

সংস্করণ : 1, 2, 3

এই ফাংশনটি Keymaster 1-এ generate_key হিসাবে চালু করা হয়েছিল এবং Keymaster 3-এ নামকরণ করা হয়েছিল।

একটি নতুন ক্রিপ্টোগ্রাফিক কী তৈরি করে, যুক্ত অনুমোদনগুলি নির্দিষ্ট করে, যা স্থায়ীভাবে কীটির সাথে আবদ্ধ। কীমাস্টার বাস্তবায়নের ফলে প্রজন্মের সময়ে নির্দিষ্ট করা অনুমোদনের সাথে অসামঞ্জস্যপূর্ণ কোনো কী ব্যবহার করা অসম্ভব হয়ে পড়ে। অনুমোদনের ক্ষেত্রে যেগুলি সুরক্ষিত হার্ডওয়্যার প্রয়োগ করতে পারে না, সুরক্ষিত হার্ডওয়্যারের বাধ্যবাধকতা নিশ্চিত করার জন্য সীমাবদ্ধ যে কী এর সাথে যুক্ত অপ্রয়োগযোগ্য অনুমোদনগুলি সংশোধন করা যাবে না, যাতে getKeyCharacteristics- এর প্রতিটি কল আসল মান ফিরিয়ে দেয়। উপরন্তু, generateKey দ্বারা প্রত্যাবর্তিত বৈশিষ্ট্যগুলি হার্ডওয়্যার-প্রবর্তিত এবং সফ্টওয়্যার-প্রবর্তিত তালিকার মধ্যে সঠিকভাবে অনুমোদন বরাদ্দ করে। আরও বিস্তারিত জানার জন্য getKey বৈশিষ্ট্য দেখুন।

generateKey এর জন্য প্রদত্ত পরামিতিগুলি কী ধরনের তৈরি করা হচ্ছে তার উপর নির্ভর করে। এই বিভাগে প্রতিটি ধরনের কী-এর জন্য প্রয়োজনীয় এবং ঐচ্ছিক ট্যাগগুলির সংক্ষিপ্ত বিবরণ দেওয়া হয়েছে। ট্যাগ::টাইপ নির্দিষ্ট করার জন্য অ্যালগোরিদম সর্বদা প্রয়োজনীয়।

RSA কী

নিম্নলিখিত পরামিতিগুলি একটি RSA কী তৈরি করতে প্রয়োজনীয়৷

  • ট্যাগ::KEY_SIZE বিটগুলিতে , পাবলিক মডুলাসের আকার নির্দিষ্ট করে। যদি বাদ দেওয়া হয়, পদ্ধতিটি ErrorCode::UNSUPPORTED_KEY_SIZE । সমর্থিত মানগুলি হল 1024, 2048, 3072 এবং 4096৷ প্রস্তাবিত মানগুলি হল সমস্ত কী মাপ যা 8 এর গুণিতক৷
  • ট্যাগ::RSA_PUBLIC_EXPONENT RSA পাবলিক এক্সপোনেন্ট মান নির্দিষ্ট করে। যদি বাদ দেওয়া হয়, পদ্ধতিটি ErrorCode::INVALID_ARGUMENT করে। সমর্থিত মানগুলি হল 3 এবং 65537৷ প্রস্তাবিত মানগুলি হল 2^64 পর্যন্ত সমস্ত প্রধান মান৷

নিম্নলিখিত পরামিতিগুলি একটি RSA কী তৈরি করার জন্য প্রয়োজনীয় নয়, তবে সেগুলি ছাড়া একটি RSA কী তৈরি করা একটি কী তৈরি করে যা ব্যবহারযোগ্য নয়৷ যাইহোক, generateKey ফাংশন কোনো ত্রুটি ফেরত দেয় না যদি এই প্যারামিটারগুলি বাদ দেওয়া হয়।

  • ট্যাগ::উদ্দেশ্য অনুমোদিত উদ্দেশ্য নির্দিষ্ট করে। সমস্ত উদ্দেশ্য RSA কীগুলির জন্য সমর্থিত হতে হবে, যেকোনো সংমিশ্রণে।
  • ট্যাগ:: ডাইজেস্ট ডাইজেস্ট অ্যালগরিদম নির্দিষ্ট করে যা নতুন কী দিয়ে ব্যবহার করা যেতে পারে। সমস্ত ডাইজেস্ট অ্যালগরিদমকে সমর্থন করে না এমন ইমপ্লিমেন্টগুলিকে কী জেনারেশনের অনুরোধগুলিকে গ্রহণ করতে হবে যাতে অসমর্থিত ডাইজেস্ট অন্তর্ভুক্ত থাকে। অসমর্থিত ডাইজেস্টগুলি ফিরিয়ে দেওয়া মূল বৈশিষ্ট্যগুলির মধ্যে "সফ্টওয়্যার-প্রবর্তিত" তালিকায় স্থাপন করা উচিত। এর কারণ হল কী সেই অন্যান্য ডাইজেস্টের সাথে ব্যবহারযোগ্য, কিন্তু হজম করা সফ্টওয়্যারে সঞ্চালিত হয়। তারপর হার্ডওয়্যারকে Digest::NONE দিয়ে অপারেশন করতে বলা হয়।
  • ট্যাগ:: প্যাডিং প্যাডিং মোডগুলি নির্দিষ্ট করে যা নতুন কী দিয়ে ব্যবহার করা যেতে পারে। সমস্ত ডাইজেস্ট অ্যালগরিদমকে সমর্থন করে না এমন ইমপ্লিমেন্টেশনগুলিকে PaddingMode::RSA_PSS এবং PaddingMode::RSA_OAEP মূল বৈশিষ্ট্যগুলির সফ্টওয়্যার-প্রবর্তিত তালিকায় রাখতে হবে যদি কোনও অসমর্থিত ডাইজেস্ট অ্যালগরিদম নির্দিষ্ট করা থাকে।

ECDSA কী

শুধুমাত্র ট্যাগ::KEY_SIZE একটি ECDSA কী তৈরি করতে প্রয়োজনীয়৷ এটি ইসি গ্রুপ নির্বাচন করতে ব্যবহৃত হয়। সমর্থিত মানগুলি হল 224, 256, 384 এবং 521, যা যথাক্রমে NIST p-224, p-256, p-384 এবং p521 বক্ররেখা নির্দেশ করে৷

ট্যাগ::ডাইজেস্ট একটি দরকারী ECDSA কী-এর জন্যও প্রয়োজনীয়, কিন্তু প্রজন্মের জন্য প্রয়োজনীয় নয়।

AES কী

একটি AES কী তৈরি করতে শুধুমাত্র Tag::KEY_SIZE প্রয়োজন। যদি বাদ দেওয়া হয়, পদ্ধতিটি ErrorCode::UNSUPPORTED_KEY_SIZE । সমর্থিত মান হল 128 এবং 256, 192-বিট AES কীগুলির জন্য ঐচ্ছিক সমর্থন সহ।

নিম্নলিখিত পরামিতিগুলি AES কীগুলির জন্য বিশেষভাবে প্রাসঙ্গিক, তবে একটি তৈরি করার জন্য প্রয়োজনীয় নয়:

  • Tag::BLOCK_MODE ব্লক মোডগুলি নির্দিষ্ট করে যার সাথে নতুন কী ব্যবহার করা যেতে পারে।
  • Tag::PADDING প্যাডিং ব্যবহার করা যেতে পারে এমন প্যাডিং মোডগুলি নির্দিষ্ট করে৷ এটি শুধুমাত্র ECB এবং CBC মোডের জন্য প্রাসঙ্গিক।

যদি GCM ব্লক মোড নির্দিষ্ট করা থাকে, তাহলে ট্যাগ প্রদান করুন::MIN_MAC_LENGTH । যদি বাদ দেওয়া হয়, পদ্ধতিটি ErrorCode::MISSING_MIN_MAC_LENGTH করে। ট্যাগের মান 8 এর গুণিতক এবং 96 এবং 128 এর মধ্যে।

HMAC কী

HMAC কী জেনারেশনের জন্য নিম্নলিখিত প্যারামিটারগুলি প্রয়োজন:

  • ট্যাগ::KEY_SIZE বিটগুলিতে কী আকার নির্দিষ্ট করে। 64-এর থেকে ছোট মান এবং 8-এর গুণিতক নয় এমন মানগুলি সমর্থিত নয়৷ 64 থেকে 512 পর্যন্ত 8 এর সমস্ত গুণিতক সমর্থিত। বড় মান সমর্থিত হতে পারে.
  • ট্যাগ::MIN_MAC_LENGTH MAC- এর ন্যূনতম দৈর্ঘ্য নির্দিষ্ট করে যা এই কী দিয়ে তৈরি বা যাচাই করা যেতে পারে। মানটি 8 এর গুণিতক এবং কমপক্ষে 64।
  • ট্যাগ:: ডাইজেস্ট কীটির জন্য ডাইজেস্ট অ্যালগরিদম নির্দিষ্ট করে। ঠিক একটি ডাইজেস্ট নির্দিষ্ট করা হয়েছে, অন্যথায় ErrorCode::UNSUPPORTED_DIGEST । যদি ডাইজেস্ট ট্রাস্টলেট দ্বারা সমর্থিত না হয়, তাহলে ErrorCode::UNSUPPORTED_DIGEST ।

মূল বৈশিষ্ট্য

যদি বৈশিষ্ট্যের আর্গুমেন্ট অ-NULL হয়, তাহলে generateKey নতুন জেনারেট হওয়া কী-এর বৈশিষ্ট্যগুলিকে সঠিকভাবে হার্ডওয়্যার-প্রবর্তিত এবং সফ্টওয়্যার-প্রবর্তিত তালিকায় বিভক্ত করে। কোন বৈশিষ্ট্য কোন তালিকায় যায় তার বর্ণনার জন্য getKeyCharacteristics দেখুন। ট্যাগ::APPLICATION_ID এবং Tag:: APPLICATION_DATA ব্যতীত, কী জেনারেশনের জন্য নির্দিষ্ট করা সমস্ত প্যারামিটারগুলি ফেরত দেওয়া বৈশিষ্ট্যগুলি অন্তর্ভুক্ত করে। যদি এই ট্যাগগুলি কী প্যারামিটারের মধ্যে অন্তর্ভুক্ত করা হয়, তবে সেগুলি প্রত্যাবর্তিত বৈশিষ্ট্যগুলি থেকে সরানো হয় যাতে ফিরে আসা কী ব্লব পরীক্ষা করে তাদের মানগুলি খুঁজে পাওয়া সম্ভব না হয়। যাইহোক, এগুলি ক্রিপ্টোগ্রাফিকভাবে কী ব্লবের সাথে আবদ্ধ থাকে, যাতে কী ব্যবহার করার সময় সঠিক মান প্রদান করা না হলে, ব্যবহার ব্যর্থ হয়। একইভাবে, Tag::ROOT_OF_TRUST কী ক্রিপ্টোগ্রাফিকভাবে আবদ্ধ, কিন্তু এটি কী তৈরি বা আমদানির সময় নির্দিষ্ট নাও হতে পারে এবং ফেরত দেওয়া হয় না।

প্রদত্ত ট্যাগগুলি ছাড়াও, ট্রাস্টলেট Tag::ORIGIN , KeyOrigin::GENERATED মান সহ যোগ করে এবং যদি কী রোলব্যাক প্রতিরোধী হয়,

ট্যাগ::ROLLBACK_RESISTANT ।

রোলব্যাক প্রতিরোধ

রোলব্যাক রেজিস্ট্যান্স মানে হল একবার ডিলিটকি বা ডিলিট অ্যালকি দিয়ে একটি কী মুছে ফেলা হলে, এটি সুরক্ষিত হার্ডওয়্যার দ্বারা নিশ্চিত করা হয় যে এটি আর কখনও ব্যবহারযোগ্য হবে না। রোলব্যাক রেজিস্ট্যান্স ব্যতীত ইমপ্লিমেন্টেশনগুলি সাধারণত একটি কী ব্লব, একটি এনক্রিপ্ট করা এবং প্রমাণীকৃত ফর্ম হিসাবে কলারের কাছে জেনারেট করা বা আমদানি করা কী উপাদান ফেরত দেয়। যখন কীস্টোর কী ব্লবটি মুছে দেয়, তখন কীটি চলে যায়, কিন্তু একজন আক্রমণকারী যিনি পূর্বে মূল উপাদানটি পুনরুদ্ধার করতে পেরেছিলেন তিনি সম্ভাব্যভাবে এটিকে ডিভাইসে পুনরুদ্ধার করতে পারেন।

একটি কী রোলব্যাক প্রতিরোধী হয় যদি সুরক্ষিত হার্ডওয়্যার গ্যারান্টি দেয় যে মুছে ফেলা কীগুলি পরে পুনরুদ্ধার করা যাবে না। এটি সাধারণত একটি বিশ্বস্ত অবস্থানে অতিরিক্ত কী মেটাডেটা সংরক্ষণ করে করা হয় যা আক্রমণকারী দ্বারা ম্যানিপুলেট করা যায় না। মোবাইল ডিভাইসে, এর জন্য ব্যবহৃত প্রক্রিয়াটি সাধারণত রিপ্লে প্রোটেক্টেড মেমরি ব্লক (RPMB)। কারণ তৈরি করা কীগুলির সংখ্যা মূলত সীমাহীন এবং রোলব্যাক প্রতিরোধের জন্য ব্যবহৃত বিশ্বস্ত স্টোরেজটি আকারে সীমিত হতে পারে, এই পদ্ধতিটি সফল হওয়া দরকার এমনকি যদি নতুন কীটির জন্য রোলব্যাক প্রতিরোধ না দেওয়া যায়। সেক্ষেত্রে, Tag::ROLLBACK_RESISTANT মূল বৈশিষ্ট্যের সাথে যোগ করা উচিত নয়।

GetKey বৈশিষ্ট্য

সংস্করণ : 1, 2, 3

এই ফাংশনটি কীমাস্টার 1-এ get_key_characteristics হিসাবে চালু করা হয়েছিল এবং কীমাস্টার 3-এ পুনঃনামকরণ করা হয়েছিল।

প্রদত্ত কী-এর সাথে সম্পর্কিত পরামিতি এবং অনুমোদন ফেরত দেয়, দুটি সেটে বিভক্ত: হার্ডওয়্যার-প্রবর্তিত এবং সফ্টওয়্যার-প্রবর্তিত। এখানে বর্ণনাটি generateKey এবং importKey দ্বারা প্রত্যাবর্তিত মূল বৈশিষ্ট্যের তালিকায় সমানভাবে প্রযোজ্য।

যদি Tag::APPLICATION_ID কী তৈরি বা আমদানির সময় প্রদান করা হয়, তাহলে clientId আর্গুমেন্টে এই পদ্ধতিতে একই মান প্রদান করা হয়। অন্যথায়, পদ্ধতিটি ErrorCode::INVALID_KEY_BLOB করে। একইভাবে, যদি Tag::APPLICATION_DATA জেনারেশন বা আমদানির সময় প্রদান করা হয়, তাহলে appData আর্গুমেন্টে এই পদ্ধতিতে একই মান প্রদান করা হয়।

এই পদ্ধতি দ্বারা প্রত্যাবর্তিত বৈশিষ্ট্যগুলি নির্দিষ্ট কীটির ধরন এবং ব্যবহার সম্পূর্ণরূপে বর্ণনা করে।

একটি প্রদত্ত ট্যাগ হার্ডওয়্যার-প্রবর্তিত বা সফ্টওয়্যার-প্রবর্তিত তালিকার অন্তর্গত কিনা তা নির্ধারণের সাধারণ নিয়ম হল যে ট্যাগের অর্থ যদি সুরক্ষিত হার্ডওয়্যার দ্বারা সম্পূর্ণরূপে নিশ্চিত করা হয় তবে এটি হার্ডওয়্যার প্রয়োগ করা হয়। অন্যথায়, এটি সফ্টওয়্যার প্রয়োগ করা হয়েছে। নীচে নির্দিষ্ট ট্যাগের একটি তালিকা রয়েছে যার সঠিক বরাদ্দ অস্পষ্ট হতে পারে:

  • Tag::ALGORITHM , Tag::KEY_SIZE , এবং Tag::RSA_PUBLIC_EXPONENT হল কীটির অন্তর্নিহিত বৈশিষ্ট্য। হার্ডওয়্যার দ্বারা সুরক্ষিত যে কোনও কীর জন্য, এই ট্যাগগুলি হার্ডওয়্যার-প্রবর্তিত তালিকায় থাকবে।
  • ট্যাগ::ডাইজেস্ট মানগুলি যা সুরক্ষিত হার্ডওয়্যার দ্বারা সমর্থিত হয় হার্ডওয়্যার-সমর্থিত তালিকায় রাখা হয়। অসমর্থিত ডাইজেস্টগুলি সফ্টওয়্যার-সমর্থিত তালিকায় যায়৷
  • ট্যাগ::প্যাডিং মানগুলি সাধারণত হার্ডওয়্যার-সমর্থিত তালিকায় যায়, যদি না এমন একটি সম্ভাবনা থাকে যে একটি নির্দিষ্ট প্যাডিং মোড সফ্টওয়্যার দ্বারা সঞ্চালিত হতে পারে৷ সেই ক্ষেত্রে, তারা সফ্টওয়্যার-প্রবর্তিত তালিকায় যায়। এই ধরনের একটি সম্ভাবনা RSA কীগুলির জন্য উদ্ভূত হয় যা নিরাপদ হার্ডওয়্যার দ্বারা সমর্থিত নয় এমন ডাইজেস্ট অ্যালগরিদমগুলির সাথে PSS বা OAEP প্যাডিংকে অনুমতি দেয়৷
  • ট্যাগ::USER_SECURE_ID এবং Tag::USER_AUTH_TYPE শুধুমাত্র হার্ডওয়্যার-প্রবর্তিত হয় যদি ব্যবহারকারীর প্রমাণীকরণ হার্ডওয়্যার প্রয়োগ করা হয়। এটি সম্পন্ন করার জন্য, কীমাস্টার ট্রাস্টলেট এবং প্রাসঙ্গিক প্রমাণীকরণ ট্রাস্টলেট উভয়কেই সুরক্ষিত থাকতে হবে এবং প্রমাণীকরণ টোকেনগুলি স্বাক্ষর ও যাচাই করতে ব্যবহৃত একটি গোপন HMAC কী শেয়ার করতে হবে। বিস্তারিত জানার জন্য প্রমাণীকরণ পৃষ্ঠা দেখুন।
  • Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME , এবং Tag::USAGE_EXPIRE_DATETIME ট্যাগগুলির জন্য একটি যাচাইযোগ্যভাবে সঠিক প্রাচীর ঘড়িতে অ্যাক্সেস প্রয়োজন৷ সর্বাধিক সুরক্ষিত হার্ডওয়্যারের শুধুমাত্র অ-সুরক্ষিত OS দ্বারা প্রদত্ত সময়ের তথ্যে অ্যাক্সেস থাকে, যার অর্থ ট্যাগগুলি সফ্টওয়্যার প্রয়োগ করা হয়৷
  • Tag::ORIGIN সবসময় হার্ডওয়্যার-বাউন্ড কীগুলির জন্য হার্ডওয়্যার তালিকায় থাকে। সেই তালিকায় এর উপস্থিতি হল যেভাবে উচ্চ স্তরগুলি নির্ধারণ করে যে একটি কী হার্ডওয়্যার-সমর্থিত।

importKey

সংস্করণ : 1, 2, 3

এই ফাংশনটি কীমাস্টার 1-এ import_key হিসাবে চালু করা হয়েছিল এবং কীমাস্টার 3-এ নামকরণ করা হয়েছিল।

Keymaster হার্ডওয়্যারে মূল উপাদান আমদানি করে। কী সংজ্ঞা পরামিতি এবং আউটপুট বৈশিষ্ট্যগুলি নিম্নলিখিত ব্যতিক্রমগুলি সহ generateKey এর মতোই পরিচালনা করা হয়:

  • ট্যাগ::KEY_SIZE এবং ট্যাগ::RSA_PUBLIC_EXPONENT (শুধুমাত্র RSA কীগুলির জন্য) ইনপুট পরামিতিগুলিতে প্রয়োজনীয় নয়৷ যদি প্রদান না করা হয়, ট্রাস্টলেট প্রদত্ত মূল উপাদান থেকে মান নির্ণয় করে এবং মূল বৈশিষ্ট্যগুলিতে উপযুক্ত ট্যাগ এবং মান যোগ করে। যদি পরামিতি প্রদান করা হয়, তাহলে ট্রাস্টলেট মূল উপাদানের বিরুদ্ধে তাদের যাচাই করে। অমিলের ক্ষেত্রে, পদ্ধতিটি ErrorCode::IMPORT_PARAMETER_MISMATCH ।
  • ফেরত দেওয়া Tag::ORIGIN- এর KeyOrigin::IMPORTED এর মতই মান রয়েছে।

রপ্তানি কী

সংস্করণ : 1, 2, 3

এই ফাংশনটি কীমাস্টার 1-এ এক্সপোর্ট_কি হিসাবে চালু করা হয়েছিল এবং export_key 3-এ নাম পরিবর্তন করা হয়েছিল।

একটি কীমাস্টার RSA বা EC কী জোড়া থেকে একটি সর্বজনীন কী রপ্তানি করে।

যদি Tag::APPLICATION_ID কী তৈরি বা আমদানির সময় প্রদান করা হয়, তাহলে clientId আর্গুমেন্টে এই পদ্ধতিতে একই মান প্রদান করা হয়। অন্যথায়, পদ্ধতিটি ErrorCode::INVALID_KEY_BLOB করে। একইভাবে, যদি Tag::APPLICATION_DATA জেনারেশন বা আমদানির সময় প্রদান করা হয়, তাহলে appData আর্গুমেন্টে এই পদ্ধতিতে একই মান প্রদান করা হয়।

ডিলিট কী

সংস্করণ : 1, 2, 3

এই ফাংশনটি Keymaster 1-এ delete_key হিসাবে চালু করা হয়েছিল এবং Keymaster 3-এ নামকরণ করা হয়েছিল।

প্রদত্ত কী মুছে দেয়। এই পদ্ধতিটি ঐচ্ছিক, এবং এটি শুধুমাত্র কীমাস্টার মডিউল দ্বারা প্রয়োগ করা হয় যা রোলব্যাক প্রতিরোধ প্রদান করে।

ডিলিট সব কী

সংস্করণ : 1, 2, 3

এই ফাংশনটি Keymaster 1-এ delete_all_keys হিসাবে চালু করা হয়েছিল এবং Keymaster 3-এ পুনঃনামকরণ করা হয়েছিল।

সব কী মুছে দেয়। এই পদ্ধতিটি ঐচ্ছিক, এবং এটি শুধুমাত্র কীমাস্টার মডিউল দ্বারা প্রয়োগ করা হয় যা রোলব্যাক প্রতিরোধ প্রদান করে।

প্রমাণীকরণ আইডি ধ্বংস করুন

সংস্করণ : 3

destroyAttestationIds() পদ্ধতিটি স্থায়ীভাবে নতুন (ঐচ্ছিক, কিন্তু অত্যন্ত প্রস্তাবিত) আইডি প্রত্যয়ন বৈশিষ্ট্যটি নিষ্ক্রিয় করতে ব্যবহৃত হয়। এই পদ্ধতিটি কল করার পরে যদি TEE-এর কাছে নিশ্চিত করার কোন উপায় না থাকে যে আইডি প্রত্যয়ন স্থায়ীভাবে অক্ষম করা হয়েছে, তাহলে আইডি প্রত্যয়নটি মোটেই কার্যকর করা উচিত নয়, এই ক্ষেত্রে এই পদ্ধতিটি কিছুই করে না এবং ErrorCode::UNIMPLEMENTED করে। আইডি প্রত্যয়ন সমর্থিত হলে, এই পদ্ধতিটি প্রয়োগ করা প্রয়োজন এবং ভবিষ্যতের সমস্ত আইডি প্রত্যয়ন প্রচেষ্টা স্থায়ীভাবে অক্ষম করতে হবে। পদ্ধতিটি যে কোনো সংখ্যক বার বলা যেতে পারে। যদি আইডি প্রত্যয়ন ইতিমধ্যেই স্থায়ীভাবে অক্ষম করা থাকে, তবে পদ্ধতিটি কিছুই করে না এবং ErrorCode::OK করে।

এই পদ্ধতিটি যে ত্রুটির কোডগুলি ফেরত দিতে পারে তা হল ErrorCode::UNIMPLEMENTED (যদি আইডি প্রত্যয়ন সমর্থিত না হয়), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED বা নিরাপদ হার্ডওয়্যারের সাথে যোগাযোগ করতে ব্যর্থতার ইঙ্গিত করে ত্রুটি কোডগুলির একটি।

শুরু

সংস্করণ : 1, 2, 3

একটি ক্রিপ্টোগ্রাফিক অপারেশন শুরু করে, নির্দিষ্ট কী ব্যবহার করে, নির্দিষ্ট উদ্দেশ্যের জন্য, নির্দিষ্ট পরামিতিগুলির সাথে (যথাযথ হিসাবে), এবং একটি অপারেশন হ্যান্ডেল ফেরত দেয় যা অপারেশন সম্পূর্ণ করতে আপডেট এবং ফিনিস সহ ব্যবহৃত হয়। অপারেশন হ্যান্ডেলটি প্রমাণীকৃত ক্রিয়াকলাপে "চ্যালেঞ্জ" টোকেন হিসাবেও ব্যবহৃত হয় এবং এই জাতীয় ক্রিয়াকলাপগুলির জন্য প্রমাণীকরণ টোকেনের challenge ক্ষেত্রে অন্তর্ভুক্ত করা হয়।

একটি কীমাস্টার বাস্তবায়ন কমপক্ষে 16টি সমসাময়িক ক্রিয়াকলাপ সমর্থন করে। কীস্টোর 15 পর্যন্ত ব্যবহার করে, একটি পাসওয়ার্ড এনক্রিপশনের জন্য ব্যবহার করার জন্য ভল্ডের জন্য রেখে দেয়। যখন কীস্টোরে 15টি অপারেশন চলছে ( begin বলা হয়েছে, কিন্তু finish বা abort করা এখনও বলা হয়নি) এবং এটি একটি 16 তম শুরু করার জন্য একটি অনুরোধ পায়, এটি সক্রিয় ক্রিয়াকলাপগুলির সংখ্যা কমাতে সম্প্রতি ব্যবহৃত অপারেশনটিকে abort বলে। কল করার আগে 14 থেকে নতুন অনুরোধ করা অপারেশন begin করতে শুরু করুন।

যদি Tag::APPLICATION_ID বা Tag::APPLICATION_DATA কী তৈরি বা আমদানির সময় নির্দিষ্ট করা হয়, তাহলে এই পদ্ধতিতে inParams আর্গুমেন্টে মূলভাবে নির্দিষ্ট করা মান সহ সেই ট্যাগগুলিকে অন্তর্ভুক্ত করার জন্য কল begin করা হয়।

অনুমোদন প্রয়োগ

এই পদ্ধতির সময়, নিম্নলিখিত কী অনুমোদন ট্রাস্টলেট দ্বারা প্রয়োগ করা হয় যদি বাস্তবায়ন তাদের "হার্ডওয়্যার-প্রবর্তিত" বৈশিষ্ট্যগুলিতে রাখে এবং যদি অপারেশনটি একটি সর্বজনীন কী অপারেশন না হয়। পাবলিক কী অপারেশন, যার অর্থ মূল উদ্দেশ্য::এনক্রিপ্ট এবং মূল উদ্দেশ্য KeyPurpose::VERIFY KeyPurpose::ENCRYPT , RSA বা EC কী সহ, অনুমোদনের প্রয়োজনীয়তা পূরণ না হলেও সফল হতে দেওয়া হয়।

  • ট্যাগ::উদ্দেশ্য: বিগিন begin() কলে উল্লিখিত উদ্দেশ্যটিকে মূল অনুমোদনের উদ্দেশ্যগুলির একটির সাথে মিলতে হবে, যদি না অনুরোধকৃত অপারেশনটি একটি সর্বজনীন কী অপারেশন হয়। যদি নির্দিষ্ট উদ্দেশ্য মেলে না এবং অপারেশনটি একটি সর্বজনীন কী অপারেশন না হয়, তাহলে start ফেরত দেবে begin ErrorCode::UNSUPPORTED_PURPOSE । পাবলিক কী ক্রিয়াকলাপগুলি অসমমিত এনক্রিপশন বা যাচাইকরণ ক্রিয়াকলাপ।
  • ট্যাগ::ACTIVE_DATETIME শুধুমাত্র একটি বিশ্বস্ত UTC সময় উৎস উপলব্ধ হলেই প্রয়োগ করা যেতে পারে৷ যদি বর্তমান তারিখ এবং সময় ট্যাগ মানের আগে হয়, তাহলে পদ্ধতিটি ErrorCode::KEY_NOT_YET_VALID ।
  • ট্যাগ::ORIGINATION_EXPIRE_DATETIME শুধুমাত্র তখনই প্রয়োগ করা যেতে পারে যদি একটি বিশ্বস্ত UTC সময় উৎস উপলব্ধ থাকে৷ যদি বর্তমান তারিখ এবং সময় ট্যাগ মানের চেয়ে পরে হয় এবং উদ্দেশ্যটি হয় KeyPurpose::ENCRYPT বা KeyPurpose::SIGN , পদ্ধতিটি ErrorCode::KEY_EXPIRED ।
  • ট্যাগ::USAGE_EXPIRE_DATETIME শুধুমাত্র একটি বিশ্বস্ত UTC সময় উৎস উপলব্ধ হলেই প্রয়োগ করা যেতে পারে৷ যদি বর্তমান তারিখ এবং সময় ট্যাগ মানের চেয়ে পরে হয় এবং উদ্দেশ্যটি হয় KeyPurpose::DECRYPT বা KeyPurpose::VERIFY VERIFY, পদ্ধতিটি ErrorCode::KEY_EXPIRED ।
  • ট্যাগ::MIN_SECONDS_BETWEEN_OPS কে একটি বিশ্বস্ত আপেক্ষিক টাইমারের সাথে তুলনা করা হয় যা কীটির শেষ ব্যবহার নির্দেশ করে। যদি শেষ ব্যবহারের সময় এবং ট্যাগ মান বর্তমান সময়ের চেয়ে কম হয়, তবে পদ্ধতিটি ErrorCode::KEY_RATE_LIMIT_EXCEEDED । গুরুত্বপূর্ণ বাস্তবায়ন বিবরণের জন্য ট্যাগ বিবরণ দেখুন.
  • ট্যাগ::MAX_USES_PER_BOOT একটি সুরক্ষিত কাউন্টারের সাথে তুলনা করা হয় যা বুট সময় থেকে কীটির ব্যবহার ট্র্যাক করে। যদি পূর্ববর্তী ব্যবহারের গণনা ট্যাগ মান অতিক্রম করে, পদ্ধতিটি ErrorCode::KEY_MAX_OPS_EXCEEDED ।
  • ট্যাগ::USER_SECURE_ID এই পদ্ধতি দ্বারা প্রয়োগ করা হয় শুধুমাত্র যদি কীটিতে ট্যাগ::AUTH_TIMEOUT থাকে । যদি কীটিতে উভয়ই থাকে, তাহলে এই পদ্ধতিটি অবশ্যই একটি বৈধ Tag::AUTH_TOKEN inParams- inParams । প্রমাণীকরণ টোকেনটি বৈধ হওয়ার জন্য, নিম্নলিখিতগুলিকে সত্য হতে হবে:
    • HMAC ক্ষেত্র সঠিকভাবে যাচাই করে।
    • কী থেকে ট্যাগ::USER_SECURE_ID মানগুলির মধ্যে অন্তত একটি টোকেনের সুরক্ষিত ID মানগুলির মধ্যে অন্তত একটির সাথে মেলে৷
    • কীটিতে একটি Tag::USER_AUTH_TYPE আছে যা টোকেনের প্রমাণ প্রকারের সাথে মেলে।

    যদি এই শর্তগুলির মধ্যে কোনটি পূরণ না হয় তবে পদ্ধতিটি ErrorCode::KEY_USER_NOT_AUTHENTICATED ।

  • ট্যাগ::CALLER_NONCE কলকারীকে একটি ননস বা ইনিশিয়ালাইজেশন ভেক্টর (IV) নির্দিষ্ট করার অনুমতি দেয়। যদি কীটিতে এই ট্যাগ না থাকে, কিন্তু কলকারী এই পদ্ধতিতে ট্যাগ::NONCE প্রদান করে, ErrorCode::CALLER_NONCE_PROHIBITED ফেরত দেওয়া হয়।
  • ট্যাগ::BOOTLOADER_ONLY নির্দিষ্ট করে যে শুধুমাত্র বুটলোডার কী ব্যবহার করতে পারে। বুটলোডার চালানো শেষ হওয়ার পরে যদি এই পদ্ধতিটিকে একটি বুটলোডার-কেবল কী দিয়ে ডাকা হয়, তাহলে এটি ErrorCode::INVALID_KEY_BLOB করে।

RSA কী

সমস্ত RSA কী ক্রিয়াকলাপগুলি inParams এ ঠিক একটি প্যাডিং মোড নির্দিষ্ট করে৷ অনির্দিষ্ট বা একাধিকবার নির্দিষ্ট করা হলে, পদ্ধতিটি ErrorCode::UNSUPPORTED_PADDING_MODE ।

RSA সাইনিং এবং ভেরিফিকেশন অপারেশনের জন্য একটি ডাইজেস্ট প্রয়োজন, যেমনটি OAEP প্যাডিং মোডের সাথে RSA এনক্রিপশন এবং ডিক্রিপশন অপারেশন করে। এই ক্ষেত্রে, কলার inParams এ ঠিক একটি ডাইজেস্ট নির্দিষ্ট করে। অনির্দিষ্ট বা একাধিকবার নির্দিষ্ট করা হলে, পদ্ধতিটি ErrorCode::UNSUPPORTED_DIGEST ।

ব্যক্তিগত কী ক্রিয়াকলাপ (কী KeyPurpose::DECYPT এবং KeyPurpose::SIGN ) এর জন্য ডাইজেস্ট এবং প্যাডিংয়ের অনুমোদন প্রয়োজন, যার অর্থ হল মূল অনুমোদনগুলিতে নির্দিষ্ট মান থাকতে হবে। যদি তা না হয়, পদ্ধতিটি ErrorCode::INCOMPATIBLE_DIGEST বা ErrorCode::INCOMPATIBLE_PADDING করে। অননুমোদিত ডাইজেস্ট বা প্যাডিং সহ সর্বজনীন কী ক্রিয়াকলাপ (কী KeyPurpose::ENCRYPT এবং KeyPurpose::VERIFY উদ্দেশ্য::যাচাই করা) অনুমোদিত।

PaddingMode::NONE বাদ দিয়ে, সমস্ত RSA প্যাডিং মোড শুধুমাত্র কিছু নির্দিষ্ট উদ্দেশ্যে প্রযোজ্য। বিশেষভাবে, PaddingMode::RSA_PKCS1_1_5_SIGN এবং PaddingMode::RSA_PSS শুধুমাত্র স্বাক্ষর এবং যাচাইকরণ সমর্থন করে, যখন PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT এবং PaddingMode::RSA_OAEP শুধুমাত্র এনক্রিপশন এবং ডিক্রিপশন সমর্থন করে। পদ্ধতিটি ErrorCode::UNSUPPORTED_PADDING_MODE করে যদি নির্দিষ্ট মোড নির্দিষ্ট উদ্দেশ্য সমর্থন না করে।

প্যাডিং মোড এবং ডাইজেস্টের মধ্যে কিছু গুরুত্বপূর্ণ মিথস্ক্রিয়া রয়েছে:

  • PaddingMode::NONE নির্দেশ করে যে একটি "raw" RSA অপারেশন করা হয়েছে। স্বাক্ষর বা যাচাই করা হলে, Digest::NONE জন্য কোনটি নির্দিষ্ট করা নেই। আনপ্যাডেড এনক্রিপশন বা ডিক্রিপশনের জন্য কোন ডাইজেস্টের প্রয়োজন নেই।
  • PaddingMode::RSA_PKCS1_1_5_SIGN প্যাডিংয়ের জন্য একটি ডাইজেস্ট প্রয়োজন। ডাইজেস্ট হতে পারে Digest::NONE , এই ক্ষেত্রে কীমাস্টার বাস্তবায়ন একটি সঠিক PKCS#1 v1.5 স্বাক্ষর কাঠামো তৈরি করতে পারে না, কারণ এটি DigestInfo কাঠামো যোগ করতে পারে না। পরিবর্তে, বাস্তবায়ন 0x00 || 0x01 || PS || 0x00 || M , যেখানে M হল প্রদত্ত বার্তা এবং PS হল প্যাডিং স্ট্রিং। RSA কী-এর আকার বার্তার চেয়ে কমপক্ষে 11 বাইট বড় হতে হবে, অন্যথায় পদ্ধতিটি ErrorCode::INVALID_INPUT_LENGTH করে।
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT প্যাডিংয়ের জন্য ডাইজেস্টের প্রয়োজন হয় না।
  • PaddingMode::RSA_PSS প্যাডিংয়ের জন্য একটি ডাইজেস্ট প্রয়োজন, যা Digest::NONE কোনও নাও হতে পারে। Digest::NONE কোনও নির্দিষ্ট না থাকলে, পদ্ধতিটি ErrorCode::INCOMPATIBLE_DIGEST । উপরন্তু, RSA কী-এর আকার ডাইজেস্টের আউটপুট আকারের চেয়ে কমপক্ষে 2 + D বাইট বড় হতে হবে, যেখানে D হল ডাইজেস্টের আকার, বাইটে। অন্যথায় পদ্ধতিটি ErrorCode::INCOMPATIBLE_DIGEST । লবণের আকার ডি।
  • PaddingMode::RSA_OAEP প্যাডিংয়ের জন্য একটি ডাইজেস্ট প্রয়োজন, যা Digest::NONE কোনও নাও হতে পারে। Digest::NONE কোনও নির্দিষ্ট না থাকলে, পদ্ধতিটি ErrorCode::INCOMPATIBLE_DIGEST ।

ইসি কী

ইসি কী অপারেশনগুলি inParams ঠিক একটি প্যাডিং মোড নির্দিষ্ট করে। অনির্দিষ্ট বা একাধিকবার নির্দিষ্ট করা হলে, পদ্ধতিটি ErrorCode::UNSUPPORTED_PADDING_MODE ।

প্রাইভেট কী ক্রিয়াকলাপ ( কী KeyPurpose::SIGN ) এর জন্য ডাইজেস্ট এবং প্যাডিং এর অনুমোদন প্রয়োজন, যার অর্থ হল মূল অনুমোদনগুলিতে নির্দিষ্ট মান থাকতে হবে। যদি না হয়, ErrorCode::INCOMPATIBLE_DIGEST । অননুমোদিত ডাইজেস্ট বা প্যাডিং সহ সর্বজনীন কী অপারেশন (কী KeyPurpose::VERIFY ) অনুমোদিত।

AES কী

AES কী অপারেশনগুলি inParams ঠিক একটি ব্লক মোড এবং একটি প্যাডিং মোড নির্দিষ্ট করে৷ যদি উভয় মান অনির্দিষ্ট হয় বা একাধিকবার নির্দিষ্ট করা হয়, তাহলে ErrorCode::UNSUPPORTED_BLOCK_MODE বা ErrorCode::UNSUPPORTED_PADDING_MODE । নির্দিষ্ট মোডগুলিকে কী দ্বারা অনুমোদিত হতে হবে, অন্যথায় পদ্ধতিটি ErrorCode::INCOMPATIBLE_BLOCK_MODE বা ErrorCode::INCOMPATIBLE_PADDING_MODE ।

যদি ব্লক মোড BlockMode::GCM হয়, inParams Tag::MAC_LENGTH নির্দিষ্ট করে, এবং নির্দিষ্ট মান হল 8-এর একটি গুণিতক যা মূল Tag::MIN_MAC_LENGTH এর মানের থেকে 128-এর বেশি বা কম নয়। MAC দৈর্ঘ্য 128-এর বেশি বা 8-এর বেশি নয়, ErrorCode::UNSUPPORTED_MAC_LENGTH । কীটির ন্যূনতম দৈর্ঘ্যের চেয়ে কম মানগুলির জন্য, ErrorCode::INVALID_MAC_LENGTH ফেরত দিন।

যদি ব্লক মোড BlockMode::GCM বা BlockMode::CTR হয়, তাহলে নির্দিষ্ট প্যাডিং মোডটি PaddingMode::NONE হতে হবে। BlockMode::ECB বা BlockMode::CBC এর জন্য, মোডটি PaddingMode::NONE বা PaddingMode::PKCS7 PKCS7 হতে পারে। যদি প্যাডিং মোড এই শর্তগুলি পূরণ না করে, তাহলে ErrorCode::INCOMPATIBLE_PADDING_MODE ।

যদি ব্লক মোড BlockMode::CBC , BlockMode::CTR , বা BlockMode::GCM হয়, তাহলে একটি ইনিশিয়ালাইজেশন ভেক্টর বা ননস প্রয়োজন। বেশির ভাগ ক্ষেত্রেই, কলকারীদের IV বা ননস প্রদান করা উচিত নয়। সেক্ষেত্রে, কীমাস্টার ইমপ্লিমেন্টেশন একটি র্যান্ডম IV বা nonce তৈরি করে এবং Tag::NONCE- এ outParams এর মাধ্যমে ফেরত দেয়। CBC এবং CTR IV হল 16 বাইট। GCM nonces হল 12 বাইট। যদি মূল অনুমোদনগুলিতে Tag::CALLER_NONCE থাকে, তাহলে কলকারী ট্যাগ::NONCE- এর সাথে একটি IV/nonce প্রদান করতে পারে inParams এ। যদি ট্যাগ::CALLER_NONCE অনুমোদিত না থাকা অবস্থায় একটি নন্স প্রদান করা হয়, ErrorCode::CALLER_NONCE_PROHIBITED । ট্যাগ::CALLER_NONCE অনুমোদিত হওয়ার সময় যদি একটি নন্স প্রদান না করা হয়, তাহলে একটি এলোমেলো IV/nonce তৈরি করুন।

HMAC কী

HMAC কী অপারেশন Tag::MAC_LENGTH inParams । নির্দিষ্ট মান অবশ্যই 8 এর একটি গুণিতক হতে হবে যা ডাইজেস্ট দৈর্ঘ্যের চেয়ে বেশি নয় বা মূল Tag::MIN_MAC_LENGTH এর মানের থেকে কম নয়৷ ডাইজেস্ট দৈর্ঘ্যের চেয়ে বেশি MAC দৈর্ঘ্যের জন্য বা 8-এর বহুগুণ নয়, ErrorCode::UNSUPPORTED_MAC_LENGTH । কীটির ন্যূনতম দৈর্ঘ্যের চেয়ে কম মানগুলির জন্য, ErrorCode::INVALID_MAC_LENGTH ফেরত দিন।

হালনাগাদ

সংস্করণ : 1, 2, 3

বিগ দিয়ে শুরু হওয়া চলমান অপারেশনে প্রক্রিয়া করার জন্য ডেটা প্রদান করে। অপারেশন হ্যান্ডেল প্যারামিটার দ্বারা operationHandle নির্দিষ্ট করা হয়।

বাফার হ্যান্ডলিংয়ের জন্য আরও নমনীয়তা প্রদান করতে, এই পদ্ধতির বাস্তবায়নে সরবরাহ করা হয়েছে তার চেয়ে কম ডেটা ব্যবহার করার বিকল্প রয়েছে। পরবর্তী কলগুলিতে বাকি ডেটা ফিড করার জন্য কলার দায়বদ্ধ। ইনপুট inputConsumed প্যারামিটারে ইনপুট খাওয়ার পরিমাণ ফেরত দেওয়া হয়। বাস্তবায়ন সর্বদা কমপক্ষে একটি বাইট ব্যবহার করে, যদি না অপারেশনটি আর গ্রহণ করতে না পারে; যদি শূন্য বাইটের বেশি প্রদান করা হয় এবং শূন্য বাইট ব্যবহার করা হয়, কলকারীরা এটিকে একটি ত্রুটি বিবেচনা করে এবং অপারেশন বাতিল করে।

আপডেটের ফলে কতটা ডেটা ফেরত দিতে হবে তা বাস্তবায়নও বেছে নিতে পারে। এটি শুধুমাত্র এনক্রিপশন এবং ডিক্রিপশন ক্রিয়াকলাপের জন্য প্রাসঙ্গিক, কারণ স্বাক্ষর এবং যাচাইকরণ শেষ না হওয়া পর্যন্ত কোনও ডেটা ফেরত দেয় না। যত তাড়াতাড়ি সম্ভব ডেটা ফেরত দিন, বাফার না করে।

শিল্প খাত

যদি এই পদ্ধতিটি ErrorCode::OK ব্যতীত একটি ত্রুটি কোড ফেরত দেয়, তাহলে অপারেশনটি বাতিল করা হয় এবং অপারেশন হ্যান্ডেলটি অবৈধ হয়ে যায়। হ্যান্ডেলের যেকোন ভবিষ্যত ব্যবহার, এই পদ্ধতির সাথে, শেষ করুন বা বাতিল করুন, ErrorCode::INVALID_OPERATION_HANDLE ।

অনুমোদন প্রয়োগ

মূল অনুমোদন প্রয়োগ প্রাথমিকভাবে শুরুতে সঞ্চালিত হয়। একটি ব্যতিক্রম হল সেই ক্ষেত্রে যেখানে কী আছে:

এই ক্ষেত্রে, কীটির জন্য অপারেশন প্রতি একটি অনুমোদনের প্রয়োজন, এবং আপডেট পদ্ধতিটি inParams আর্গুমেন্টে একটি Tag::AUTH_TOKEN পায়। HMAC যাচাই করে যে টোকেনটি বৈধ এবং এতে একটি মিলে যাওয়া সুরক্ষিত ব্যবহারকারী আইডি রয়েছে, কী এর ট্যাগ::USER_AUTH_TYPE এর সাথে মেলে এবং চ্যালেঞ্জ ক্ষেত্রের বর্তমান অপারেশনের অপারেশন হ্যান্ডেল রয়েছে৷ যদি এই শর্তগুলি পূরণ না হয়, তাহলে ErrorCode::KEY_USER_NOT_AUTHENTICATED ।

কলকারী প্রতিটি কল আপডেট এবং শেষ করার জন্য প্রমাণীকরণ টোকেন প্রদান করে। বাস্তবায়নের জন্য শুধুমাত্র একবার টোকেন যাচাই করতে হবে যদি এটি পছন্দ করে।

RSA কী

Digest::NONE এর সাথে সাইনিং এবং যাচাইকরণ ক্রিয়াকলাপগুলির জন্য, এই পদ্ধতিটি একটি একক আপডেটে স্বাক্ষরিত বা যাচাই করা সম্পূর্ণ ব্লককে গ্রহণ করে। এটি ব্লকের শুধুমাত্র একটি অংশ গ্রাস করতে পারে না। যাইহোক, যদি কলকারী একাধিক আপডেটে ডেটা প্রদান করতে পছন্দ করে, এই পদ্ধতিটি তা গ্রহণ করে। যদি কলকারী সাইন করার জন্য ব্যবহার করার চেয়ে বেশি ডেটা প্রদান করে (ডেটার দৈর্ঘ্য RSA কী আকারের চেয়ে বেশি), ErrorCode::INVALID_INPUT_LENGTH ফেরত দিন।

ECDSA কী

Digest::NONE এর সাথে সাইনিং এবং যাচাইকরণ ক্রিয়াকলাপগুলির জন্য, এই পদ্ধতিটি একটি একক আপডেটে স্বাক্ষরিত বা যাচাই করা সম্পূর্ণ ব্লককে গ্রহণ করে। এই পদ্ধতিটি ব্লকের শুধুমাত্র একটি অংশ গ্রাস করতে পারে না।

যাইহোক, যদি কলকারী একাধিক আপডেটে ডেটা প্রদান করতে পছন্দ করে, এই পদ্ধতিটি তা গ্রহণ করে। কলকারী যদি সাইন করার জন্য ব্যবহার করা যায় তার চেয়ে বেশি ডেটা প্রদান করে, ডেটা নীরবে কেটে ফেলা হয়। (এটি অনুরূপ RSA ক্রিয়াকলাপগুলিতে প্রদত্ত অতিরিক্ত ডেটা পরিচালনার থেকে পৃথক। এর কারণ হল উত্তরাধিকার ক্লায়েন্টদের সাথে সামঞ্জস্যতা।)

AES কী

AES GCM মোড inParams আর্গুমেন্টে ট্যাগ::ASSOCIATED_DATA ট্যাগের মাধ্যমে প্রদত্ত "সম্পর্কিত প্রমাণীকরণ ডেটা" সমর্থন করে। সংশ্লিষ্ট ডেটা বারবার কলে প্রদান করা যেতে পারে (একটি ব্লকে পাঠানোর জন্য ডেটা খুব বড় হলে গুরুত্বপূর্ণ) কিন্তু সর্বদা ডেটা এনক্রিপ্ট বা ডিক্রিপ্ট করার আগে থাকে। একটি আপডেট কল এনক্রিপ্ট/ডিক্রিপ্ট করার জন্য সংশ্লিষ্ট ডেটা এবং ডেটা উভয়ই গ্রহণ করতে পারে, কিন্তু পরবর্তী আপডেটগুলিতে সংশ্লিষ্ট ডেটা অন্তর্ভুক্ত নাও হতে পারে। যদি কলকারী একটি কলের পরে একটি আপডেট কলে সম্পর্কিত ডেটা সরবরাহ করে যাতে এনক্রিপ্ট/ডিক্রিপ্ট করার ডেটা অন্তর্ভুক্ত থাকে, ErrorCode::INVALID_TAG ফেরত দিন।

GCM এনক্রিপশনের জন্য, ট্যাগটি শেষ করে সাইফারটেক্সটে যুক্ত করা হয়। ডিক্রিপশনের সময়, শেষ আপডেট কলে দেওয়া ডেটার শেষ Tag::MAC_LENGTH বাইট হল ট্যাগ। যেহেতু আপডেটের একটি প্রদত্ত আহ্বান জানাতে পারে না যে এটি শেষ আহ্বান কিনা, তাই এটি ট্যাগ দৈর্ঘ্য ছাড়া সব প্রক্রিয়া করে এবং ফিনিশের সময় সম্ভাব্য ট্যাগ ডেটা বাফার করে।

শেষ

সংস্করণ : 1, 2, 3

Finishes an ongoing operation started with begin , processing all of the as-yet-unprocessed data provided by update (s).

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

  • PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
  • PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

  • BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
  • BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

  • Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
  • PKCS#1 v1.5 encryption and signing padding modes
  • PSS with a minimum salt length of 20
  • OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

  • configure