x/crypto: document how to unmarshal ssh certs

[cviecco]

What did you do?

While writing an application that generates ssh certificates I wanted to audit its output, by verifying the signed ssh certificate against signing policies.

What did you expect to see?

A public function that unmarshalls a []byte into an *ssh.Certificate. This is 98% done already with the private parseCert function.

What did you see instead?

No public function to unmarshal ssh certificates (a private one exists) and the Unmarshall (which is the mirror of Marshall and not suitable for my purposes ( see: #21491 )).

[cviecco]

The code for this function would be trivial:

func ParseCertificate(wireBytes []byte) (*Certificate, error) {
algo, in, ok := parseString(wireBytes)
if !ok {
return nil, errShortRead
}
return parseCert(in, certToPrivAlgo(string(algo)))
}

[rsc]

/cc @hanwen @x1ddos @FiloSottile @agl (recent Reviewers of golang.org/x/net/ssh)

[hanwen]

doesn't ParsePublicKey work?

btw - what does "verifying the signed ssh certificate against signing policies" mean?

[cviecco]

No, parse publicKey gets me the public key, not the other members of the certificate like the ValidPrincipals, ValidAfter, ValidBefore etc.

what does "verifying the signed ssh certificate against signing policies" mean?
After I generate a certificate ( (*Certificate) SignCert ) and give it to an external user ( (*Certificate) Marshal) I wan to take the marshalled representation and verify that the ValidBefore, ValidPrincipals match what I expect.
Think certificate transparency for ssh certs.

[hanwen]

public key is an interface. You can cast to ssh.Certificate, see https://gist.github.com/hanwen/ec620792123ffee5c2cdfbcc33fab0da

SignCert just signs the certificate in place (setting nonce, signature and signaturekey). You can (and should!) check the fields of the certificate that you want to sign before you call SignCert.

Marshal does not modify the certificate, so there is no need to go through a Marshal/Unmarshal step when you do this check.

[cviecco]

I guess I explained myself poorly. I have two processes: P1: generates ssh certs and writes the marshalled certificate to a log. P2: Audits P1 by unmarshalling the generated certificates(in the log) and looking at the fields.

The publicKey interface is not enough for auditing purposes. This is an ask for the inverse of (*Certficiate)Marsall just like the crypto/x509's ParseCertificate.

[hanwen]

"The publicKey interface is not enough for auditing purposes." - you can cast the PublicKey to a certificate and audit it to your heart's desire.

I don't want to provide syntactic sugar for what is essentially a one-liner, but maybe you can think of a way to clarify the docs?

[rgooch]

We don't know what that one-liner is. Can you please post sample code which performs this conversion?

[hanwen]

pk, .. , err := ssh.ParsePublicKey( .. )

cert := pk.(*ssh.Certificate)

[rgooch]

Wow. Thank you for showing this. I'm happy to report that this works for us. I have to say, this is basically non-discoverable. I would suggest adding a note to the documentation for ssh.ParsePublicKey saying that - given the correct input - will return *ssh.Certificate as the concrete type.

[gopherbot]

Change https://golang.org/cl/88895 mentions this issue: ssh: clarify how to parse out Certificates