package bccsp

import (
	"crypto"
	"hash"
)

// Key represents a cryptographic key
// 密钥的一般定义
type Key interface {

	// Bytes converts this key to its byte representation,
	// if this operation is allowed.
  // 返回这个key的二进制表示
	Bytes() ([]byte, error)

	// SKI returns the subject key identifier of this key.
  // 标准定义的SKI是：The subject key identifier extension provides a means of
  // identifying certificates that contain a particular public key.
  // 就是用于寻找所有证书里面是否包含了特定的公钥。看BCCSP.GetKey方法，可以理解
  // 为用户id，根据该用户id，从BCCSP中获取公钥
	SKI() []byte

	// Symmetric returns true if this key is a symmetric key,
	// false is this key is asymmetric
  // 若是对称密钥则返回true
	Symmetric() bool

	// Private returns true if this key is a private key,
	// false otherwise.
  // 若是私钥，则返回true
	Private() bool

	// PublicKey returns the corresponding public key part of an asymmetric public/private key pair.
	// This method returns an error in symmetric key schemes.
  // 若本key是私钥，则返回对应的公钥。若是公钥则直接返回。
	PublicKey() (Key, error)
}

// KeyGenOpts contains options for key-generation with a CSP.
// 包含了提供个CSP用于生成密钥的选项，用在BCCSP的Keygen函数
// 下面的都类似，不再说明
type KeyGenOpts interface {

	// Algorithm returns the key generation algorithm identifier (to be used).
  // 指定使用什么算法
	Algorithm() string

	// Ephemeral returns true if the key to generate has to be ephemeral,
	// false otherwise.
  // 指定生成的密钥是否是暂时使用的
	Ephemeral() bool
}

// KeyDerivOpts contains options for key-derivation with a CSP.
type KeyDerivOpts interface {

	// Algorithm returns the key derivation algorithm identifier (to be used).
	Algorithm() string

	// Ephemeral returns true if the key to derived has to be ephemeral,
	// false otherwise.
	Ephemeral() bool
}

// KeyImportOpts contains options for importing the raw material of a key with a CSP.
type KeyImportOpts interface {

	// Algorithm returns the key importation algorithm identifier (to be used).
	Algorithm() string

	// Ephemeral returns true if the key generated has to be ephemeral,
	// false otherwise.
	Ephemeral() bool
}

// HashOpts contains options for hashing with a CSP.
type HashOpts interface {

	// Algorithm returns the hash algorithm identifier (to be used).
	Algorithm() string
}

// SignerOpts contains options for signing with a CSP.
type SignerOpts interface {
	crypto.SignerOpts
}

// EncrypterOpts contains options for encrypting with a CSP.
// 这是空接口，意味着我们可以使用自定义的加密参数类来实现这个，传入任意的参数。
type EncrypterOpts interface{}

// DecrypterOpts contains options for decrypting with a CSP.
type DecrypterOpts interface{}

// BCCSP is the blockchain cryptographic service provider that offers
// the implementation of cryptographic standards and algorithms.
// BCCSP全称区块链密码学服务提供方，提供了一系列密码学服务的接口
type BCCSP interface {

  // -----------------------------密钥管理-------------------------

	// KeyGen generates a key using opts.
  // 根据参数生成Key
	KeyGen(opts KeyGenOpts) (k Key, err error)

	// KeyDeriv derives a key from k using opts.
	// The opts argument should be appropriate for the primitive used.
  // 使用密钥k以及选项opts派生一个新的密钥
  // opts参数需要适合用于底层（Primitive）的加密
	KeyDeriv(k Key, opts KeyDerivOpts) (dk Key, err error)

	// KeyImport imports a key from its raw representation using opts.
	// The opts argument should be appropriate for the primitive used.
  // 将一个密钥的原始表示，使用选项opts来转换成接口所使用的Key类型
	KeyImport(raw interface{}, opts KeyImportOpts) (k Key, err error)

	// GetKey returns the key this CSP associates to
	// the Subject Key Identifier ski.
  // 从本CSP中，根据SKI获取该SKI的公钥
	GetKey(ski []byte) (k Key, err error)

  // -----------------------------哈希算法-----------------------------

	// Hash hashes messages msg using options opts.
	// If opts is nil, the default hash function will be used.
  // 求哈希值，若opts忽略，则使用默认哈希函数
	Hash(msg []byte, opts HashOpts) (hash []byte, err error)

	// GetHash returns and instance of hash.Hash using options opts.
	// If opts is nil, the default hash function will be returned.
  // 获取一个哈希接口的实现。若opts为空，则返回默认实现
	GetHash(opts HashOpts) (h hash.Hash, err error)

  // ------------------------------签名验证----------------------------

	// Sign signs digest using key k.
	// The opts argument should be appropriate for the algorithm used.
	//
	// Note that when a signature of a hash of a larger message is needed,
	// the caller is responsible for hashing the larger message and passing
	// the hash (as digest).
  // 使用密钥K签名。注意，当需要使用消息的哈希时，需要调用方先把消息使用哈希函数
  // 求得哈希之后，再调用本函数求签名。
	Sign(k Key, digest []byte, opts SignerOpts) (signature []byte, err error)

	// Verify verifies signature against key k and digest
	// The opts argument should be appropriate for the algorithm used.
  // 使用密钥K验证签名，也需要先哈希
	Verify(k Key, signature, digest []byte, opts SignerOpts) (valid bool, err error)

  // ----------------------------------加密解密-------------------------

	// Encrypt encrypts plaintext using key k.
	// The opts argument should be appropriate for the algorithm used.
  // 使用密钥k进行加密明文
	Encrypt(k Key, plaintext []byte, opts EncrypterOpts) (ciphertext []byte, err error)

	// Decrypt decrypts ciphertext using key k.
	// The opts argument should be appropriate for the algorithm used.
  // 使用密钥k解密密文
	Decrypt(k Key, ciphertext []byte, opts DecrypterOpts) (plaintext []byte, err error)
}

// KeyStore represents a storage system for cryptographic keys.
// It allows to store and retrieve bccsp.Key objects.
// The KeyStore can be read only, in that case StoreKey will return
// an error.
// Keystore代表一个存储密码学密钥的存储系统。允许存储与取得bccsp.Key类型的对象，
// Keystore可以为只读，这样，StoreKey将会返回一个error对象。
type KeyStore interface {

	// ReadOnly returns true if this KeyStore is read only, false otherwise.
	// If ReadOnly is true then StoreKey will fail.
  // 只读返回true
	ReadOnly() bool

	// GetKey returns a key object whose SKI is the one passed.
  // 使用SKI获取密钥
	GetKey(ski []byte) (k Key, err error)

	// StoreKey stores the key k in this KeyStore.
	// If this KeyStore is read only then the method will fail.
  // 保存密钥。若存储是只读的，则返回error
	StoreKey(k Key) (err error)
}

// ====下面两个函数，是具体实现的函数，存放在pkcs11.go和nopkcs11.go文件中====

// 在使用factory的所有东西之前，首先需要调用这个函数！使用FactoryOpts初始化所有
// 工厂，FactoryOpts可以为空，有默认的设置。
func InitFactories(config *FactoryOpts) error

// 使用FactoryOpts获取BCCSP，根据Opts的ProviderName来获取对应的BCCSP
func GetBCCSPFromOpts(config *FactoryOpts) (bccsp.BCCSP, error)

// ====下面两个函数是工厂通用函数，存放在factory.go文件中====

// 获取一个默认的BCCSP
func GetDefault() bccsp.BCCSP

// 根据名称获取BCCSP，在初始化之后，就可以使用SW、PKCS11、PLUGIN来获取了，就是三个
// Opts对应的三个BCCSP
func GetBCCSP(name string) (bccsp.BCCSP, error)

// FactoryOpts holds configuration information used to initialize factory implementations
// 保存了初始化factory实例的配置信息
type FactoryOpts struct {
	ProviderName string            
	SwOpts       *SwOpts           
	PluginOpts   *PluginOpts        
	Pkcs11Opts   *pkcs11.PKCS11Opts
}

github.com/hyperledger/fabric/bccsp/
├── aesopts.go                      AES加密算法选项
├── bccsp.go                        BCCSP接口定义
├── ecdsaopts.go                    ECDSA加密算法选项
├── factory                         工厂包
│   ├── factory.go                 BCCSP工厂接口和通用函数定义
│   ├── nopkcs11.go                不包含PCKS11 BCCSP的工厂的选项，以及初始化工厂函数
│   ├── opts.go                    主要放置了默认选项
│   ├── pkcs11factory.go           PCKS11 BCCSP工厂定义
│   ├── pkcs11.go                  包含PCKS11 BCCSP的工厂的选项，以及初始化工厂的函数
│   ├── pluginfactory.go           PLUGIN BCCSP工厂定义
│   └── swfactory.go               Software-Based BCCSP工厂定义
├── hashopts.go                     哈希选项
├── keystore.go                     密钥存储库接口
├── mocks
│   └── mocks.go                   测试用的
├── opts.go                         放置许多Opts结构定义的位置
├── pkcs11                          这是PKCS11 BCCSP接口的实现，与SW类似，请看下面
│   ├── conf.go
│   ├── ecdsa.go
│   ├── ecdsakey.go
│   ├── impl.go
│   └── pkcs11.go
├── rsaopts.go
├── signer
│   └── signer.go                  签名工具的定义。签名使用的接口是`crypto`库
├── sw                              Software-Based BCCSP库
│   ├── aes.go                     AES加解密算法实现
│   ├── aeskey.go                  AES密钥实现
│   ├── conf.go                    impl的config对象结构定义
│   ├── dummyks.go                 一个辣鸡的密钥存储库实现，当不持久化数据时使用
│   ├── ecdsa.go                   ECDSA加解密算法
│   ├── ecdsakey.go                ECDSA密钥实现
│   ├── fileks.go                  基于文件的密钥存储库实现
│   ├── hash.go                    哈希算法通用实现
│   ├── impl.go                    SW实现所在地，结构名为impl，包含了对BCCSP接口的实现方法
│   ├── internals.go               impl实现使用的一些接口定义
│   ├── keyderiv.go                密钥派生函数实现
│   ├── keygen.go                  密钥生成函数实现
│   ├── keyimport.go               密钥导入函数实现
│   ├── mocks                      
│   │   └── mocks.go              又一个辣鸡实现
│   ├── rsa.go                     rsa加解密算法实现
│   └── rsakey.go                  rsa密钥实现
└── utils                           就一些通用函数，不多说
    ├── ecdsa.go
    ├── errs.go
    ├── io.go
    ├── keys.go
    ├── slice.go
    └── x509.go

// SoftwareBasedBCCSP is the software-based implementation of the BCCSP.
type impl struct {
	conf *config
	ks   bccsp.KeyStore

	keyGenerators map[reflect.Type]KeyGenerator
	keyDerivers   map[reflect.Type]KeyDeriver
	keyImporters  map[reflect.Type]KeyImporter
	encryptors    map[reflect.Type]Encryptor
	decryptors    map[reflect.Type]Decryptor
	signers       map[reflect.Type]Signer
	verifiers     map[reflect.Type]Verifier
	hashers       map[reflect.Type]Hasher
}

// 为简化，已省略注释，注释内容与BCCSP的类似
type KeyGenerator interface {
	KeyGen(opts bccsp.KeyGenOpts) (k bccsp.Key, err error)
}

type KeyDeriver interface {
	KeyDeriv(k bccsp.Key, opts bccsp.KeyDerivOpts) (dk bccsp.Key, err error)
}

type KeyImporter interface {
	KeyImport(raw interface{}, opts bccsp.KeyImportOpts) (k bccsp.Key, err error)
}

type Encryptor interface {
	Encrypt(k bccsp.Key, plaintext []byte, opts bccsp.EncrypterOpts) (ciphertext []byte, err error)
}

type Decryptor interface {
	Decrypt(k bccsp.Key, ciphertext []byte, opts bccsp.DecrypterOpts) (plaintext []byte, err error)
}

type Signer interface {
	Sign(k bccsp.Key, digest []byte, opts bccsp.SignerOpts) (signature []byte, err error)
}

type Verifier interface {
	Verify(k bccsp.Key, signature, digest []byte, opts bccsp.SignerOpts) (valid bool, err error)
}

type Hasher interface {
	Hash(msg []byte, opts bccsp.HashOpts) (hash []byte, err error)
	GetHash(opts bccsp.HashOpts) (h hash.Hash, err error)
}

func New(securityLevel int, hashFamily string, keyStore bccsp.KeyStore) (bccsp.BCCSP, error)

func (csp *CSP) Sign(k bccsp.Key, digest []byte, opts bccsp.SignerOpts) (signature []byte, err error) {
  // ...
	keyType := reflect.TypeOf(k)
	signer, found := csp.signers[keyType]
  // ...
	signature, err = signer.Sign(k, digest, opts)
  // ...
	return
}

// BCCSPFactory is used to get instances of the BCCSP interface.
// A Factory has name used to address it.
// 用于构造BCCSP实例，每个具体的工厂都有自己的名字。
type BCCSPFactory interface {

	// Name returns the name of this factory
	Name() string

	// Get returns an instance of BCCSP using opts.
  // 根据工厂选项FactoryOpts来创建BCCSP，注意，其实他用的是SWOpts等三个具体的Opts
	Get(opts *FactoryOpts) (bccsp.BCCSP, error)
}

// Software-Based BCCSP
if config.SwOpts != nil {
  f := &SWFactory{}
  err := initBCCSP(f, config)
  if err != nil {
    factoriesInitError = errors.Wrap(err, "Failed initializing SW.BCCSP")
  }
}

func initBCCSP(f BCCSPFactory, config *FactoryOpts) error {
	csp, err := f.Get(config)
	if err != nil {
		return errors.Errorf("Could not initialize BCCSP %s [%s]", f.Name(), err)
	}

	logger.Debugf("Initialize BCCSP [%s]", f.Name())
	bccspMap[f.Name()] = csp
	return nil
}

var ok bool
defaultBCCSP, ok = bccspMap[config.ProviderName]
if !ok {
  factoriesInitError = errors.Errorf("%s\nCould not find default `%s` BCCSP", factoriesInitError, config.ProviderName)
}

type FactoryOpts struct {
    *factory.FactoryOpts
    ABEOpts *ABEOpts `mapstructure:"ABE,omitempty" json:"ABE,omitempty" yaml:"ABE"`
}

// 在使用BCCSPFactory接口之前，必须调用此函数，初始化
func InitFactories(config *FactoryOpts) error {
    factoriesInitOnce.Do(func() {
        // 调用本来的，以初始化本来的factory
        factoriesInitError = factory.InitFactories(config.FactoryOpts)
        if factoriesInitError != nil {
            return
        }
        factoriesInitError = setABEFactory(config)
    })

    return factoriesInitError
}