Package org.bouncycastle.pqc.jcajce.provider.util

## Class AsymmetricHybridCipher

- java.lang.Object
- - javax.crypto.CipherSpi
  - - org.bouncycastle.pqc.jcajce.provider.util.CipherSpiExt
    - - org.bouncycastle.pqc.jcajce.provider.util.AsymmetricHybridCipher

- Direct Known Subclasses:
    `McElieceFujisakiCipherSpi`, `McElieceKobaraImaiCipherSpi`, `McEliecePointchevalCipherSpi`

      public abstract class AsymmetricHybridCipher
      extends CipherSpiExt

  The AsymmetricHybridCipher class extends CipherSpiExt. NOTE: Some Ciphers are using Padding. OneAndZeroesPadding is used as default padding. However padding can still be specified, but mode is not supported; if you try to instantiate the cipher with something else than "NONE" as mode, NoSuchAlgorithmException is thrown.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.security.spec.AlgorithmParameterSpec` | `paramSpec` | ParameterSpec used with this cipher

    - ### Fields inherited from class org.bouncycastle.pqc.jcajce.provider.util.CipherSpiExt

      `DECRYPT_MODE, ENCRYPT_MODE, opMode`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AsymmetricHybridCipher()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected abstract int` | `decryptOutputSize​(int inLen)` | Compute the output size of an update() or doFinal() operation of a hybrid asymmetric cipher in decryption mode when given input of the specified length.
    `abstract byte[]` | `doFinal​(byte[] input, int inOff, int inLen)` | Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).
    `int` | `doFinal​(byte[] input, int inOff, int inLen, byte[] output, int outOff)` | Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).
    `protected abstract int` | `encryptOutputSize​(int inLen)` | Compute the output size of an update() or doFinal() operation of a hybrid asymmetric cipher in encryption mode when given input of the specified length.
    `int` | `getBlockSize()` |
    `byte[]` | `getIV()` | Return the initialization vector.
    `int` | `getOutputSize​(int inLen)` | Return the length in bytes that an output buffer would need to be in order to hold the result of the next update or doFinal operation, given the input length `inLen` (in bytes).
    `java.security.spec.AlgorithmParameterSpec` | `getParameters()` | Return the parameters used with this cipher.
    `protected abstract void` | `initCipherDecrypt​(java.security.Key key, java.security.spec.AlgorithmParameterSpec params)` | Initialize the AsymmetricHybridCipher with a certain key for data encryption.
    `protected abstract void` | `initCipherEncrypt​(java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom sr)` | Initialize the AsymmetricHybridCipher with a certain key for data encryption.
    `void` | `initDecrypt​(java.security.Key key)` | Initialize the cipher for decryption by forwarding it to initDecrypt(Key, FlexiSecureRandom).
    `void` | `initDecrypt​(java.security.Key key, java.security.spec.AlgorithmParameterSpec params)` | Initialize the cipher with a certain key for data decryption.
    `void` | `initEncrypt​(java.security.Key key)` | Initialize the cipher for encryption by forwarding it to `initEncrypt(Key, AlgorithmParameterSpec, SecureRandom)`.
    `void` | `initEncrypt​(java.security.Key key, java.security.SecureRandom random)` | Initialize this cipher for encryption by forwarding it to `initEncrypt(Key, AlgorithmParameterSpec, SecureRandom)`.
    `void` | `initEncrypt​(java.security.Key key, java.security.spec.AlgorithmParameterSpec params)` | Initialize the cipher for encryption by forwarding it to initEncrypt(Key, FlexiSecureRandom, AlgorithmParameterSpec).
    `void` | `initEncrypt​(java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random)` | Initialize the cipher with a certain key for data encryption.
    `protected void` | `setMode​(java.lang.String modeName)` | Since asymmetric hybrid ciphers do not support modes, this method does nothing.
    `protected void` | `setPadding​(java.lang.String paddingName)` | Since asymmetric hybrid ciphers do not support padding, this method does nothing.
    `abstract byte[]` | `update​(byte[] input, int inOff, int inLen)` | Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
    `int` | `update​(byte[] input, int inOff, int inLen, byte[] output, int outOff)` | Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

    - ### Methods inherited from class org.bouncycastle.pqc.jcajce.provider.util.CipherSpiExt

      `doFinal, doFinal, engineDoFinal, engineDoFinal, engineGetBlockSize, engineGetIV, engineGetKeySize, engineGetOutputSize, engineGetParameters, engineInit, engineInit, engineInit, engineSetMode, engineSetPadding, engineUpdate, engineUpdate, getKeySize, getName, update`

    - ### Methods inherited from class javax.crypto.CipherSpi

      `engineDoFinal, engineUnwrap, engineUpdate, engineUpdateAAD, engineUpdateAAD, engineWrap`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### paramSpec

          protected java.security.spec.AlgorithmParameterSpec paramSpec

      ParameterSpec used with this cipher

  - ### Constructor Detail

    - #### AsymmetricHybridCipher

          public AsymmetricHybridCipher()

  - ### Method Detail

    - #### setMode

          protected final void setMode​(java.lang.String modeName)

      Since asymmetric hybrid ciphers do not support modes, this method does nothing.
      Specified by:
        `setMode` in class `CipherSpiExt`
      Parameters:
        `modeName` - the cipher mode (unused)

    - #### setPadding

          protected final void setPadding​(java.lang.String paddingName)

      Since asymmetric hybrid ciphers do not support padding, this method does nothing.
      Specified by:
        `setPadding` in class `CipherSpiExt`
      Parameters:
        `paddingName` - the name of the padding scheme (not used)

    - #### getIV

          public final byte[] getIV()

      Description copied from class: `CipherSpiExt`
      Return the initialization vector. This is useful in the context of password-based encryption or decryption, where the IV is derived from a user-provided passphrase.
      Specified by:
        `getIV` in class `CipherSpiExt`
      Returns:
        `null` since no initialization vector is used.

    - #### getBlockSize

          public final int getBlockSize()

      Specified by:
        `getBlockSize` in class `CipherSpiExt`
      Returns:
        0 since the implementing algorithms are not block ciphers

    - #### getParameters

          public final java.security.spec.AlgorithmParameterSpec getParameters()

      Return the parameters used with this cipher.

      The returned parameters may be the same that were used to initialize this cipher, or may contain the default set of parameters or a set of randomly generated parameters used by the underlying cipher implementation (provided that the underlying cipher implementation uses a default set of parameters or creates new parameters if it needs parameters but was not initialized with any).

      Specified by:
        `getParameters` in class `CipherSpiExt`
      Returns:
        the parameters used with this cipher, or `null` if this cipher does not use any parameters.

    - #### getOutputSize

          public final int getOutputSize​(int inLen)

      Return the length in bytes that an output buffer would need to be in order to hold the result of the next update or doFinal operation, given the input length `inLen` (in bytes). This call takes into account any unprocessed (buffered) data from a previous update call, and padding. The actual output length of the next update() or doFinal() call may be smaller than the length returned by this method.
      Specified by:
        `getOutputSize` in class `CipherSpiExt`
      Parameters:
        `inLen` - the length of the input
      Returns:
        the length of the output of the next `update()` or `doFinal()` call

    - #### initEncrypt

          public final void initEncrypt​(java.security.Key key)
                                 throws java.security.InvalidKeyException

      Initialize the cipher for encryption by forwarding it to `initEncrypt(Key, AlgorithmParameterSpec, SecureRandom)`.

      If this cipher requires any algorithm parameters that cannot be derived from the given key, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidKeyException if it is being initialized for decryption. The generated parameters can be retrieved using `getParameters()`.

      Parameters:
        `key` - the encryption key
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher.
        `java.security.InvalidParameterException` - if this cipher needs algorithm parameters for initialization and cannot generate parameters itself.

    - #### initEncrypt

          public final void initEncrypt​(java.security.Key key,
                                        java.security.SecureRandom random)
                                 throws java.security.InvalidKeyException

      Initialize this cipher for encryption by forwarding it to `initEncrypt(Key, AlgorithmParameterSpec, SecureRandom)`.

      If this cipher requires any algorithm parameters that cannot be derived from the given key, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidKeyException if it is being initialized for decryption. The generated parameters can be retrieved using `getParameters()`.

      Parameters:
        `key` - the encryption key
        `random` - the source of randomness
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher.
        `java.security.InvalidParameterException` - if this cipher needs algorithm parameters for initialization and cannot generate parameters itself.

    - #### initEncrypt

          public final void initEncrypt​(java.security.Key key,
                                        java.security.spec.AlgorithmParameterSpec params)
                                 throws java.security.InvalidKeyException,
                                        java.security.InvalidAlgorithmParameterException

      Initialize the cipher for encryption by forwarding it to initEncrypt(Key, FlexiSecureRandom, AlgorithmParameterSpec).
      Parameters:
        `key` - the encryption key
        `params` - the algorithm parameters
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher.
        `java.security.InvalidAlgorithmParameterException` - if the given algorithm parameters are inappropriate for this cipher, or if this cipher is initialized with `null` parameters and cannot generate parameters itself.

    - #### initEncrypt

          public final void initEncrypt​(java.security.Key key,
                                        java.security.spec.AlgorithmParameterSpec params,
                                        java.security.SecureRandom random)
                                 throws java.security.InvalidKeyException,
                                        java.security.InvalidAlgorithmParameterException

      Initialize the cipher with a certain key for data encryption.

      If this cipher requires any random bytes (e.g., for parameter generation), it will get them from `random`.

      Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.

      Specified by:
        `initEncrypt` in class `CipherSpiExt`
      Parameters:
        `key` - the encryption key
        `random` - the source of randomness
        `params` - the algorithm parameters
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher
        `java.security.InvalidAlgorithmParameterException` - if the given algorithm parameters are inappropriate for this cipher, or if this cipher is initialized with `null` parameters and cannot generate parameters itself.

    - #### initDecrypt

          public final void initDecrypt​(java.security.Key key)
                                 throws java.security.InvalidKeyException

      Initialize the cipher for decryption by forwarding it to initDecrypt(Key, FlexiSecureRandom).

      If this cipher requires any algorithm parameters that cannot be derived from the given key, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidKeyException if it is being initialized for decryption. The generated parameters can be retrieved using `getParameters()`.

      Parameters:
        `key` - the decryption key
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher.

    - #### initDecrypt

          public final void initDecrypt​(java.security.Key key,
                                        java.security.spec.AlgorithmParameterSpec params)
                                 throws java.security.InvalidKeyException,
                                        java.security.InvalidAlgorithmParameterException

      Initialize the cipher with a certain key for data decryption.

      If this cipher requires any random bytes (e.g., for parameter generation), it will get them from `random`.

      Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it

      Specified by:
        `initDecrypt` in class `CipherSpiExt`
      Parameters:
        `key` - the decryption key
        `params` - the algorithm parameters
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher
        `java.security.InvalidAlgorithmParameterException` - if the given algorithm parameters are inappropriate for this cipher, or if this cipher is initialized with `null` parameters and cannot generate parameters itself.

    - #### update

          public abstract byte[] update​(byte[] input,
                                        int inOff,
                                        int inLen)

      Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
      Specified by:
        `update` in class `CipherSpiExt`
      Parameters:
        `input` - the input buffer
        `inOff` - the offset where the input starts
        `inLen` - the input length
      Returns:
        a new buffer with the result (maybe an empty byte array)

    - #### update

          public final int update​(byte[] input,
                                  int inOff,
                                  int inLen,
                                  byte[] output,
                                  int outOff)
                           throws javax.crypto.ShortBufferException

      Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
      Specified by:
        `update` in class `CipherSpiExt`
      Parameters:
        `input` - the input buffer
        `inOff` - the offset where the input starts
        `inLen` - the input length
        `output` - the output buffer
        `outOff` - the offset where the result is stored
      Returns:
        the length of the output
      Throws:
        `javax.crypto.ShortBufferException` - if the output buffer is too small to hold the result.

    - #### doFinal

          public abstract byte[] doFinal​(byte[] input,
                                         int inOff,
                                         int inLen)
                                  throws javax.crypto.BadPaddingException

      Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).
      Specified by:
        `doFinal` in class `CipherSpiExt`
      Parameters:
        `input` - the input buffer
        `inOff` - the offset where the input starts
        `inLen` - the input length
      Returns:
        a new buffer with the result
      Throws:
        `javax.crypto.BadPaddingException` - if the ciphertext is invalid.

    - #### doFinal

          public final int doFinal​(byte[] input,
                                   int inOff,
                                   int inLen,
                                   byte[] output,
                                   int outOff)
                            throws javax.crypto.ShortBufferException,
                                   javax.crypto.BadPaddingException

      Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).
      Specified by:
        `doFinal` in class `CipherSpiExt`
      Parameters:
        `input` - the input buffer
        `inOff` - the offset where the input starts
        `inLen` - the input length
        `output` - the buffer for the result
        `outOff` - the offset where the result is stored
      Returns:
        the output length
      Throws:
        `javax.crypto.ShortBufferException` - if the output buffer is too small to hold the result.
        `javax.crypto.BadPaddingException` - if the ciphertext is invalid.

    - #### encryptOutputSize

          protected abstract int encryptOutputSize​(int inLen)

      Compute the output size of an update() or doFinal() operation of a hybrid asymmetric cipher in encryption mode when given input of the specified length.
      Parameters:
        `inLen` - the length of the input
      Returns:
        the output size

    - #### decryptOutputSize

          protected abstract int decryptOutputSize​(int inLen)

      Compute the output size of an update() or doFinal() operation of a hybrid asymmetric cipher in decryption mode when given input of the specified length.
      Parameters:
        `inLen` - the length of the input
      Returns:
        the output size

    - #### initCipherEncrypt

          protected abstract void initCipherEncrypt​(java.security.Key key,
                                                    java.security.spec.AlgorithmParameterSpec params,
                                                    java.security.SecureRandom sr)
                                             throws java.security.InvalidKeyException,
                                                    java.security.InvalidAlgorithmParameterException

      Initialize the AsymmetricHybridCipher with a certain key for data encryption.
      Parameters:
        `key` - the key which has to be used to encrypt data
        `params` - the algorithm parameters
        `sr` - the source of randomness
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher.
        `java.security.InvalidAlgorithmParameterException` - if the given parameters are inappropriate for initializing this cipher.

    - #### initCipherDecrypt

          protected abstract void initCipherDecrypt​(java.security.Key key,
                                                    java.security.spec.AlgorithmParameterSpec params)
                                             throws java.security.InvalidKeyException,
                                                    java.security.InvalidAlgorithmParameterException

      Initialize the AsymmetricHybridCipher with a certain key for data encryption.
      Parameters:
        `key` - the key which has to be used to decrypt data
        `params` - the algorithm parameters
      Throws:
        `java.security.InvalidKeyException` - if the given key is inappropriate for initializing this cipher
        `java.security.InvalidAlgorithmParameterException` - if the given parameters are inappropriate for initializing this cipher.