github.com/cactusblossom/fabric-ca@v0.0.0-20200611062428-0082fc643826/api/client.go (about) 1 /* 2 Copyright IBM Corp. All Rights Reserved. 3 4 SPDX-License-Identifier: Apache-2.0 5 */ 6 7 package api 8 9 import ( 10 "math/big" 11 "time" 12 13 "github.com/cloudflare/cfssl/csr" 14 "github.com/hyperledger/fabric-ca/util" 15 ) 16 17 // RegistrationRequest for a new identity 18 type RegistrationRequest struct { 19 // Name is the unique name of the identity 20 Name string `json:"id" help:"Unique name of the identity"` 21 // Type of identity being registered (e.g. "peer, app, user") 22 Type string `json:"type" def:"client" help:"Type of identity being registered (e.g. 'peer, app, user')"` 23 // Secret is an optional password. If not specified, 24 // a random secret is generated. In both cases, the secret 25 // is returned in the RegistrationResponse. 26 Secret string `json:"secret,omitempty" mask:"password" help:"The enrollment secret for the identity being registered"` 27 // MaxEnrollments is the maximum number of times the secret can 28 // be reused to enroll. 29 MaxEnrollments int `json:"max_enrollments,omitempty" help:"The maximum number of times the secret can be reused to enroll (default CA's Max Enrollment)"` 30 // is returned in the response. 31 // The identity's affiliation. 32 // For example, an affiliation of "org1.department1" associates the identity with "department1" in "org1". 33 Affiliation string `json:"affiliation" help:"The identity's affiliation"` 34 // Attributes associated with this identity 35 Attributes []Attribute `json:"attrs,omitempty"` 36 // CAName is the name of the CA to connect to 37 CAName string `json:"caname,omitempty" skip:"true"` 38 } 39 40 func (rr *RegistrationRequest) String() string { 41 return util.StructToString(rr) 42 } 43 44 // RegistrationResponse is a registration response 45 type RegistrationResponse struct { 46 // The secret returned from a successful registration response 47 Secret string `json:"secret"` 48 } 49 50 // EnrollmentRequest is a request to enroll an identity 51 type EnrollmentRequest struct { 52 // The identity name to enroll 53 Name string `json:"name" skip:"true"` 54 // The secret returned via Register 55 Secret string `json:"secret,omitempty" skip:"true" mask:"password"` 56 // CAName is the name of the CA to connect to 57 CAName string `json:"caname,omitempty" skip:"true"` 58 // AttrReqs are requests for attributes to add to the certificate. 59 // Each attribute is added only if the requestor owns the attribute. 60 AttrReqs []*AttributeRequest `json:"attr_reqs,omitempty"` 61 // Profile is the name of the signing profile to use in issuing the X509 certificate 62 Profile string `json:"profile,omitempty" help:"Name of the signing profile to use in issuing the certificate"` 63 // Label is the label to use in HSM operations 64 Label string `json:"label,omitempty" help:"Label to use in HSM operations"` 65 // CSR is Certificate Signing Request info 66 CSR *CSRInfo `json:"csr,omitempty" skip:"true"` // Skipping this because we pull the CSR from the CSR flags 67 // The type of the enrollment request: x509 or idemix 68 // The default is a request for an X509 enrollment certificate 69 Type string `def:"x509" help:"The type of enrollment request: 'x509' or 'idemix'"` 70 } 71 72 func (er EnrollmentRequest) String() string { 73 return util.StructToString(&er) 74 } 75 76 // ReenrollmentRequest is a request to reenroll an identity. 77 // This is useful to renew a certificate before it has expired. 78 type ReenrollmentRequest struct { 79 // Profile is the name of the signing profile to use in issuing the certificate 80 Profile string `json:"profile,omitempty"` 81 // Label is the label to use in HSM operations 82 Label string `json:"label,omitempty"` 83 // CSR is Certificate Signing Request info 84 CSR *CSRInfo `json:"csr,omitempty"` 85 // CAName is the name of the CA to connect to 86 CAName string `json:"caname,omitempty" skip:"true"` 87 // AttrReqs are requests for attributes to add to the certificate. 88 // Each attribute is added only if the requestor owns the attribute. 89 AttrReqs []*AttributeRequest `json:"attr_reqs,omitempty"` 90 } 91 92 // RevocationRequest is a revocation request for a single certificate or all certificates 93 // associated with an identity. 94 // To revoke a single certificate, both the Serial and AKI fields must be set; 95 // otherwise, to revoke all certificates and the identity associated with an enrollment ID, 96 // the Name field must be set to an existing enrollment ID. 97 // A RevocationRequest can only be performed by a user with the "hf.Revoker" attribute. 98 type RevocationRequest struct { 99 // Name of the identity whose certificates should be revoked 100 // If this field is omitted, then Serial and AKI must be specified. 101 Name string `json:"id,omitempty" opt:"e" help:"Identity whose certificates should be revoked"` 102 // Serial number of the certificate to be revoked 103 // If this is omitted, then Name must be specified 104 Serial string `json:"serial,omitempty" opt:"s" help:"Serial number of the certificate to be revoked"` 105 // AKI (Authority Key Identifier) of the certificate to be revoked 106 AKI string `json:"aki,omitempty" opt:"a" help:"AKI (Authority Key Identifier) of the certificate to be revoked"` 107 // Reason is the reason for revocation. See https://godoc.org/golang.org/x/crypto/ocsp for 108 // valid values. The default value is 0 (ocsp.Unspecified). 109 Reason string `json:"reason,omitempty" opt:"r" help:"Reason for revocation"` 110 // CAName is the name of the CA to connect to 111 CAName string `json:"caname,omitempty" skip:"true"` 112 // GenCRL specifies whether to generate a CRL 113 GenCRL bool `def:"false" skip:"true" json:"gencrl,omitempty"` 114 } 115 116 // RevocationResponse represents response from the server for a revocation request 117 type RevocationResponse struct { 118 // RevokedCerts is an array of certificates that were revoked 119 RevokedCerts []RevokedCert 120 // CRL is PEM-encoded certificate revocation list (CRL) that contains all unexpired revoked certificates 121 CRL []byte 122 } 123 124 // RevokedCert represents a revoked certificate 125 type RevokedCert struct { 126 // Serial number of the revoked certificate 127 Serial string 128 // AKI of the revoked certificate 129 AKI string 130 } 131 132 // GetTCertBatchRequest is input provided to identity.GetTCertBatch 133 type GetTCertBatchRequest struct { 134 // Number of TCerts in the batch. 135 Count int `json:"count"` 136 // The attribute names whose names and values are to be sealed in the issued TCerts. 137 AttrNames []string `json:"attr_names,omitempty"` 138 // EncryptAttrs denotes whether to encrypt attribute values or not. 139 // When set to true, each issued TCert in the batch will contain encrypted attribute values. 140 EncryptAttrs bool `json:"encrypt_attrs,omitempty"` 141 // Certificate Validity Period. If specified, the value used 142 // is the minimum of this value and the configured validity period 143 // of the TCert manager. 144 ValidityPeriod time.Duration `json:"validity_period,omitempty"` 145 // The pre-key to be used for key derivation. 146 PreKey string `json:"prekey"` 147 // DisableKeyDerivation if true disables key derivation so that a TCert is not 148 // cryptographically related to an ECert. This may be necessary when using an 149 // HSM which does not support the TCert's key derivation function. 150 DisableKeyDerivation bool `json:"disable_kdf,omitempty"` 151 // CAName is the name of the CA to connect to 152 CAName string `json:"caname,omitempty" skip:"true"` 153 } 154 155 // GetTCertBatchResponse is the return value of identity.GetTCertBatch 156 type GetTCertBatchResponse struct { 157 ID *big.Int `json:"id"` 158 TS time.Time `json:"ts"` 159 Key []byte `json:"key"` 160 TCerts []TCert `json:"tcerts"` 161 } 162 163 // TCert encapsulates a signed transaction certificate and optionally a map of keys 164 type TCert struct { 165 Cert []byte `json:"cert"` 166 Keys map[string][]byte `json:"keys,omitempty"` //base64 encoded string as value 167 } 168 169 // GetCAInfoRequest is request to get generic CA information 170 type GetCAInfoRequest struct { 171 CAName string `json:"caname,omitempty" skip:"true"` 172 } 173 174 // GenCRLRequest represents a request to get CRL for the specified certificate authority 175 type GenCRLRequest struct { 176 CAName string `json:"caname,omitempty" skip:"true"` 177 RevokedAfter time.Time `json:"revokedafter,omitempty"` 178 RevokedBefore time.Time `json:"revokedbefore,omitempty"` 179 ExpireAfter time.Time `json:"expireafter,omitempty"` 180 ExpireBefore time.Time `json:"expirebefore,omitempty"` 181 } 182 183 // GenCRLResponse represents a response to get CRL 184 type GenCRLResponse struct { 185 // CRL is PEM-encoded certificate revocation list (CRL) that contains requested unexpired revoked certificates 186 CRL []byte 187 } 188 189 // GetCRIRequest is a request to send to server to get Idemix credential revocation information 190 type GetCRIRequest struct { 191 CAName string `json:"caname,omitempty" skip:"true"` 192 } 193 194 // GetCRIResponse is the response from the server for get CRI request 195 type GetCRIResponse struct { 196 // CRI is base64 encoded proto bytes of idemix.CredentialRevocationInformation 197 CRI string 198 } 199 200 // AddIdentityRequest represents the request to add a new identity to the 201 // fabric-ca-server 202 type AddIdentityRequest struct { 203 ID string `json:"id" skip:"true"` 204 Type string `json:"type" def:"user" help:"Type of identity being registered (e.g. 'peer, app, user')"` 205 Affiliation string `json:"affiliation" help:"The identity's affiliation"` 206 Attributes []Attribute `json:"attrs" mapstructure:"attrs" ` 207 MaxEnrollments int `json:"max_enrollments" mapstructure:"max_enrollments" help:"The maximum number of times the secret can be reused to enroll (default CA's Max Enrollment)"` 208 // Secret is an optional password. If not specified, 209 // a random secret is generated. In both cases, the secret 210 // is returned in the RegistrationResponse. 211 Secret string `json:"secret,omitempty" mask:"password" help:"The enrollment secret for the identity being added"` 212 CAName string `json:"caname,omitempty" skip:"true"` 213 } 214 215 // ModifyIdentityRequest represents the request to modify an existing identity on the 216 // fabric-ca-server 217 type ModifyIdentityRequest struct { 218 ID string `skip:"true"` 219 Type string `json:"type" help:"Type of identity being registered (e.g. 'peer, app, user')"` 220 Affiliation string `json:"affiliation" help:"The identity's affiliation"` 221 Attributes []Attribute `mapstructure:"attrs" json:"attrs"` 222 MaxEnrollments int `mapstructure:"max_enrollments" json:"max_enrollments" help:"The maximum number of times the secret can be reused to enroll"` 223 Secret string `json:"secret,omitempty" mask:"password" help:"The enrollment secret for the identity"` 224 CAName string `json:"caname,omitempty" skip:"true"` 225 } 226 227 // RemoveIdentityRequest represents the request to remove an existing identity from the 228 // fabric-ca-server 229 type RemoveIdentityRequest struct { 230 ID string `skip:"true"` 231 Force bool `json:"force"` 232 CAName string `json:"caname,omitempty" skip:"true"` 233 } 234 235 // GetIDResponse is the response from the GetIdentity call 236 type GetIDResponse struct { 237 ID string `json:"id" skip:"true"` 238 Type string `json:"type" def:"user"` 239 Affiliation string `json:"affiliation"` 240 Attributes []Attribute `json:"attrs" mapstructure:"attrs" ` 241 MaxEnrollments int `json:"max_enrollments" mapstructure:"max_enrollments"` 242 CAName string `json:"caname,omitempty"` 243 } 244 245 // GetAllIDsResponse is the response from the GetAllIdentities call 246 type GetAllIDsResponse struct { 247 Identities []IdentityInfo `json:"identities"` 248 CAName string `json:"caname,omitempty"` 249 } 250 251 // IdentityResponse is the response from the any add/modify/remove identity call 252 type IdentityResponse struct { 253 ID string `json:"id" skip:"true"` 254 Type string `json:"type,omitempty"` 255 Affiliation string `json:"affiliation"` 256 Attributes []Attribute `json:"attrs,omitempty" mapstructure:"attrs"` 257 MaxEnrollments int `json:"max_enrollments,omitempty" mapstructure:"max_enrollments"` 258 Secret string `json:"secret,omitempty"` 259 CAName string `json:"caname,omitempty"` 260 } 261 262 // IdentityInfo contains information about an identity 263 type IdentityInfo struct { 264 ID string `json:"id"` 265 Type string `json:"type"` 266 Affiliation string `json:"affiliation"` 267 Attributes []Attribute `json:"attrs" mapstructure:"attrs"` 268 MaxEnrollments int `json:"max_enrollments" mapstructure:"max_enrollments"` 269 } 270 271 // AddAffiliationRequest represents the request to add a new affiliation to the 272 // fabric-ca-server 273 type AddAffiliationRequest struct { 274 Name string `json:"name"` 275 Force bool `json:"force"` 276 CAName string `json:"caname,omitempty"` 277 } 278 279 // ModifyAffiliationRequest represents the request to modify an existing affiliation on the 280 // fabric-ca-server 281 type ModifyAffiliationRequest struct { 282 Name string 283 NewName string `json:"name"` 284 Force bool `json:"force"` 285 CAName string `json:"caname,omitempty"` 286 } 287 288 // RemoveAffiliationRequest represents the request to remove an existing affiliation from the 289 // fabric-ca-server 290 type RemoveAffiliationRequest struct { 291 Name string 292 Force bool `json:"force"` 293 CAName string `json:"caname,omitempty"` 294 } 295 296 // AffiliationResponse contains the response for get, add, modify, and remove an affiliation 297 type AffiliationResponse struct { 298 AffiliationInfo `mapstructure:",squash"` 299 CAName string `json:"caname,omitempty"` 300 } 301 302 // AffiliationInfo contains the affiliation name, child affiliation info, and identities 303 // associated with this affiliation. 304 type AffiliationInfo struct { 305 Name string `json:"name"` 306 Affiliations []AffiliationInfo `json:"affiliations,omitempty"` 307 Identities []IdentityInfo `json:"identities,omitempty"` 308 } 309 310 // CSRInfo is Certificate Signing Request (CSR) Information 311 type CSRInfo struct { 312 CN string `json:"CN"` 313 Names []csr.Name `json:"names,omitempty"` 314 Hosts []string `json:"hosts,omitempty"` 315 KeyRequest *BasicKeyRequest `json:"key,omitempty"` 316 CA *csr.CAConfig `json:"ca,omitempty" hide:"true"` 317 SerialNumber string `json:"serial_number,omitempty"` 318 } 319 320 // GetCertificatesRequest represents the request to get certificates from the server 321 // per the enrollment ID and/or AKI and Serial. If neither ID or AKI/Serial are 322 // provided all certificates are returned which are in or under the caller's affiliation. 323 // By default all certificates are returned. However, only revoked and/or expired 324 // certificates can be requested by providing a time range. 325 type GetCertificatesRequest struct { 326 ID string `skip:"true"` // Get certificates for this enrollment ID 327 AKI string `help:"Get certificates for this AKI"` // Get certificate that matches this AKI 328 Serial string `help:"Get certificates for this serial number"` // Get certificate that matches this serial 329 Revoked TimeRange `skip:"true"` // Get certificates which were revoked between the specified time range 330 Expired TimeRange `skip:"true"` // Get certificates which expire between the specified time range 331 NotExpired bool `help:"Don't return expired certificates"` // Don't return expired certificates 332 NotRevoked bool `help:"Don't return revoked certificates"` // Don't return revoked certificates 333 CAName string `skip:"true"` // Name of CA to send request to within the server 334 } 335 336 // CertificateResponse contains the response from Get or Delete certificate request. 337 type CertificateResponse struct { 338 Certs []string `json:"certs"` 339 } 340 341 // TimeRange specifies a range of time 342 type TimeRange struct { 343 StartTime string 344 EndTime string 345 } 346 347 // BasicKeyRequest encapsulates size and algorithm for the key to be generated 348 type BasicKeyRequest struct { 349 Algo string `json:"algo" yaml:"algo" help:"Specify key algorithm"` 350 Size int `json:"size" yaml:"size" help:"Specify key size"` 351 } 352 353 // Attribute is a name and value pair 354 type Attribute struct { 355 Name string `json:"name"` 356 Value string `json:"value"` 357 ECert bool `json:"ecert,omitempty"` 358 } 359 360 // GetName returns the name of the attribute 361 func (a *Attribute) GetName() string { 362 return a.Name 363 } 364 365 // GetValue returns the value of the attribute 366 func (a *Attribute) GetValue() string { 367 return a.Value 368 } 369 370 // AttributeRequest is a request for an attribute. 371 // This implements the certmgr/AttributeRequest interface. 372 type AttributeRequest struct { 373 Name string `json:"name"` 374 Optional bool `json:"optional,omitempty"` 375 } 376 377 // GetName returns the name of an attribute being requested 378 func (ar *AttributeRequest) GetName() string { 379 return ar.Name 380 } 381 382 // IsRequired returns true if the attribute being requested is required 383 func (ar *AttributeRequest) IsRequired() bool { 384 return !ar.Optional 385 } 386 387 // NewBasicKeyRequest returns the BasicKeyRequest object that is constructed 388 // from the object returned by the csr.NewBasicKeyRequest() function 389 func NewBasicKeyRequest() *BasicKeyRequest { 390 bkr := csr.NewBasicKeyRequest() 391 return &BasicKeyRequest{Algo: bkr.A, Size: bkr.S} 392 }