1 /* 2 * Copyright 2018 The gRPC Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.grpc.alts.internal; 18 19 import io.netty.buffer.ByteBuf; 20 import java.security.GeneralSecurityException; 21 import java.util.List; 22 23 /** 24 * A @{code ChannelCrypterNetty} performs stateful encryption and decryption of independent input 25 * and output streams. Both decrypt and encrypt gather their input from a list of Netty @{link 26 * ByteBuf} instances. 27 * 28 * <p>Note that we provide implementations of this interface that provide integrity only and 29 * implementations that provide privacy and integrity. All methods should be thread-compatible. 30 */ 31 public interface ChannelCrypterNetty { 32 33 /** 34 * Encrypt plaintext into output buffer. 35 * 36 * @param out the protected input will be written into this buffer. The buffer must be direct and 37 * have enough space to hold all input buffers and the tag. Encrypt does not take ownership of 38 * this buffer. 39 * @param plain the input buffers that should be protected. Encrypt does not modify or take 40 * ownership of these buffers. 41 */ encrypt(ByteBuf out, List<ByteBuf> plain)42 void encrypt(ByteBuf out, List<ByteBuf> plain) throws GeneralSecurityException; 43 44 /** 45 * Decrypt ciphertext into the given output buffer and check tag. 46 * 47 * @param out the unprotected input will be written into this buffer. The buffer must be direct 48 * and have enough space to hold all ciphertext buffers and the tag, i.e., it must have 49 * additional space for the tag, even though this space will be unused in the final result. 50 * Decrypt does not take ownership of this buffer. 51 * @param tag the tag appended to the ciphertext. Decrypt does not modify or take ownership of 52 * this buffer. 53 * @param ciphertext the buffers that should be unprotected (excluding the tag). Decrypt does not 54 * modify or take ownership of these buffers. 55 */ decrypt(ByteBuf out, ByteBuf tag, List<ByteBuf> ciphertext)56 void decrypt(ByteBuf out, ByteBuf tag, List<ByteBuf> ciphertext) throws GeneralSecurityException; 57 58 /** 59 * Decrypt ciphertext into the given output buffer and check tag. 60 * 61 * @param out the unprotected input will be written into this buffer. The buffer must be direct 62 * and have enough space to hold all ciphertext buffers and the tag, i.e., it must have 63 * additional space for the tag, even though this space will be unused in the final result. 64 * Decrypt does not take ownership of this buffer. 65 * @param ciphertextAndTag single buffer containing ciphertext and tag that should be unprotected. 66 * The buffer must be direct and either completely overlap with {@code out} or not overlap at 67 * all. 68 */ decrypt(ByteBuf out, ByteBuf ciphertextAndTag)69 void decrypt(ByteBuf out, ByteBuf ciphertextAndTag) throws GeneralSecurityException; 70 71 /** Returns the length of the tag in bytes. */ getSuffixLength()72 int getSuffixLength(); 73 74 /** Must be called to release all associated resources (instance cannot be used afterwards). */ destroy()75 void destroy(); 76 } 77