Documentation
¶
Overview ¶
Package machineenrollment enrolls a device as a machine principal using a device token or a fleet key. The server answers with an OAuth client_id bound to a newly generated RSA key, which authenticates with private_key_jwt client assertions.
Index ¶
- Constants
- Variables
- func ClientAssertion(key crypto.Signer, clientID, tokenURL string, now time.Time) (string, error)
- func EncodeKeyPEM(key crypto.Signer) ([]byte, error)
- func GenerateKey() (*rsa.PrivateKey, error)
- func ParseKeyPEM(data []byte) (crypto.Signer, error)
- func ReadFleetKeyFile(path string) (*ecdsa.PrivateKey, error)
- type Enrollment
- type EnrollmentError
- type Identifier
Constants ¶
const ( CodeMachineNotRegistered = "machine_not_registered" CodeIdentifiersAmbiguous = "identifiers_ambiguous" CodeMachineDeprovisioned = "machine_deprovisioned" CodeMachineEnrolled = "machine_enrolled" )
Codes the enrollment service sets on an enrollment error, for those a machine needs to tell apart from others with the same status.
const (
// ClientAssertionType is the client_assertion_type of a private_key_jwt client assertion.
ClientAssertionType = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
)
const (
// DeviceTokenPrefix starts every device token.
DeviceTokenPrefix = "sdt_"
)
const IdentifierTypeSerialNumber = "serial_number"
IdentifierTypeSerialNumber is the type of a hardware serial number, the only identifier the enrollment service knows.
Variables ¶
var ( // ErrMachineNotRegistered: no machine the fleet key allows has any of the identifiers. ErrMachineNotRegistered = &EnrollmentError{Code: CodeMachineNotRegistered} // ErrIdentifiersAmbiguous: the identifiers name more than one machine the fleet key allows. ErrIdentifiersAmbiguous = &EnrollmentError{Code: CodeIdentifiersAmbiguous} // ErrMachineDeprovisioned: the machine is retired and can't enroll again. ErrMachineDeprovisioned = &EnrollmentError{Code: CodeMachineDeprovisioned} // ErrMachineEnrolled: a fleet key can't enroll a machine that has an active client. An admin has to // issue a device token to re-enroll it. ErrMachineEnrolled = &EnrollmentError{Code: CodeMachineEnrolled} )
Errors for the typed enrollment errors, for use with errors.Is.
var ErrMalformedDeviceToken = errors.New("the device token is malformed: device tokens start with " + DeviceTokenPrefix)
ErrMalformedDeviceToken is returned for a device token that can't be one, before it is sent anywhere.
var ErrNoIdentifiers = errors.New("a fleet key enrollment needs between 1 and 32 machine identifiers, each of 1 to 256 characters")
ErrNoIdentifiers is returned when a fleet key enrollment has no valid identifier to name the machine with.
var ErrOutcomeUnknown = errors.New("the outcome of the enrollment is unknown: the service may have enrolled the machine, a single-use device token (if one was used) may be spent, and an admin can check the machine's client and revoke it")
ErrOutcomeUnknown is returned when the enrollment request may have reached the service but its outcome could not be read: no response arrived, the response was a 2xx or 5xx whose body could not be read or used, or a 5xx that may follow an accepted enrollment. The service may have enrolled the machine.
var ErrRetiredJoinKey = errors.New("join keys (" + retiredJoinKeyPrefix + "...) are no longer supported: ask an admin for a device token (" + DeviceTokenPrefix + "...) for this machine, or use a fleet key")
ErrRetiredJoinKey is returned for a retired join key (sjt_), which the enrollment service no longer accepts.
Functions ¶
func ClientAssertion ¶
ClientAssertion returns a private_key_jwt client assertion (RFC 7523) for clientID, signed by key, for a token request to tokenURL. Each assertion has a unique jti, so the authorization server accepts it once.
func EncodeKeyPEM ¶
EncodeKeyPEM encodes key as a PKCS8 PEM.
func GenerateKey ¶
func GenerateKey() (*rsa.PrivateKey, error)
GenerateKey generates a new machine client key: an RSA key, for RS256 signatures, which is the algorithm the enrollment service and the OAuth token server accept.
func ParseKeyPEM ¶
ParseKeyPEM parses a PKCS8 PEM key written by EncodeKeyPEM: an RSA key, or a P-256 ECDSA key.
func ReadFleetKeyFile ¶
func ReadFleetKeyFile(path string) (*ecdsa.PrivateKey, error)
ReadFleetKeyFile reads a fleet key: the private half of the P-256 keypair an admin registered, as a PEM file with a PKCS8 ("PRIVATE KEY") or SEC1 ("EC PRIVATE KEY") key. The file must be a regular file.
Types ¶
type Enrollment ¶
type Enrollment struct {
MachineID string
ClientID string
KeyID string
// Key is the machine client's private key, which the caller stores. It is the only credential
// the machine needs from now on.
Key *rsa.PrivateKey
}
Enrollment is the result of enrolling this device.
func EnrollWithDeviceToken ¶
func EnrollWithDeviceToken(ctx context.Context, httpClient *http.Client, apiURL, deviceToken string, now time.Time) (Enrollment, error)
EnrollWithDeviceToken enrolls this machine with the single-use device token an admin issued for it, exchanging it for an OAuth client bound to a newly generated machine client key. It needs no device identity, so it works on any platform, and it enrolls the machine even if it is enrolled already. httpClient must not add authentication.
func EnrollWithFleetKey ¶
func EnrollWithFleetKey(ctx context.Context, httpClient *http.Client, apiURL string, fleetKey *ecdsa.PrivateKey, identifiers []Identifier, now time.Time) (Enrollment, error)
EnrollWithFleetKey enrolls this machine with a fleet key, the P-256 key an admin registered and allowed for the machines of a fleet. The machine names itself by identifiers, which must be the ones an admin registered it with, and signs them with the fleet key. Like EnrollWithDeviceToken, it exchanges them for an OAuth client bound to a newly generated machine client key, but it enrolls only a machine that has no active client. httpClient must not add authentication.
type EnrollmentError ¶
type EnrollmentError struct {
// Status is the HTTP status of the response.
Status int
// Code tells apart errors with the same status, or is empty. See the Code constants.
Code string
Detail string
// Identifiers are those the service looked up, for CodeMachineNotRegistered.
Identifiers []Identifier
// contains filtered or unexported fields
}
EnrollmentError is an error response of the enrollment service. Match one of the typed errors, such as ErrMachineEnrolled, with errors.Is, or read the status and code with errors.As.
func (*EnrollmentError) Error ¶
func (e *EnrollmentError) Error() string
Error describes the response, and what to do about it if that is known.
func (*EnrollmentError) Is ¶
func (e *EnrollmentError) Is(target error) bool
Is matches the typed errors by code.
type Identifier ¶
Identifier names a machine, as an admin registered it.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package enrollmenttest provides a test double for the enrollment service: a fake API server that implements the enrollment (by device token and by fleet key) and token endpoints as the service's enrollment spec defines them, and independently verifies everything the client signs.
|
Package enrollmenttest provides a test double for the enrollment service: a fake API server that implements the enrollment (by device token and by fleet key) and token endpoints as the service's enrollment spec defines them, and independently verifies everything the client signs. |