Thoughts on Refactor Signer submodule in notation-core-go to support cose

[binbin-li]

Backgroud

We're adding COSE built-in/external support to notation currently. For now there is a SignatureProvider providing the basic logic to sign the payload in bytes and a SignatureEnvelope to wrap up functions to generate and verify signatures. However, it only supports JWS envelope/signing for now which is not generalized for a new envelope like COSE. So some refactoring are necessary to be made on it so that we can extend it to new envelopes easily.

Current Provider Implementation

Code reference to provider implementation: LocalSignatureProvider

Code reference to internal envelope implementation: jwsEnvelope

COSE Implementation

The signing logic would be quite different from that for COSE which is explained in the example: COSE_Sign1

Problem

The overall signing logics for each combination of COSE/JWS and RSA/ECDSA can be simplified as below:

1. COSE 
	a. ecdsa:
                msgToSign = cose.NewSign1Message()
                msgToSign.Payload = []byte("hello world")
		signer = cose.NewSigner(cose.AlgorithmES512, privateKey) 
		msgToSign.Sign(io.Reader, nil, signer) 
	b. rsa: 
                msgToSign := cose.NewSign1Message()
                msgToSign.Payload = []byte("hello world")
		signer = cose.NewSigner(cose.AlgorithmPS512, privateKey) 
		msgToSign.Sign(io.Reader, nil, signer) 

2. JWS 
	a. ecdsa: 
                digest := h.Sum()
		ecdsa.Sign(io.Reader, privateKey, digest []byte) 
	b. rsa:
                digest := h.Sum()
		rsa.SignPss(io.Reader, privateKey, crypto.Hash, digest []byte, *Opts) 

Problems

1. We can see that the basic signing logics are different in COSE/Jws. And they don't share the same exported interface, neither the way performing the signing. Specifically a COSE (built-in/remote) signer needs to implement the Signer interface.
2. The LocalSignatureProvider should be designed for all signers(COSE/JWS). But the current implementation follows the workflow of a JWS signer. To support COSE signer, we need to refactor the local provider to support multiple local signers.
3. Currently we have defined SignatureEnvelope struct for verification and signing in notation-go. It's better to expose those APIs wrapped in an interface for better abstraction and easier unit tests.

Proposed Solution

Envelope

1. For the envelope, we expose 4 basic APIs(Sign, Verify, Payload, SignerInfo) in the Envelope interface.
2. We need a base envelope that wraps a raw signature and an internal envelope.
   2.1 The internal envelope can be a JWS envelope or COSE envelope. It handles the actual signing/verifying for a specific envelope format.
   2.2 The base envelope wraps up a raw signature and the internal envelope. The base envelope implements the same interface as the internal envelope. The base envelope implementation just holds the common logics shared by JWS/COSE internal envelopes.

Signer

1. Signer interface exposes 2 basic APIs(Sign, KeySpec). It performs the same functioanalities as the original SignatureProvider.
2. Signers could be classified into external/built-in singers. And built-in signers can be divided into JWS/COSE signers.
3. For the Local Signer, we create a LocalSigner interface embedding a Signer interface with additional PrivateKey() and CertificateChain() APIs. When the envelope needs to create a local signer, it just checks if the given signer holds the LocalSigner interface.
4. For the extenal signer, it just needs to follow the correspondoing signer interface(JWS/COSE).

Diagram

Additional Refactoring

The Signer submodule was designed for JWS in the notation-core-go. Since we're adding COSE support and will add more files inside, it's necessary to restructure the directory as well.
The directory can be refactored like the below structure:

envelope
├── errors.go
├── types.go
├── signer.go
├── envelope.go
├── algorithm.go
└── jws
    ├── jws.go
    ├── jwt.go
    └── envelope.go
└── cose
    └── envelope.go
└── internal
    └── base
        └── envelope.go

[priteshbandi]

I would like to understand the problem before we refactor the code:

We can see that the basic signing logics are different in COSE/Jws. And they don't share the same exported interface, neither the way performing the signing.

Whats the interface for remote signing in cose? Usually, the remote signing interface would take a bag of bits to sign.

COSE takes in a payload, but JWS takes in a digest.

The current code doesn't restrict what the input to the singing library, it provides a way to plug remote or local signer transparently

The LocalSignatureProvider should be designed for all built-in providers, COSE/Jws in this case. But it couples the the context logic of Jws and that of the algorithm(RSA/ECDSA). So if we're adding COSE support directly, it needs to handle both contexts. The same issue applies to the external plugins.

LocalSignatureProvider is independent of JWS or any other signature format...It only knows how to sign a given bag of bits i.e. hash and encrypt it.

[binbin-li]

@priteshbandi thanks for your comments.

Whats the interface for remote signing in cose? Usually, the remote signing interface would take a bag of bits to sign.

This is the cose signer interface we need to implement: cose.Signer

The current code doesn't restrict what the input to the singing library, it provides a way to plug remote or local signer transparently

I didn't describe it correctly. It's just about the input to the Sign() method of the SignatureProvider interface. I tried to accommodate it to COSE signer. But as discussed in notaryproject/specifications#185, we don't need to refactor it anymore. It's removed from the problem list.

LocalSignatureProvider is independent of JWS or any other signature format...It only knows how to sign a given bag of bits i.e. hash and encrypt it.

You're right on the purpose of LocalSignatureProvider. It's just the current implementation which only works in the JWS signing way. So we want to refactor it so that it can support multiple local signers easily.

btw, I updated the descriptions accroding to your questions as well.

[rgnote]

@binbin-li From the above conversation, it looks like the current implementation does support extending to COSE without lot of refactoring to SignatureEnvelope and SignatureProvider. Can you clarify what this discussion is trying to achieve?

[binbin-li]

@rgnote We want to achieve 3 goals via refactoring:

1. Expose a uniform Envelope interface to notation-go. Current implementation defined an exposed SignatureEnvelope struct with Verify(), Sign() and GetSignerInfo() methods and an internal internalSignatureEnvelope interface with similar methods validateIntegrity(), getSignerInfo(), signPayload(). We'd like to have an Envelope interface for both exposed envelope and internal envelope to implement which would be more clear and easier to be tested in notation-go.
2. Rename the SignatureProvider interface to Signer interface which better reflects its functionality.
3. We'd like to create a new LocalSigner interface extending from Signer interface to distinguish between local and remote signers. In the current implementation, we have defined localSignatureProvider to support local JWS signing library. The new LocalSigner interface can be used by COSE and JWS.

[priteshbandi]

1. Expose a uniform Envelope interface to notation-go. Current implementation defined an exposed SignatureEnvelope struct with Verify(), Sign() and GetSignerInfo() methods and an internal internalSignatureEnvelope interface with similar methods validateIntegrity(), getSignerInfo(), signPayload(). We'd like to have an Envelope interface for both exposed envelope and internal envelope to implement which would be more clear and easier to be tested in notation-go.

Why is this a requirement? With current implementation only Verify(), Sign() and GetSignerInfo() methods are visible to caller (aka outside the package)

3. We'd like to create a new LocalSigner interface extending from Signer interface to distinguish between local and remote signers. In the current implementation, we have defined localSignatureProvider to support local JWS signing library. The new LocalSigner interface can be used by COSE and JWS.

Why are we trying to distinguish between local and remote signers?

[patrickzheng200]

@binbin-li Let's update the diagram, we have CertificateChain() under the LocalSigner interface now.