SignedCertificateTimestamp ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- com.entrust.toolkit.x509.extensions.SignedCertificateTimestamp

public class SignedCertificateTimestamp
extends java.lang.Object

The Signed Certificate Timestamp is a V3Extension used for Certificate Transparency. It is used in final issued Certificate to indicate it was signed by an external Certificate Transparency Log. From RFC 6962 section 3.3:

 Similarly, a certificate authority MAY submit a Pre certificate to
 more than one log, and all obtained SCTs can be directly embedded in
 the final certificate, by encoding the SignedCertificateTimestampList
 structure as an ASN.1 OCTET STRING and inserting the resulting data
 in the TBSCertificate as an X.509v3 certificate extension (OID
 1.3.6.1.4.1.11129.2.4.2).  Upon receiving the certificate, clients
 can reconstruct the original TBSCertificate to verify the SCT
 signature.
 
 The contents of the ASN.1 OCTET STRING embedded in an OCSP extension
 or X509v3 certificate extension are as follows:
 
     opaque SerializedSCT<1..2^16-1>;

       struct {
           SerializedSCT sct_list <1..2^16-1>;
       } SignedCertificateTimestampList;

  Here, "SerializedSCT" is an opaque byte string that contains the
  serialized TLS structure.  This encoding ensures that TLS clients can
  decode each SCT individually (i.e., if there is a version upgrade,
  out-of-date clients can still parse old SCTs while skipping over new
  SCTs whose versions they don't understand).

The format of the SCT is as follows:

 struct {
         Version sct_version;
          LogID id;
          uint64 timestamp;
          CtExtensions extensions;
          digitally-signed struct {
              Version sct_version;
              SignatureType signature_type = certificate_timestamp;
              uint64 timestamp;
              LogEntryType entry_type;
              select(entry_type) {
                  case x509_entry: ASN.1Cert;
                  case precert_entry: PreCert;
              } signed_entry;
             CtExtensions extensions;
          };
      } SignedCertificateTimestamp;

A digitally-signed element is encoded as a struct DigitallySigned and is defined in RFC 5246 as the following:

    struct {
        SignatureAndHashAlgorithm algorithm;
        opaque signature<0..2^16-1>;
     } DigitallySigned;

The encoding of the HashAlgorithm and Signature Algorithm come from section 7.4.1.4.1 of RFC 5246:

 
 7.4.1.4.1.  Signature Algorithms


  The client uses the "signature_algorithms" extension to indicate to
  the server which signature/hash algorithm pairs may be used in
  digital signatures.  The "extension_data" field of this extension
  contains a "supported_signature_algorithms" value.


     enum {
         none(0), md5(1), sha1(2), sha224(3), sha256(4), sha384(5),
         sha512(6), (255)
     } HashAlgorithm;

     enum { anonymous(0), rsa(1), dsa(2), ecdsa(3), (255) }
       SignatureAlgorithm;

     struct {
           HashAlgorithm hash;
           SignatureAlgorithm signature;
     } SignatureAndHashAlgorithm;

     SignatureAndHashAlgorithm
       supported_signature_algorithms<2..2^16-2>;

Since:: 8.0 patch

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`HASH_ALG_LENGTH` The Hash algorithm length is 1 byte
`static int`	`KEYID_LENGTH` Number of bytes for the KEYID.
`int`	`LOG_ENTRY_TYPE`
`static int`	`LOG_ENTRY_TYPE_LENGTH` The LogEntryType - The Log Entry type length is two bytes enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType;
`static int`	`LOG_ENTRY_TYPE_PRE_CERT`
`static int`	`LOG_ENTRY_TYPE_X509` The LogEntryType - Defined in 6269 as enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType;
`static int`	`MAX_CERTIFICATE_LENGTH` The Maximum Certificate length
`static int`	`MAX_EXTENSION_LENGTH` The Maximum extension length is 2^16-1
`static int`	`MAX_SIGNATURE_LENGTH` The Maximum signature length is 2^16-1
`static int`	`SIGNATURE_ALG_LENGTH` The Signature algorithm length is 1 byte
`static int`	`SIGNATURE_TYPE` The SignatureType - We always use a certificate timestamp so this is a fixed value of 0 enum { certificate_timestamp(0), tree_hash(1), (255) } SignatureType;
`static int`	`SIGNATURE_TYPE_LENGTH` The SignatureType - The length is always 1 Defined AS enum { certificate_timestamp(0), tree_hash(1), (255) } SignatureType;
`static int`	`TIMESTAMP_LENGTH` The length of the Timestamp is always 8 bytes
`static int`	`VERSION_LENGTH` Number of bytes for the VERSION

Constructor Summary

Constructors
Constructor and Description
`SignedCertificateTimestamp(byte[] inputSCT)` Parse an SCT by reading it from the given ByteArray
`SignedCertificateTimestamp(java.io.InputStream inputSCT)` Create an SCT by parsing from the the given InputStream
`SignedCertificateTimestamp(int Version, byte[] keyID, long timestamp, byte[] extensions, byte[] signature)` Create a Signed Certificate Timestamp from the supplied data values.

Method Summary

Methods
Modifier and Type	Method and Description
`byte[]`	`getEncoded()` Encode an SCT as a stream of bytes.
`byte[]`	`getExtension()`
`AlgorithmID`	`getHashAlgorithm()`
`byte[]`	`getLogID()`
`AlgorithmID`	`getSignatureAlgorith()`
`byte[]`	`getSignatureByte()`
`long`	`getTimestamp()`
`int`	`getVersion()`
`java.lang.String`	`toString()` Return the String readable version of the Signed Certificate Timestamp
`boolean`	`verify(X509Certificate cert, java.security.PublicKey key)` Verify this Signed Certificate Timestamp.
`boolean`	`verify(X509Certificate preCertorFinal, java.security.PublicKey logkey, java.security.PublicKey issuerKey)` Verify this Signed Certificate Timestamp.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - VERSION_LENGTH
```
public static final int VERSION_LENGTH
```
    Number of bytes for the VERSION
    
    See Also:
    Constant Field Values
  - LOG_ENTRY_TYPE_LENGTH
```
public static final int LOG_ENTRY_TYPE_LENGTH
```
    The LogEntryType - The Log Entry type length is two bytes enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType;
    
    See Also:
    Constant Field Values
  - LOG_ENTRY_TYPE_X509
```
public static final int LOG_ENTRY_TYPE_X509
```
    The LogEntryType - Defined in 6269 as enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType;
    
    See Also:
    Constant Field Values
  - LOG_ENTRY_TYPE_PRE_CERT
```
public static final int LOG_ENTRY_TYPE_PRE_CERT
```
    See Also:
    Constant Field Values
  - LOG_ENTRY_TYPE
```
public int LOG_ENTRY_TYPE
```
  - SIGNATURE_TYPE_LENGTH
```
public static final int SIGNATURE_TYPE_LENGTH
```
    The SignatureType - The length is always 1 Defined AS enum { certificate_timestamp(0), tree_hash(1), (255) } SignatureType;
    
    See Also:
    Constant Field Values
  - SIGNATURE_TYPE
```
public static final int SIGNATURE_TYPE
```
    The SignatureType - We always use a certificate timestamp so this is a fixed value of 0 enum { certificate_timestamp(0), tree_hash(1), (255) } SignatureType;
    
    See Also:
    Constant Field Values
  - KEYID_LENGTH
```
public static final int KEYID_LENGTH
```
    Number of bytes for the KEYID. It is always 32 since it is a SHA-256 Hash
    
    See Also:
    Constant Field Values
  - TIMESTAMP_LENGTH
```
public static final int TIMESTAMP_LENGTH
```
    The length of the Timestamp is always 8 bytes
    
    See Also:
    Constant Field Values
  - MAX_EXTENSION_LENGTH
```
public static final int MAX_EXTENSION_LENGTH
```
    The Maximum extension length is 2^16-1
    
    See Also:
    Constant Field Values
  - MAX_SIGNATURE_LENGTH
```
public static final int MAX_SIGNATURE_LENGTH
```
    The Maximum signature length is 2^16-1
    
    See Also:
    Constant Field Values
  - MAX_CERTIFICATE_LENGTH
```
public static final int MAX_CERTIFICATE_LENGTH
```
    The Maximum Certificate length
    
    See Also:
    Constant Field Values
  - HASH_ALG_LENGTH
```
public static final int HASH_ALG_LENGTH
```
    The Hash algorithm length is 1 byte
    
    See Also:
    Constant Field Values
  - SIGNATURE_ALG_LENGTH
```
public static final int SIGNATURE_ALG_LENGTH
```
    The Signature algorithm length is 1 byte
    
    See Also:
    Constant Field Values
- Constructor Detail
  - SignedCertificateTimestamp
```
public SignedCertificateTimestamp(int Version,
                          byte[] keyID,
                          long timestamp,
                          byte[] extensions,
                          byte[] signature)
                           throws java.io.IOException
```
    Create a Signed Certificate Timestamp from the supplied data values. This values will come from the Certificate Transparency LOG.
    
    Parameters:
    Version - The version of the protocol to which the SCT conforms, this version is v1 which is
    keyID - The KeyID which is the SHA-256 hash of the logs's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo
    timestamp - The timestamp is the NTP time when the SCT was created
    extensions - Future extensions to the protocol
    signature - The signature over the digitally signed structure.
    
    Throws:
    
    java.io.IOException - if the components could not be parsed
  - SignedCertificateTimestamp
```
public SignedCertificateTimestamp(java.io.InputStream inputSCT)
                           throws java.io.IOException
```
    Create an SCT by parsing from the the given InputStream
    
    Parameters:
    inputSCT - The SCT on the InputStream
    
    Throws:
    
    java.io.IOException
  - SignedCertificateTimestamp
```
public SignedCertificateTimestamp(byte[] inputSCT)
                           throws java.io.IOException
```
    Parse an SCT by reading it from the given ByteArray
    
    Parameters:
    inputSCT - the input Signed Certificate Timestamp
    
    Throws:
    
    java.io.IOException - if there is an error parsing the SignedCertificate Timestamp
- Method Detail
  - getVersion
```
public int getVersion()
```
    Returns:
    the Version used in this Signed Certificate Timestamp
  - getLogID
```
public byte[] getLogID()
```
    Returns:
    the SHA256 hash of the Certificate Transparency LOGS public key
  - getTimestamp
```
public long getTimestamp()
```
    Returns:
    the timestamp which represents the NTP time
  - getExtension
```
public byte[] getExtension()
```
    Returns:
    the list of extensions as a byte array
  - getSignatureAlgorith
```
public AlgorithmID getSignatureAlgorith()
```
    Returns:
    the Signature Algorithm used to sign this Signed Certificate Timestamp
  - getHashAlgorithm
```
public AlgorithmID getHashAlgorithm()
```
    Returns:
    the Hash Algorithm used to hash the data that was digitally signed
  - getSignatureByte
```
public byte[] getSignatureByte()
```
    Returns:
    the byte encoding of the Signature
  - getEncoded
```
public byte[] getEncoded()
                  throws java.io.IOException
```
    Encode an SCT as a stream of bytes. These will be used for generation of the V3Extension which contains the data as a stream of bytes
    
    Returns:
    The Stream of bytes represent the SCT structure
    
    Throws:
    
    java.io.IOException
  - verify
```
public boolean verify(X509Certificate preCertorFinal,
             java.security.PublicKey logkey,
             java.security.PublicKey issuerKey)
               throws java.security.NoSuchAlgorithmException,
                      java.security.NoSuchProviderException,
                      java.security.SignatureException,
                      java.security.InvalidAlgorithmParameterException,
                      java.security.InvalidKeyException,
                      java.io.IOException,
                      java.security.cert.CertificateException,
                      X509ExtensionException
```
    Verify this Signed Certificate Timestamp. The Certificate passed in can be validated if it meets one of the following:
    - The Certificate is the X.509 pre-certificate (signed by the final issuing CA) that was sent to the Certificate Transparency Log
    - The Certificate is the X.509 final certificate issued by the CA with the embedded Signed Certificate Timestamp List
    - The Certificate is an X.509 certificate which was given to the Certificate Transparency Log and the SignedCertificateTimestamp was generated over the X.509 certificate.
    Note: When the certificate is an X.509 certificate that was given to the Certificate Transparency Log with an externally generated Signed Certificate Timestamp List this SignedCertificateTimestampList object would not be extracted from the Certificate, but could be constructed by passing in the list of SignedCertificateTimestamp objects.
    Note: A pre-Certificate issued by a pre-Certificate Signing certificate and containing EKU 1.3.6.1.4.1.11129.2.4.4 cannot be validated by this API.
    Parameters:
    preCertorFinal - The X509Certificate containing the TBSCertificate structure used to create the Signed Certificate Timestamp.
    logkey - The Public Key of the Certificate Transparency Log used to validate the signature in this SignedCertificateTimestamp
    issuerKey - The Public Key of the certificate that issued the certificate that contains the SignedCertificateTimestamp.
    
    Returns:
    true if the verification succeeds or throws an exception if it does not succeed.
    
    Throws:
    
    java.security.NoSuchProviderException - when it can't find the indicated provider
    
    java.security.NoSuchAlgorithmException - when the specified algorithm implementation cannot be found
    
    java.security.SignatureException - to indicate a Signature Failure
    
    java.security.InvalidAlgorithmParameterException - if a problem occurs when reading the algorithm parameters
    
    java.security.InvalidKeyException - to indicate an issue when decoding the keys
    
    java.io.IOException - to indicate an issue when reading/writing the certificates
    
    java.security.cert.CertificateException - to indicate a problem when parsing the certificate
    
    X509ExtensionException - to indicate a problem with X509 extensions
  - verify
```
public boolean verify(X509Certificate cert,
             java.security.PublicKey key)
               throws java.security.InvalidKeyException,
                      java.security.NoSuchAlgorithmException,
                      java.security.NoSuchProviderException,
                      java.security.SignatureException,
                      java.security.InvalidAlgorithmParameterException,
                      java.security.cert.CertificateException,
                      X509ExtensionException,
                      java.io.IOException
```
    Verify this Signed Certificate Timestamp. The Certificate passed in can be validated if it meets the following criteria:
    - The Certificate is an X.509 certificate which was given to the Certificate Transparency Log and the SignedCertificateTimestamp was generated over the X.509 certificate.
    Note: When the certificate is an X.509 certificate that was given to the Certificate Transparency Log with an externally generated Signed Certificate Timestamp List this SignedCertificateTimestamp object would not be extracted from the Certificate, but could be constructed by passing in the SignedCertificateTimestamp itself.
    Parameters:
    cert - The certificate used to calculate the Signed Certificate Timestamp (SCT) signature as mentioned above.
    logkeys - The list of Public Log keys, used to validate the SCT signature(s).
    
    Returns:
    true for validation success or an exception indicating why validatio failed.
    
    Throws:
    
    java.security.NoSuchProviderException - when it can't find the indicated provider
    
    java.security.NoSuchAlgorithmException - when the specified algorithm implementation cannot be found
    
    java.security.SignatureException - to indicate a Signature Failure
    
    java.security.InvalidAlgorithmParameterException - if a problem occurs when reading the algorithm parameters
    
    java.security.InvalidKeyException - to indicate an issue when decoding the keys
    
    java.io.IOException - to indicate an issue when reading/writing the certificates
    
    java.security.cert.CertificateException - to indicate a problem when parsing the certificate
    
    X509ExtensionException - to indicate a problem with X509 extensions
  - toString
```
public java.lang.String toString()
```
    Return the String readable version of the Signed Certificate Timestamp
    
    Overrides:
    
    toString in class java.lang.Object

Class SignedCertificateTimestamp

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

VERSION_LENGTH

LOG_ENTRY_TYPE_LENGTH

LOG_ENTRY_TYPE_X509

LOG_ENTRY_TYPE_PRE_CERT

LOG_ENTRY_TYPE

SIGNATURE_TYPE_LENGTH

SIGNATURE_TYPE

KEYID_LENGTH

TIMESTAMP_LENGTH

MAX_EXTENSION_LENGTH

MAX_SIGNATURE_LENGTH

MAX_CERTIFICATE_LENGTH

HASH_ALG_LENGTH

SIGNATURE_ALG_LENGTH

Constructor Detail

SignedCertificateTimestamp

SignedCertificateTimestamp

SignedCertificateTimestamp

Method Detail

getVersion

getLogID

getTimestamp

getExtension

getSignatureAlgorith

getHashAlgorithm

getSignatureByte

getEncoded

verify

verify

toString