net.i2p.data

## Class Certificate

- java.lang.Object
- - net.i2p.data.DataStructureImpl
  - - net.i2p.data.Certificate

- All Implemented Interfaces:
    Serializable, DataStructure
  Direct Known Subclasses:
    KeyCertificate

      public class Certificate
      extends DataStructureImpl

  Extensible certificate system for I2P structures providing metadata and capabilities.

  Certificate offers flexible metadata attachment to I2P identities:

  - Metadata: Additional information beyond cryptographic keys
  - DoS Protection: Help manage denial of service attacks
  - Network Utilization: Control resource usage and capabilities
  - Extensible: Support for multiple certificate types and formats
  - Optional: Structures can have NULL certificates for minimal overhead

  Supported Certificate Types:

  - `CERTIFICATE_TYPE_NULL` - No certificate (default)
  - `CERTIFICATE_TYPE_HIDDEN` - Service should not be published
  - `CERTIFICATE_TYPE_SIGNED` - Signed by certificate authority
  - `CERTIFICATE_TYPE_MULTIPLE` - Contains multiple certificates
  - `CERTIFICATE_TYPE_KEY` - Specifies key types (KeyCertificate)

  Common Use Cases:

  - Identity Verification: Prove authenticity of routers/destinations
  - Capability Advertising: Announce supported features and protocols
  - Access Control: Specify service restrictions or requirements
  - Resource Management: Indicate bandwidth or usage limitations
  - Trust Establishment: Certificate authority-based trust chains

  Security Considerations:

  - Anonymous Network: CA-based certificates may not be appropriate
  - Signature Verification: Always verify certificate signatures
  - Trust Validation: Carefully evaluate certificate authorities
  - Privacy Impact: Consider anonymity implications of certificates

  Implementation Notes:

  - Multiple Certificates: Support for multiple certificates is planned
  - Size Efficiency: Minimal overhead for NULL certificates
  - Flexibility: Payload can contain arbitrary metadata
  - Backward Compatibility: Existing formats continue to be supported

  Related Structures:

  - `Destination` - Uses certificates for service identity
  - `RouterIdentity` - Router certificates
  - `KeyCertificate` - Specialized certificate for key type specification
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected byte[]` | `_payload`
    `protected int` | `_type`
    `static int` | `CERTIFICATE_LENGTH_SIGNED_WITH_HASH`
    `static int` | `CERTIFICATE_TYPE_HIDDEN` we should not be used for anything (don't use us in the netDb, in tunnels, or tell others about us)
    `static int` | `CERTIFICATE_TYPE_KEY` Key certificate type.
    `static int` | `CERTIFICATE_TYPE_MULTIPLE` Contains multiple certs
    `static int` | `CERTIFICATE_TYPE_NULL` Specifies a null certificate type with no payload
    `static int` | `CERTIFICATE_TYPE_SIGNED` Signed with 40-byte Signature and (optional) 32-byte hash
    `static Certificate` | `NULL_CERT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Certificate()`
    `Certificate(int type, byte[] payload)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Certificate` | `create(byte[] data, int off)` If null, P256 key, or Ed25519 key cert, return immutable static instance, else create new
    `static Certificate` | `create(InputStream in)` If null, P256 key, or Ed25519 key cert, return immutable static instance, else create new
    `boolean` | `equals(Object object)`
    `int` | `getCertificateType()` Gets the certificate type.
    `byte[]` | `getPayload()`
    `int` | `hashCode()`
    `int` | `readBytes(byte[] source, int offset)` Reads the certificate from the source array.
    `void` | `readBytes(InputStream in)` Load up the current object with data from the given stream.
    `void` | `setCertificateType(int type)` Sets the certificate type.
    `void` | `setPayload(byte[] payload)` Sets the certificate payload.
    `int` | `size()`
    `KeyCertificate` | `toKeyCertificate()` Up-convert this to a KeyCertificate
    `String` | `toString()`
    `int` | `writeBytes(byte[] target, int offset)` Writes the certificate to the target array.
    `void` | `writeBytes(OutputStream out)` Write out the data structure to the stream, using the format defined in the I2P data structure specification.

    - ### Methods inherited from class net.i2p.data.DataStructureImpl

      `calculateHash, fromBase64, fromByteArray, read, toBase64, toByteArray`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### _payload

          protected byte[] _payload

    - #### _type

          protected int _type

    - #### CERTIFICATE_LENGTH_SIGNED_WITH_HASH

          public static final int CERTIFICATE_LENGTH_SIGNED_WITH_HASH

    - #### CERTIFICATE_TYPE_HIDDEN

          public static final int CERTIFICATE_TYPE_HIDDEN

      we should not be used for anything (don't use us in the netDb, in tunnels, or tell others about us)
      See Also:
        Constant Field Values

    - #### CERTIFICATE_TYPE_KEY

          public static final int CERTIFICATE_TYPE_KEY

      Key certificate type.
      See Also:
        Constant Field Values

    - #### CERTIFICATE_TYPE_MULTIPLE

          public static final int CERTIFICATE_TYPE_MULTIPLE

      Contains multiple certs
      See Also:
        Constant Field Values

    - #### CERTIFICATE_TYPE_NULL

          public static final int CERTIFICATE_TYPE_NULL

      Specifies a null certificate type with no payload
      See Also:
        Constant Field Values

    - #### CERTIFICATE_TYPE_SIGNED

          public static final int CERTIFICATE_TYPE_SIGNED

      Signed with 40-byte Signature and (optional) 32-byte hash
      See Also:
        Constant Field Values

    - #### NULL_CERT

          public static final Certificate NULL_CERT

  - ### Constructor Detail

    - #### Certificate

          public Certificate()

    - #### Certificate

          public Certificate(int type,
                             byte[] payload)

      Throws:
        `IllegalArgumentException` - if type < 0

  - ### Method Detail

    - #### create

          public static Certificate create(byte[] data,
                                           int off)
                                    throws DataFormatException

      If null, P256 key, or Ed25519 key cert, return immutable static instance, else create new
      Throws:
        `DataFormatException` - if not enough bytes

    - #### create

          public static Certificate create(InputStream in)
                                    throws DataFormatException,
                                           IOException

      If null, P256 key, or Ed25519 key cert, return immutable static instance, else create new
      Throws:
        `DataFormatException`
        `IOException`

    - #### equals

          public boolean equals(Object object)

      Overrides:
        `equals` in class `Object`

    - #### getCertificateType

          public int getCertificateType()

      Gets the certificate type.

    - #### getPayload

          public byte[] getPayload()

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### readBytes

          public int readBytes(byte[] source,
                               int offset)
                        throws DataFormatException

      Reads the certificate from the source array.
      Throws:
        `IllegalStateException` - if already set
        `DataFormatException`

    - #### readBytes

          public void readBytes(InputStream in)
                         throws DataFormatException,
                                IOException

      Description copied from interface: `DataStructure`
      Load up the current object with data from the given stream. Data loaded this way must match the I2P data structure specification. Warning - many classes will throw IllegalStateException if data is already set.
      Parameters:
        `in` - stream to read from
      Throws:
        `IllegalStateException` - if already set
        `DataFormatException` - if the data is improperly formatted
        `IOException` - if there was a problem reading the stream

    - #### setCertificateType

          public void setCertificateType(int type)

      Sets the certificate type.
      Throws:
        `IllegalArgumentException` - if type < 0
        `IllegalStateException` - if already set

    - #### setPayload

          public void setPayload(byte[] payload)

      Sets the certificate payload.
      Throws:
        `IllegalStateException` - if already set

    - #### size

          public int size()

    - #### toKeyCertificate

          public KeyCertificate toKeyCertificate()
                                          throws DataFormatException

      Up-convert this to a KeyCertificate
      Throws:
        `DataFormatException` - if cert type != CERTIFICATE_TYPE_KEY

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### writeBytes

          public int writeBytes(byte[] target,
                                int offset)

      Writes the certificate to the target array.
      Returns:
        the written length (NOT the new offset)

    - #### writeBytes

          public void writeBytes(OutputStream out)
                          throws DataFormatException,
                                 IOException

      Description copied from interface: `DataStructure`
      Write out the data structure to the stream, using the format defined in the I2P data structure specification.
      Parameters:
        `out` - stream to write to
      Throws:
        `DataFormatException` - if the data was incomplete or not yet ready to be written
        `IOException` - if there was a problem writing to the stream