pseries/plpks: fix kernel-doc comment inconsistencies

+318 -87

2 changed files

expand all

arch

powerpc

include

asm

plpks.h

platforms

pseries

plpks.c

-77

arch/powerpc/include/asm/plpks.h

··· 67 67 struct plpks_var_name varlist[]; 68 68 }; 69 69 70 - /** 71 - * Updates the authenticated variable. It expects NULL as the component. 72 - */ 73 70 int plpks_signed_update_var(struct plpks_var *var, u64 flags); 74 71 75 - /** 76 - * Writes the specified var and its data to PKS. 77 - * Any caller of PKS driver should present a valid component type for 78 - * their variable. 79 - */ 80 72 int plpks_write_var(struct plpks_var var); 81 73 82 - /** 83 - * Removes the specified var and its data from PKS. 84 - */ 85 74 int plpks_remove_var(char *component, u8 varos, 86 75 struct plpks_var_name vname); 87 76 88 - /** 89 - * Returns the data for the specified os variable. 90 - * 91 - * Caller must allocate a buffer in var->data with length in var->datalen. 92 - * If no buffer is provided, var->datalen will be populated with the object's 93 - * size. 94 - */ 95 77 int plpks_read_os_var(struct plpks_var *var); 96 78 97 - /** 98 - * Returns the data for the specified firmware variable. 99 - * 100 - * Caller must allocate a buffer in var->data with length in var->datalen. 101 - * If no buffer is provided, var->datalen will be populated with the object's 102 - * size. 103 - */ 104 79 int plpks_read_fw_var(struct plpks_var *var); 105 80 106 - /** 107 - * Returns the data for the specified bootloader variable. 108 - * 109 - * Caller must allocate a buffer in var->data with length in var->datalen. 110 - * If no buffer is provided, var->datalen will be populated with the object's 111 - * size. 112 - */ 113 81 int plpks_read_bootloader_var(struct plpks_var *var); 114 82 115 - /** 116 - * Returns if PKS is available on this LPAR. 117 - */ 118 83 bool plpks_is_available(void); 119 84 120 - /** 121 - * Returns version of the Platform KeyStore. 122 - */ 123 85 u8 plpks_get_version(void); 124 86 125 - /** 126 - * Returns hypervisor storage overhead per object, not including the size of 127 - * the object or label. Only valid for config version >= 2 128 - */ 129 87 u16 plpks_get_objoverhead(void); 130 88 131 - /** 132 - * Returns maximum password size. Must be >= 32 bytes 133 - */ 134 89 u16 plpks_get_maxpwsize(void); 135 90 136 - /** 137 - * Returns maximum object size supported by Platform KeyStore. 138 - */ 139 91 u16 plpks_get_maxobjectsize(void); 140 92 141 - /** 142 - * Returns maximum object label size supported by Platform KeyStore. 143 - */ 144 93 u16 plpks_get_maxobjectlabelsize(void); 145 94 146 - /** 147 - * Returns total size of the configured Platform KeyStore. 148 - */ 149 95 u32 plpks_get_totalsize(void); 150 96 151 - /** 152 - * Returns used space from the total size of the Platform KeyStore. 153 - */ 154 97 u32 plpks_get_usedspace(void); 155 98 156 - /** 157 - * Returns bitmask of policies supported by the hypervisor. 158 - */ 159 99 u32 plpks_get_supportedpolicies(void); 160 100 161 - /** 162 - * Returns maximum byte size of a single object supported by the hypervisor. 163 - * Only valid for config version >= 3 164 - */ 165 101 u32 plpks_get_maxlargeobjectsize(void); 166 102 167 - /** 168 - * Returns bitmask of signature algorithms supported for signed updates. 169 - * Only valid for config version >= 3 170 - */ 171 103 u64 plpks_get_signedupdatealgorithms(void); 172 104 173 - /** 174 - * Returns the length of the PLPKS password in bytes. 175 - */ 176 105 u16 plpks_get_passwordlen(void); 177 106 178 - /** 179 - * Called in early init to retrieve and clear the PLPKS password from the DT. 180 - */ 181 107 void plpks_early_init_devtree(void); 182 108 183 - /** 184 - * Populates the FDT with the PLPKS password to prepare for kexec. 185 - */ 186 109 int plpks_populate_fdt(void *fdt); 187 110 #else // CONFIG_PSERIES_PLPKS 188 111 static inline bool plpks_is_available(void) { return false; }

+318 -10

arch/powerpc/platforms/pseries/plpks.c

··· 312 312 return rc; 313 313 } 314 314 315 + /** 316 + * plpks_get_version() - Get the version of the PLPKS config structure. 317 + * 318 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 319 + * reads the PLPKS config structure version and saves it in a file local static 320 + * version variable. 321 + * 322 + * Returns: On success the saved PLPKS config structure version is returned, 0 323 + * if not. 324 + */ 315 325 u8 plpks_get_version(void) 316 326 { 317 327 return version; 318 328 } 319 329 330 + /** 331 + * plpks_get_objoverhead() - Get the hypervisor storage overhead per object. 332 + * 333 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 334 + * reads the per object hypervisor storage overhead in bytes into the local 335 + * static objoverhead variable, excluding the size of the object or the label. 336 + * This value can be treated as valid only when the PLPKS config structure 337 + * version >= 2. 338 + * 339 + * Returns: If PLPKS config structure version >= 2 then the storage overhead is 340 + * returned, 0 otherwise. 341 + */ 320 342 u16 plpks_get_objoverhead(void) 321 343 { 322 344 return objoverhead; 323 345 } 324 346 347 + /** 348 + * plpks_get_maxpwsize() - Get the maximum password size. 349 + * 350 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 351 + * reads the maximum password size and checks if it is 32 bytes at the least 352 + * before storing it in the local static maxpwsize variable. 353 + * 354 + * Returns: On success the maximum password size is returned, 0 if not. 355 + */ 325 356 u16 plpks_get_maxpwsize(void) 326 357 { 327 358 return maxpwsize; 328 359 } 329 360 361 + /** 362 + * plpks_get_maxobjectsize() - Get the maximum object size supported by the 363 + * PLPKS. 364 + * 365 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 366 + * reads the maximum object size into the file local static maxobjsize variable. 367 + * 368 + * Returns: On success the maximum object size is returned, 0 if not. 369 + */ 330 370 u16 plpks_get_maxobjectsize(void) 331 371 { 332 372 return maxobjsize; 333 373 } 334 374 375 + /** 376 + * plpks_get_maxobjectlabelsize() - Get the maximum object label size supported 377 + * by the PLPKS. 378 + * 379 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 380 + * reads the maximum object label size into the local static maxobjlabelsize 381 + * variable. 382 + * 383 + * Returns: On success the maximum object label size is returned, 0 if not. 384 + */ 335 385 u16 plpks_get_maxobjectlabelsize(void) 336 386 { 337 387 return maxobjlabelsize; 338 388 } 339 389 390 + /** 391 + * plpks_get_totalsize() - Get the total size of the PLPKS that is configured. 392 + * 393 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 394 + * reads the total size of the PLPKS that is configured for the LPAR into the 395 + * file local static totalsize variable. 396 + * 397 + * Returns: On success the total size of the PLPKS configured is returned, 0 if 398 + * not. 399 + */ 340 400 u32 plpks_get_totalsize(void) 341 401 { 342 402 return totalsize; 343 403 } 344 404 405 + /** 406 + * plpks_get_usedspace() - Get the used space from the total size of the PLPKS. 407 + * 408 + * Invoke the H_PKS_GET_CONFIG HCALL to refresh the latest value for the used 409 + * space as this keeps changing with the creation and removal of objects in the 410 + * PLPKS. 411 + * 412 + * Returns: On success the used space is returned, 0 if not. 413 + */ 345 414 u32 plpks_get_usedspace(void) 346 415 { 347 - // Unlike other config values, usedspace regularly changes as objects 348 - // are updated, so we need to refresh. 349 416 int rc = _plpks_get_config(); 350 417 if (rc) { 351 418 pr_err("Couldn't get config, rc: %d\n", rc); ··· 421 354 return usedspace; 422 355 } 423 356 357 + /** 358 + * plpks_get_supportedpolicies() - Get a bitmask of the policies supported by 359 + * the hypervisor. 360 + * 361 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 362 + * reads a bitmask of the policies supported by the hypervisor into the file 363 + * local static supportedpolicies variable. 364 + * 365 + * Returns: On success the bitmask of the policies supported by the hypervisor 366 + * are returned, 0 if not. 367 + */ 424 368 u32 plpks_get_supportedpolicies(void) 425 369 { 426 370 return supportedpolicies; 427 371 } 428 372 373 + /** 374 + * plpks_get_maxlargeobjectsize() - Get the maximum object size supported for 375 + * PLPKS config structure version >= 3 376 + * 377 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 378 + * reads the maximum object size into the local static maxlargeobjectsize 379 + * variable for PLPKS config structure version >= 3. This was introduced 380 + * starting with PLPKS config structure version 3 to allow for objects of 381 + * size >= 64K. 382 + * 383 + * Returns: If PLPKS config structure version >= 3 then the new maximum object 384 + * size is returned, 0 if not. 385 + */ 429 386 u32 plpks_get_maxlargeobjectsize(void) 430 387 { 431 388 return maxlargeobjectsize; 432 389 } 433 390 391 + /** 392 + * plpks_get_signedupdatealgorithms() - Get a bitmask of the signature 393 + * algorithms supported for signed updates. 394 + * 395 + * Successful execution of the H_PKS_GET_CONFIG HCALL during initialization 396 + * reads a bitmask of the signature algorithms supported for signed updates into 397 + * the file local static signedupdatealgorithms variable. This is valid only 398 + * when the PLPKS config structure version >= 3. 399 + * 400 + * Returns: On success the bitmask of the signature algorithms supported for 401 + * signed updates is returned, 0 if not. 402 + */ 434 403 u64 plpks_get_signedupdatealgorithms(void) 435 404 { 436 405 return signedupdatealgorithms; 437 406 } 438 407 408 + /** 409 + * plpks_get_passwordlen() - Get the length of the PLPKS password in bytes. 410 + * 411 + * The H_PKS_GEN_PASSWORD HCALL makes the hypervisor generate a random password 412 + * for the specified consumer, apply that password to the PLPKS and return it to 413 + * the caller. In this process, the password length for the OS consumer is 414 + * stored in the local static ospasswordlength variable. 415 + * 416 + * Returns: On success the password length for the OS consumer in bytes is 417 + * returned, 0 if not. 418 + */ 439 419 u16 plpks_get_passwordlen(void) 440 420 { 441 421 return ospasswordlength; 442 422 } 443 423 424 + /** 425 + * plpks_is_available() - Get the PLPKS availability status for the LPAR. 426 + * 427 + * The availability of PLPKS is inferred based upon the successful execution of 428 + * the H_PKS_GET_CONFIG HCALL provided the firmware supports this feature. The 429 + * H_PKS_GET_CONFIG HCALL reads the configuration and status information related 430 + * to the PLPKS. The configuration structure provides a version number to inform 431 + * the caller of the supported features. 432 + * 433 + * Returns: true is returned if PLPKS is available, false if not. 434 + */ 444 435 bool plpks_is_available(void) 445 436 { 446 437 int rc; ··· 550 425 return pseries_status_to_err(rc); 551 426 } 552 427 428 + /** 429 + * plpks_signed_update_var() - Update the specified authenticated variable. 430 + * @var: authenticated variable to be updated 431 + * @flags: signed update request operation flags 432 + * 433 + * The H_PKS_SIGNED_UPDATE HCALL performs a signed update to an object in the 434 + * PLPKS. The object must have the signed update policy flag set. 435 + * 436 + * Possible reasons for the returned errno values: 437 + * 438 + * -ENXIO if PLPKS is not supported 439 + * -EIO if PLPKS access is blocked due to the LPAR's state 440 + * if PLPKS modification is blocked due to the LPAR's state 441 + * if an error occurred while processing the request 442 + * -EINVAL if invalid authorization parameter 443 + * if invalid object label parameter 444 + * if invalid object label len parameter 445 + * if invalid or unsupported policy declaration 446 + * if invalid signed update flags 447 + * if invalid input data parameter 448 + * if invalid input data len parameter 449 + * if invalid continue token parameter 450 + * -EPERM if access is denied 451 + * -ENOMEM if there is inadequate memory to perform the operation 452 + * -EBUSY if unable to handle the request or long running operation 453 + * initiated, retry later 454 + * 455 + * Returns: On success 0 is returned, a negative errno if not. 456 + */ 553 457 int plpks_signed_update_var(struct plpks_var *var, u64 flags) 554 458 { 555 459 unsigned long retbuf[PLPAR_HCALL9_BUFSIZE] = {0}; ··· 635 481 return rc; 636 482 } 637 483 484 + /** 485 + * plpks_write_var() - Write the specified variable and its data to PLPKS. 486 + * @var: variable to be written into the PLPKS 487 + * 488 + * The H_PKS_WRITE_OBJECT HCALL writes an object into the PLPKS. The caller must 489 + * provide a valid component type for the variable, and the signed update policy 490 + * flag must not be set. 491 + * 492 + * Possible reasons for the returned errno values: 493 + * 494 + * -ENXIO if PLPKS is not supported 495 + * -EIO if PLPKS access is blocked due to the LPAR's state 496 + * if PLPKS modification is blocked due to the LPAR's state 497 + * if an error occurred while processing the request 498 + * -EINVAL if invalid authorization parameter 499 + * if invalid object label parameter 500 + * if invalid object label len parameter 501 + * if invalid or unsupported policy declaration 502 + * if invalid input data parameter 503 + * if invalid input data len parameter 504 + * -EPERM if access is denied 505 + * -ENOMEM if unable to store the requested object in the space available 506 + * -EBUSY if unable to handle the request 507 + * -EEXIST if the object label already exists 508 + * 509 + * Returns: On success 0 is returned, a negative errno if not. 510 + */ 638 511 int plpks_write_var(struct plpks_var var) 639 512 { 640 513 unsigned long retbuf[PLPAR_HCALL_BUFSIZE] = { 0 }; ··· 701 520 return rc; 702 521 } 703 522 523 + /** 524 + * plpks_remove_var() - Remove the specified variable and its data from PLPKS. 525 + * @component: metadata prefix in the object label metadata structure 526 + * @varos: metadata OS flags in the object label metadata structure 527 + * @vname: object label for the object that needs to be removed 528 + * 529 + * The H_PKS_REMOVE_OBJECT HCALL removes an object from the PLPKS. The removal 530 + * is independent of the policy bits that are set. 531 + * 532 + * Possible reasons for the returned errno values: 533 + * 534 + * -ENXIO if PLPKS is not supported 535 + * -EIO if PLPKS access is blocked due to the LPAR's state 536 + * if PLPKS modification is blocked due to the LPAR's state 537 + * if an error occurred while processing the request 538 + * -EINVAL if invalid authorization parameter 539 + * if invalid object label parameter 540 + * if invalid object label len parameter 541 + * -EPERM if access is denied 542 + * -ENOENT if the requested object was not found 543 + * -EBUSY if unable to handle the request 544 + * 545 + * Returns: On success 0 is returned, a negative errno if not. 546 + */ 704 547 int plpks_remove_var(char *component, u8 varos, struct plpks_var_name vname) 705 548 { 706 549 unsigned long retbuf[PLPAR_HCALL_BUFSIZE] = { 0 }; ··· 824 619 return rc; 825 620 } 826 621 622 + /** 623 + * plpks_read_os_var() - Fetch the data for the specified variable that is 624 + * owned by the OS consumer. 625 + * @var: variable to be read from the PLPKS 626 + * 627 + * The consumer or the owner of the object is the os kernel. The 628 + * H_PKS_READ_OBJECT HCALL reads an object from the PLPKS. The caller must 629 + * allocate the buffer var->data and specify the length for this buffer in 630 + * var->datalen. If no buffer is provided, var->datalen will be populated with 631 + * the requested object's size. 632 + * 633 + * Possible reasons for the returned errno values: 634 + * 635 + * -ENXIO if PLPKS is not supported 636 + * -EIO if PLPKS access is blocked due to the LPAR's state 637 + * if an error occurred while processing the request 638 + * -EINVAL if invalid authorization parameter 639 + * if invalid object label parameter 640 + * if invalid object label len parameter 641 + * if invalid output data parameter 642 + * if invalid output data len parameter 643 + * -EPERM if access is denied 644 + * -ENOENT if the requested object was not found 645 + * -EFBIG if the requested object couldn't be 646 + * stored in the buffer provided 647 + * -EBUSY if unable to handle the request 648 + * 649 + * Returns: On success 0 is returned, a negative errno if not. 650 + */ 827 651 int plpks_read_os_var(struct plpks_var *var) 828 652 { 829 653 return plpks_read_var(PLPKS_OS_OWNER, var); 830 654 } 831 655 656 + /** 657 + * plpks_read_fw_var() - Fetch the data for the specified variable that is 658 + * owned by the firmware consumer. 659 + * @var: variable to be read from the PLPKS 660 + * 661 + * The consumer or the owner of the object is the firmware. The 662 + * H_PKS_READ_OBJECT HCALL reads an object from the PLPKS. The caller must 663 + * allocate the buffer var->data and specify the length for this buffer in 664 + * var->datalen. If no buffer is provided, var->datalen will be populated with 665 + * the requested object's size. 666 + * 667 + * Possible reasons for the returned errno values: 668 + * 669 + * -ENXIO if PLPKS is not supported 670 + * -EIO if PLPKS access is blocked due to the LPAR's state 671 + * if an error occurred while processing the request 672 + * -EINVAL if invalid authorization parameter 673 + * if invalid object label parameter 674 + * if invalid object label len parameter 675 + * if invalid output data parameter 676 + * if invalid output data len parameter 677 + * -EPERM if access is denied 678 + * -ENOENT if the requested object was not found 679 + * -EFBIG if the requested object couldn't be 680 + * stored in the buffer provided 681 + * -EBUSY if unable to handle the request 682 + * 683 + * Returns: On success 0 is returned, a negative errno if not. 684 + */ 832 685 int plpks_read_fw_var(struct plpks_var *var) 833 686 { 834 687 return plpks_read_var(PLPKS_FW_OWNER, var); 835 688 } 836 689 690 + /** 691 + * plpks_read_bootloader_var() - Fetch the data for the specified variable 692 + * owned by the bootloader consumer. 693 + * @var: variable to be read from the PLPKS 694 + * 695 + * The consumer or the owner of the object is the bootloader. The 696 + * H_PKS_READ_OBJECT HCALL reads an object from the PLPKS. The caller must 697 + * allocate the buffer var->data and specify the length for this buffer in 698 + * var->datalen. If no buffer is provided, var->datalen will be populated with 699 + * the requested object's size. 700 + * 701 + * Possible reasons for the returned errno values: 702 + * 703 + * -ENXIO if PLPKS is not supported 704 + * -EIO if PLPKS access is blocked due to the LPAR's state 705 + * if an error occurred while processing the request 706 + * -EINVAL if invalid authorization parameter 707 + * if invalid object label parameter 708 + * if invalid object label len parameter 709 + * if invalid output data parameter 710 + * if invalid output data len parameter 711 + * -EPERM if access is denied 712 + * -ENOENT if the requested object was not found 713 + * -EFBIG if the requested object couldn't be 714 + * stored in the buffer provided 715 + * -EBUSY if unable to handle the request 716 + * 717 + * Returns: On success 0 is returned, a negative errno if not. 718 + */ 837 719 int plpks_read_bootloader_var(struct plpks_var *var) 838 720 { 839 721 return plpks_read_var(PLPKS_BOOTLOADER_OWNER, var); 840 722 } 841 723 724 + /** 725 + * plpks_populate_fdt(): Populates the FDT with the PLPKS password to prepare 726 + * for kexec. 727 + * @fdt: pointer to the device tree blob 728 + * 729 + * Upon confirming the existence of the chosen node, invoke fdt_setprop to 730 + * populate the device tree with the PLPKS password in order to prepare for 731 + * kexec. 732 + * 733 + * Returns: On success 0 is returned, a negative value if not. 734 + */ 842 735 int plpks_populate_fdt(void *fdt) 843 736 { 844 737 int chosen_offset = fdt_path_offset(fdt, "/chosen"); ··· 950 647 return fdt_setprop(fdt, chosen_offset, "ibm,plpks-pw", ospassword, ospasswordlength); 951 648 } 952 649 953 - // Once a password is registered with the hypervisor it cannot be cleared without 954 - // rebooting the LPAR, so to keep using the PLPKS across kexec boots we need to 955 - // recover the previous password from the FDT. 956 - // 957 - // There are a few challenges here. We don't want the password to be visible to 958 - // users, so we need to clear it from the FDT. This has to be done in early boot. 959 - // Clearing it from the FDT would make the FDT's checksum invalid, so we have to 960 - // manually cause the checksum to be recalculated. 650 + /** 651 + * plpks_early_init_devtree() - Retrieves and clears the PLPKS password from the 652 + * DT in early init. 653 + * 654 + * Once a password is registered with the hypervisor it cannot be cleared 655 + * without rebooting the LPAR, so to keep using the PLPKS across kexec boots we 656 + * need to recover the previous password from the FDT. 657 + * 658 + * There are a few challenges here. We don't want the password to be visible to 659 + * users, so we need to clear it from the FDT. This has to be done in early 660 + * boot. Clearing it from the FDT would make the FDT's checksum invalid, so we 661 + * have to manually cause the checksum to be recalculated. 662 + */ 961 663 void __init plpks_early_init_devtree(void) 962 664 { 963 665 void *fdt = initial_boot_params;

Configure Feed

Configure Feed