github.com/gnolang/gno@v0.0.0-20240520182011-228e9d0192ce/gnovm/stdlibs/crypto/cipher/cipher.gno (about)

     1  package cipher
     2  
     3  import "io"
     4  
     5  type AEAD interface {
     6  	// NonceSize returns the size of the nonce that must be passed to Seal
     7  	// and Open.
     8  	NonceSize() int
     9  
    10  	// Overhead returns the maximum difference between the lengths of a
    11  	// plaintext and its ciphertext.
    12  	Overhead() int
    13  
    14  	// Seal encrypts and authenticates plaintext, authenticates the
    15  	// additional data and appends the result to dst, returning the updated
    16  	// slice. The nonce must be NonceSize() bytes long and unique for all
    17  	// time, for a given key.
    18  	//
    19  	// To reuse plaintext's storage for the encrypted output, use plaintext[:0]
    20  	// as dst. Otherwise, the remaining capacity of dst must not overlap plaintext.
    21  	Seal(dst, nonce, plaintext, additionalData []byte) []byte
    22  
    23  	// Open decrypts and authenticates ciphertext, authenticates the
    24  	// additional data and, if successful, appends the resulting plaintext
    25  	// to dst, returning the updated slice. The nonce must be NonceSize()
    26  	// bytes long and both it and the additional data must match the
    27  	// value passed to Seal.
    28  	//
    29  	// To reuse ciphertext's storage for the decrypted output, use ciphertext[:0]
    30  	// as dst. Otherwise, the remaining capacity of dst must not overlap plaintext.
    31  	//
    32  	// Even if the function fails, the contents of dst, up to its capacity,
    33  	// may be overwritten.
    34  	Open(dst, nonce, ciphertext, additionalData []byte) ([]byte, error)
    35  }
    36  
    37  type Block interface {
    38  	// BlockSize returns the cipher's block size.
    39  	BlockSize() int
    40  
    41  	// Encrypt encrypts the first block in src into dst.
    42  	// Dst and src must overlap entirely or not at all.
    43  	Encrypt(dst, src []byte)
    44  
    45  	// Decrypt decrypts the first block in src into dst.
    46  	// Dst and src must overlap entirely or not at all.
    47  	Decrypt(dst, src []byte)
    48  }
    49  
    50  type BlockMode interface {
    51  	// BlockSize returns the mode's block size.
    52  	BlockSize() int
    53  
    54  	// CryptBlocks encrypts or decrypts a number of blocks. The length of
    55  	// src must be a multiple of the block size. Dst and src must overlap
    56  	// entirely or not at all.
    57  	//
    58  	// If len(dst) < len(src), CryptBlocks should panic. It is acceptable
    59  	// to pass a dst bigger than src, and in that case, CryptBlocks will
    60  	// only update dst[:len(src)] and will not touch the rest of dst.
    61  	//
    62  	// Multiple calls to CryptBlocks behave as if the concatenation of
    63  	// the src buffers was passed in a single run. That is, BlockMode
    64  	// maintains state and does not reset at each CryptBlocks call.
    65  	CryptBlocks(dst, src []byte)
    66  }
    67  
    68  type Stream interface {
    69  	// XORKeyStream XORs each byte in the given slice with a byte from the
    70  	// cipher's key stream. Dst and src must overlap entirely or not at all.
    71  	//
    72  	// If len(dst) < len(src), XORKeyStream should panic. It is acceptable
    73  	// to pass a dst bigger than src, and in that case, XORKeyStream will
    74  	// only update dst[:len(src)] and will not touch the rest of dst.
    75  	//
    76  	// Multiple calls to XORKeyStream behave as if the concatenation of
    77  	// the src buffers was passed in a single run. That is, Stream
    78  	// maintains state and does not reset at each XORKeyStream call.
    79  	XORKeyStream(dst, src []byte)
    80  }
    81  
    82  type StreamReader struct {
    83  	S Stream
    84  	R io.Reader
    85  }
    86  
    87  type StreamWriter struct {
    88  	S   Stream
    89  	W   io.Writer
    90  	Err error // unused
    91  }