Package com.bfo.json

Class COSE

java.lang.Object
com.bfo.json.Json
com.bfo.json.COSE
public class COSE extends Json
A basic COSE class. Currently supports COSE signatures only, not encryption.

Examples

 COSE cose = new COSE();
 cose.setPayload(ByteBuffer.wrap("Hello, World".getBytes("UTF-8")));
 cose.sign(privateKey);               // Sign using a private key, eg ES256
 cose.writeCBOR(..., null);           // Save COSE

 json = Json.readCBOR(..., null);     // Reload COSE
 cose = new COSE(json);
 String s = new String(cose.getPayload().array(), "UTF-8"); // Hello, World
 assert jwt.verify(publicKey) == 0;   // Verify with the public key
Since:
5

  • Constructor Details

    • COSE

      public COSE()
      Create a new, uninitialized COSE object

    • COSE

      public COSE(Json cose)
      Create a new COSE from one that has already been read, eg COSE cose = new COSE(Json.readCbor(..., null))
      Parameters:
      cose - the object

  • Method Details

    • setProvider

      public COSE setProvider(Provider provider)
      Set the Provider to be used for any cryptographic operations
      Parameters:
      provider - the crypto Provider to use, or null to use the default
      Returns:
      this

    • getProvider

      public Provider getProvider()
      Return the Provider set by setProvider(java.security.Provider)
      Returns:
      the provider

    • isInitialized

      public boolean isInitialized()
      Return true if this COSE object is initialized. Initialized objects are typically passed into the constructor, or created by a call to sign(java.security.Key, java.lang.String)
      Returns:
      true if this object is initialized

    • getPayload

      public ByteBuffer getPayload()
      Get the payload from this COSE object.
      Returns:
      the payload (the original, not a clone)
      Throws:
      IllegalStateException - if the COSE object has not been set or the payload has not been set

    • isDetached

      public boolean isDetached()
      Return true if the payload was set to "detached".
      Returns:
      if the payload is detached

    • setPayload

      public COSE setPayload(ByteBuffer payload, boolean detached)
      Set the payload to sign. When verifying an existing COSE object where isDetached() is true, this method must be called before verify to set the payload to verify.
      Parameters:
      payload - the payload
      detached - if true, the payload will be "detached" - it will not be stored in the COSE structure. If false, it will be embedded.
      Returns:
      this
      Throws:
      IllegalStateException - if the COSE object has already been set

    • getUnprotectedAttributes

      public Json getUnprotectedAttributes()
      Return the unprotected attributes, which may be null
      Returns:
      the attributes

    • setUnprotectedAttributes

      public COSE setUnprotectedAttributes(Json atts)
      Set the unprotected attributes on this object. This can be called any time. Calling this method will reset the list of certificates returned from getCertificates()
      Parameters:
      atts - the attributes, or null
      Returns:
      this

    • getProtectedAttributes

      public Json getProtectedAttributes()
      Return the protected attributes, which may be null
      Returns:
      the attributes

    • setProtectedAttributes

      public COSE setProtectedAttributes(Json atts)
      Set the protected attributes on this object.
      Parameters:
      atts - the attributes, or null
      Returns:
      this
      Throws:
      IllegalStateException - if the COSE object has already been set

    • getExternalProtectedAttributes

      public Json getExternalProtectedAttributes()
      Return the external protected attributes, as set by setExternalProtectedAttributes(com.bfo.json.Json)
      Returns:
      the attributes

    • setExternalProtectedAttributes

      public COSE setExternalProtectedAttributes(Json atts)
      Set the external protected attributes on this object, which may be null. This can be called any time.
      Parameters:
      atts - the attributes, or null
      Returns:
      this

    • getAlgorithm

      public String getAlgorithm(int signature)
      Return the Signature algorithm used for the specified signature - 0 for the first signature, 1 for the second etc.
      Parameters:
      signature - the index of the signature to query, from 0 to getNumSignatures()-1
      Returns:
      the Signature algorithm
      Throws:
      IllegalArgumentException - if the specified signature is out of range
      IllegalStateException - if the COSE object has not been set

    • getNumSignatures

      public int getNumSignatures()
      Return the number of Sigantures on this COSE object
      Returns:
      the number of signatures
      Throws:
      IllegalStateException - if the COSE object has not been set

    • getCertificates

      public List<X509Certificate> getCertificates()
      If the COSE object contains X.509 Certificates in the header, as defined by RFC9360, then return the list. If the certificate is referenced by URL, it will be downloaded. RFC9630 implies the certificates can be stored as protected or unprotected attributes, or even a combination. This method will check all possibilities and combine into a single list. The return value will be cached until reset (by calling either setCertificates or setUnprotectedAttributes(com.bfo.json.Json).
      Returns:
      the list of certificates, or an empty list if none are specified.

    • setCertificates

      public COSE setCertificates(List<X509Certificate> certs)
      Set a list of X.509 Certificates to be included in the COSE header, or null. Certificates will be merged into the unprotected attributes on save; for more control, they can be set manually in the protected/unproteected attribute list. This can be called any time. Calling this method will reset the list of certificates returned from getCertificates()
      Parameters:
      certs - the list of X.509 certificates, or null
      Returns:
      this

    • verify

      public int verify(PublicKey key)
      Verify a COSE that is initialized
      Parameters:
      key - the key. Should be a PublicKey
      Returns:
      if the COSE is verified, return which Key in the COSE structure this is - 0 for the first key, 1 for the second etc. If it doesn't verify, return -1
      Throws:
      RuntimeException - wrapping a GeneralSecurityException if there are cryptographic problems when verifying.
      IllegalStateException - if the COSE object has not been set

    • sign

      public COSE sign(Key key, String algorithm)
      Sign the COSE. The payload must have been set with setPayload(java.nio.ByteBuffer, boolean).
      Parameters:
      key - the key - should be a PrivateKey
      algorithm - the algorithm name, or null to use the recommended algorithm for that Key type.
      Returns:
      this
      Throws:
      RuntimeException - wrapping a GeneralSecurityException if there are cryptographic problems when signing.
      IllegalStateException - if the COSE object has already set or the payload has not been set

    • sign

      public COSE sign(Map<Key,String> keysAndAlgorithms)
      Sign the COSE with multiple signatures. The payload must have been set with setPayload(java.nio.ByteBuffer, boolean).
      Parameters:
      keysAndAlgorithms - a Map of [key,algorithm name] to sign with. Currently anything other than Private keys will be ignored. Algorithms may be null, if they are the recommended algorithm for each Key type will be used.
      Returns:
      this
      Throws:
      IllegalStateException - if the COSE object has already set or the payload has not been set
      IllegalArgumentException - if no suitable Keys are supplied
      RuntimeException - wrapping a GeneralSecurityException if there are cryptographic problems when signing.