Enrollment Trait
API Service: EnrollmentApi
A service used to enroll a Smart Core node into a centrally managed installation. Establishes a trust relationship between the node serving this API (the target node) and the node calling it (the management node), using PKI.
Operates on a "Trust on First Use" security policy:
- When a target node is in enrollment mode (on first boot or after a DeleteEnrollment) it will accept incoming CreateEnrollment calls. The target node may accept enrollments from any management node, or optionally may accept only some requests (based on preconfigured policy). When in enrollment mode, the target node shall serve gRPC with a self-signed TLS certificate.
- When a target node is in operating mode, its management node may cancel its enrollment by calling DeleteEnrollment. The target node will then return to enrollment mode. The target node will not accept any CreateEnrollment calls while it is in operating mode.
- The certificate and roots associated with an enrollment can be updated via UpdateEnrollment. Only an enrolled node will respond successfully to an update. The node must only update the enrollment information if the certificate given is signed by the same signer as the current enrollment certificate. The node may reject the update if the client certificate isn't signed by one of the existing enrollment roots.
| Method | Request Type | Response Type | Description |
|---|---|---|---|
| GetEnrollment | GetEnrollmentRequest | Enrollment | |
| CreateEnrollment | CreateEnrollmentRequest | Enrollment | |
| UpdateEnrollment | UpdateEnrollmentRequest | Enrollment | |
| DeleteEnrollment | DeleteEnrollmentRequest | Enrollment | |
| TestEnrollment | TestEnrollmentRequest | TestEnrollmentResponse | TestEnrollment checks whether this node can communicate with the manager. If the node is not enrolled, returns a NotFound grpc error. A failed tests returns a successful grpc response with an error message. |
Enrollment
Enrollment is metadata associated with the enrollment of a target node with a management node.
The enrollment binds the target node to the management node's public key infrastructure. A given target node can have at most one Enrollment at a time, so an Enrollment does not need an identifier.
The Enrollment Connection is the gRPC connection from the management node to the target node, opened for the purpose of calling CreateEnrollment.
| Field Name | Type | Description |
|---|---|---|
| target_name | string | The Smart Core name that should be adopted by the target node as its root name when it accepts this enrollment. |
| target_address | string | The address that the management node will use to connect to the target node, in the form "host:port" |
| manager_name | string | The Smart Core root name of the node which will manage the target node |
| manager_address | string | The address where the management node's Smart Core gRPC server can be found, in the form "host:port". The host must either be a DNS name or an IP address. When the target node connects to this address using gRPC with TLS, the management node MUST use a certificate signed by one of the Certificate Authorities present in root_cas, and that certificate MUST contain the host as a Subject Alternative Name. This is so the target node can verify the identity of the management node. |
| certificate | bytes | An X.509 certificate chain issued by the management node to the target node, in DER-encoded ASN.1 in a PEM container. If more than one certificate is present, they should be concatenated. The certificate chain MUST be in leaf-first order; the leaf certificate is the certificate issued to the target node. The leaf certificate's public key MUST be the target node's public key. Each certificate in the chain MUST be signed by the next certificate in the chain. The final certificate in the chain MUST be signed by the one of the Certificate Authorities whose certificate is present in root_cas. The leaf certificate's Subject Common Name SHOULD be a human-readable name for the target node. The leaf certificate MUST contain target_name as a URI Subject Alternative Name in the form "smart-core:<target_name>" If the enrollment connection was opened by resolving a DNS name, then the leaf certificate MUST contain that DNS name as a Subject Alternative Name. If the enrollment connection was opened by directly connecting to an IP address, then the leaf certificate MUST contain that IP address as a Subject Alternative Name. |
| root_cas | bytes | One or more X.509 certificates, in DER-encoded ASN.1 in a PEM container. If more than one certificate is present, they should be concatenated. These are the Root Certificate Authorities for the enrollment. Each MUST be a CA certificate. The target node SHOULD use these certificate authorities whenever it communicates with another Smart Core node, to verify that the other node is also enrolled with the same manager. |
GetEnrollmentRequest
No fields defined.
CreateEnrollmentRequest
| Field Name | Type | Description |
|---|---|---|
| enrollment | Enrollment |
UpdateEnrollmentRequest
| Field Name | Type | Description |
|---|---|---|
| enrollment | Enrollment |
DeleteEnrollmentRequest
No fields defined.
TestEnrollmentRequest
No fields defined.
TestEnrollmentResponse
| Field Name | Type | Description |
|---|---|---|
| error | string | Error, if empty means success. If not empty, describes the error that occurred. |
| code | int32 | If the underlying error has a code, this is it. Typically a grpc status code. |